Known Limitations

It is better for you to read that something does not work than to spend an afternoon proving it. Every entry below says what happens, what it looks like from where you are sitting, and what to do instead. Entries leave this page when they are fixed.

How to read an entry

Three conventions hold for every row and every section.

Each entry is named by the symptom you would see, not by its internal cause. If you are scanning, scan the first column.

Workaround is a real instruction or the words “None today”. It is never a hedge. “Consider restructuring your content” is not a workaround and does not appear here.

A limitation is not a plan gate and not a fixed ceiling. Both of those have their own pages, linked once in the note above and not repeated.

Writing and formatting

These are round-trip and editor defects: the content survives, one detail of it does not.

A numbered list restarts at 1

Set a numbered list to start at 14 in the editor and it looks right in the editor. On the published site it starts at 1. The editor serializes the start number as a bare value while the site’s markdown parser only recognizes a quoted one, so the attribute is dropped on the way through and the list falls back to the default.

Workaround: none today. If the numbering matters — a continued procedure, a numbered requirement — write the number into the item text rather than relying on the list’s start value.

Table column alignment is lost

Leed Markdown carries column alignment the way markdown always has, with colons in the header separator. The editor’s document model does not carry it, so alignment is dropped the first time the page is saved from the editor.

Workaround: alignment authored in Leed Markdown and written through an import or an MCP client survives until someone opens the page in the editor and saves it. There is no way to set or preserve alignment from the editor itself. The rest of what the editor does and does not carry across a round trip is described from the format’s side at Fidelity and Unsupported Syntax.

A colored icon can emit invalid markup

An icon’s parameters are emitted straight into the rendered element’s class list. A color, which is written as color="…", therefore lands inside a quoted attribute value — and the quotes collide. The resulting markup is malformed, and how a browser recovers from it is not something you can rely on.

Workaround: leave icon color unset and let the icon inherit the surrounding text color, or color it with a class instead.

Nested tabs mis-parse

A tab group inside another tab group is not read as a child of the outer group. The inner tabs are flattened into siblings of the outer ones and the text that was around them appears loose in the container.

Workaround: do not nest tab groups. If you need two axes, put one of them in a table.

Markdown containing raw HTML is rejected on import

Leed’s markdown parser understands a short list of inline tags because the editor itself emits them — line breaks, superscript and subscript. Everything else is a parse failure, and a parse failure fails the whole write. This does not affect typing in the editor; it affects markdown arriving from an AI client, an import, or the MCP page tools.

Workaround: convert the HTML to Leed Markdown before writing. Almost everything an importer reaches for has a Leed Markdown equivalent — Fidelity and Unsupported Syntax maps them.

Written by the editor:   1. Item 14 {start=14}
Read by the site parser: 1. Item 14 {start="14"}

{% icon fa-solid fa-star lg color="#ff0000" %}

Could not parse the provided markdown

Tabs that look right and are not

Three defects share one property: the page renders, nothing errors, and the reader is the one who pays. You will not see any of these while you are authoring — which is exactly why they are here.

Lower-case groupid silently loses your titles and icons

Your tabs render. They still switch. They still sync across pages. They just show the labels you typed instead of the group’s display titles, and they carry no icons. Nothing warns you, and nothing looks broken unless you know what the group was supposed to look like.

The cause is a single character: the build matches the literal attribute data-tabs-groupId, with a capital I. Written as data-tabs-groupid the browser still finds the attribute — HTML attribute names are case-insensitive at runtime — so switching and syncing keep working, while the build-time lookup that supplies titles and icons misses entirely.

Workaround: write the capital I. Tab Groups for Consistent Examples has the rules that avoid all three of these entries, and Tabs has the syntax.

An ungrouped tab container inherits the previous group’s styling

Put a grouped tab container on a page, then a plain one below it, and the plain one picks up the first one’s display titles and icons. It looks grouped. It is not: it emits no group attribute of its own, so it does not sync with anything and a reader’s choice on it is forgotten immediately.

The parser records the group id of each container it sees and never clears it, so an unbound container simply keeps whatever was set last.

Workaround: bind every tab container on a page to a group id, including one-off ones. A container that belongs to no shared axis still needs its own unique id.

A reader is switched to the wrong tab across pages

