Documentation Reading Experience

Publish a page into a documentation set and it arrives with a reading experience already attached. None of what follows is a setting, a plugin or a template you write. Two things on this page are yours to configure — the Starting Page that produces the home breadcrumb, and the menu order that produces previous and next — and everything else is derived from the set you have already built.

Breadcrumbs

Breadcrumbs are built from the reader’s position in the navigation tree: the folders above the page, then the page itself. Page items in between are not crumbs — only folders and the current page are, which is what keeps the trail short in a deep set.

A home crumb appears at the front only when the set has a Starting Page configured on its page type. This is the single most common reason breadcrumbs look truncated: the trail starts at the first folder because there is no home to point at. The field is on the same panel as the rest of the set’s configuration — see Documentation Configuration Reference.

Previous and next

The pager walks your navigation in reading order and skips folders, so it steps from the last page of one section straight into the first page of the next. Two consequences follow directly:

• The order is your menu’s order. Drag an item in the tree and you have reordered the reading path for every reader. Left Navigation Menu is where that order is set.
• A page that is not in the menu has no neighbors. It renders, it is reachable by URL and by search, and the pager simply does not include it.

A pager link pointing at a page you have not published yet loses its link and keeps its text, the same as any other internal reference — which is one more reason to publish a set whole rather than page by page. Linking Between Docs Pages covers that behavior in full.

On-page contents

The contents panel — headed On this page — is built from the page’s second- and third-level headings and tracks the reader’s scroll, marking the section they are in. Below the large breakpoint the same list moves into the bar above the content as a Jump to dropdown.

Navigation filter

Above the sidebar is a filter field — placeholder Filter menu… — that narrows the tree as the reader types. Matches inside collapsed folders are revealed rather than hidden, so a reader does not have to guess which section a page lives in.

Three details make it usable rather than merely present. It falls back to matching on a page’s URL when nothing matches by title, and says so in its screen-reader announcement (No title matches — 3 pages matched by link) rather than leaving someone hunting a highlight that is not there. It shows an explicit No matching pages when nothing matches at all, instead of an empty tree. And clearing it — with the clear button or the Escape key — restores the reader’s own expand and collapse state rather than resetting the tree.

The sidebar

The current page is marked, announced to assistive technology as the current page, and scrolled into view; its ancestors are opened; and its own link is inert, because it goes nowhere. A folder you marked Expanded in the menu editor opens by default for every reader.

Below the large breakpoint the sidebar becomes a drawer, opened from the mini bar at the top of the content.

Search

Ctrl + K opens search from anywhere on a documentation page, and Escape closes it — the modal carries the shortcut itself rather than the header button, so search still opens on a set whose custom header leaves the button out. Which pages it can find is a question about your search index, not about this page: see Search for Your Documentation.

Code, sections and images

Every fenced code block gets a copy button in its top corner, with a Copied! confirmation. This one is real — try it:

leed site build --serve

Every heading from the second to the fourth level gets a Copy link to section control that copies the page’s full URL with the heading’s anchor and puts it in the address bar. That control is also how an author gets an anchor slug: copy the link, take the fragment, and use it to deep-link a specific section from another page with pageid:<id>#anchor-slug.

Images inside the article body enlarge on click, unless the image is itself wrapped in a link — in that case the link wins, which is what you want for a thumbnail that leads somewhere. Mathematics is rendered as mathematics rather than left as source.

Diagrams enlarge too

A rendered diagram is click-to-zoom: it opens full screen over a dimmed backdrop with zoom controls, and clicking the diagram or pressing the close control returns you to the page.

flowchart LR
    A[Diagram in the reading column] -- click --> B[Full-screen stage]
    B -- zoom / pan --> B
    B -- click or close --> A

This changes what you may draw. A diagram no longer has to be fully legible at reading-column width, so it can carry the detail the subject actually needs rather than the detail that fits.

Overflowing tab strips

A tabbed example with more tabs than fit the column collapses into a dropdown rather than scrolling off the side of the page, and converts back when the window widens. This matters most on generated API pages, where the response-code strip can be long, but it applies to any tab container in the body.

Light and dark

The set follows the reader’s operating system appearance. Colors, code highlighting, diagram palettes and your dark logo variant all switch together, and a rendered diagram re-renders when the preference changes so it is themed for the scheme it is being read in.

What you configure, and what you do not

Which of these sit where on the page — search centered or grouped right, the footer inside the column or spanning the viewport — is a function of the layout you picked, described at Documentation Layouts. Everything a visitor gets on a page that is not part of a documentation set is at What Your Visitors Get.