Documentation layout

Task#

Use this pattern for brand documentation that needs persistent orientation without sacrificing horizontal reading space. It helps a reader understand where a page lives, read the page in one main flow, and continue to a deliberately related page.

Composition#

The layout combines the Documentation sidebar, Breadcrumbs, a documentation title block, article content, and optional Related posts. The docs shell owns their order and width; each component retains its own behavioural contract.

Content and data#

The sidebar reads the bilingual documentation tree from Hugo sections and pages. Each page supplies standard front matter—title, description, date, and lastmod—for its title block, indexes, and related rows. Add related: only when a reader has a meaningful next destination; do not use it as a general tag list.

Responsive behaviour#

On wider screens the documentation sidebar occupies the left rail and the article receives the remaining reading width. At smaller sizes the rail becomes part of the normal document flow and remains available before the article. There is intentionally no persistent right-side table of contents.

Implementation#

layouts/partials/docs/shell.html composes the shell once for the documentation section. It provides the sections and current page to the sidebar, emits breadcrumbs before the article, renders the title block and content, then places related pages at the end. The sidebar uses native disclosure elements and a small script only to prevent a section link inside its summary from toggling the disclosure accidentally.

Accessibility#

• The sidebar and breadcrumb are distinct named navigation landmarks; neither replaces the other.
• The article remains one main reading flow, with no right-side table of contents competing for width or focus.
• The sidebar uses native <details> and <summary> for disclosure, and the current page uses aria-current="page".
• Breadcrumbs use an ordered list and a non-linked current-page item. Related pages are ordinary links inside a named complementary region.
• At narrow widths, source order keeps orientation tools available before article content instead of relying on a visual-only rearrangement.