Tab choices follow a reader from page to page, which is the point of a tab group. The choice is stored as a position, not as a tab name. So if two containers in the same group hold different tabs, a different number of tabs, or the same tabs in a different order, a reader who picked the third tab on one page lands on whatever happens to be third on the next — or on nothing at all, if that container has fewer tabs.

Themes and code themes that do not apply

Two entries with sharply different symptoms, which is the reason they are documented together. A color theme that fails to load falls through to your site’s own palette, so the page merely looks un-branded. A code theme that fails to load has nothing to fall through to, so your code blocks ship with no colors at all.

Three Gruvbox code themes do nothing

code-theme-gruvbox-hard, code-theme-gruvbox-medium and code-theme-gruvbox-soft are all offered in the code-theme picker. The stylesheets that ship for them declare a misspelled name, so selecting one emits a class with no rule behind it. The result is not a fallback to a different theme — it is code with no syntax coloring at all, on every page of the set.

Workaround: pick any other built-in code theme, or author your own. Custom Documentation Themes covers both.

A built-in theme does not color everything

Choosing one of the built-in color themes sets the palette a docs site is judged on — the accent, the grounds, the borders, the sidebar and the search chrome. It does not set heading colors, the active link color, the inline maths color or the menu ground. Those fall through to your site’s own tokens by design, so a docs set inherits the typography of the site it belongs to rather than overriding it.

The consequence is that a stock built-in theme looks less “themed” than a custom one. That is not a fault; it is the fallback chain doing its job.

Workaround: if you want the headings in the accent color, that is a custom theme — the tokens are read, they are just not set by the built-ins. Custom Documentation Themes names each one.

Navigation and links in the CMS

Three cosmetic and navigational defects, each with a one-line answer.

The second of these has a small tail worth knowing about: the same lookup that highlights a rail tab also records where you were last. Because a documentation page matches nothing, that visit is not remembered — so clicking Design afterwards returns you to whatever page you were on before, not to the documentation set you were just editing.

Surfaces that store a plan and do not execute it

Three surfaces persist real settings and then stop. What they save is real and shareable; what they do not do is deliver anything.

For each of these, be clear about what is real. The Workflows tab genuinely stores per-page channel settings and their on-page toggles, and they persist across publishes — Page Workflows and Release Notes and Auto-Posting describe exactly what is recorded. Campaigns genuinely hold a plan, a schedule and an approval state, and the calendar shows them — Campaigns and Deliverables. Neither of them delivers.

Surfaces that render empty on purpose

An empty screen means one of two things and you cannot tell them apart by looking: either you have no data yet, or there is no source behind the widget. These are the second kind.

Which Know widgets have a real source, and what each one counts, is enumerated at Know Widgets Reference. The asset placeholder appears on every asset regardless of kind — Asset Details and Usage.

Things that fail without telling you

The two most expensive entries on this page. Both look like success.

Configuration that does not do what it says

Four settings that accept a value and then do not use it, or do not use it where you expect.

The highlighter entry is the one likely to cost you time, because there are two keys with the same name at two levels. Extra syntax languages are read from the top level of your site data, not from inside the documentation configuration block, and each language additionally needs its matching highlighter file in the repository — a missing file logs a build warning and is skipped rather than failing the build. Documentation Configuration Reference marks the key that is read and the one that is not.

A hard-bounced contact is a related case with no entry of its own: once an address is recorded as hard-bounced, nothing in the CMS clears that flag, so a fixed address stays suppressed. Bounces and Deliverability explains what a hard bounce means for the rest of your list.

What we do with this list

Every entry here is handed to engineering, and this page is edited when a fix ships rather than left to accumulate. That is not a claim about a roadmap — it is how the page is maintained. One entry has already left it: a link to a specific heading on another page used to lose its anchor at build time, and now it does not, so the row is gone rather than being demoted to “fixed”.

If you have hit something that belongs here, use the feedback control in the CMS rail. A symptom you cannot find on this page may be a plan gate, a fixed ceiling, or something Leed simply does not have — Troubleshooting Index routes all three, and capabilities that were never built rather than built-and-broken are at What Leed Does Not Do. A setting you cannot find in the CMS at all is probably named at Settings You Will Not Find.