DocsLayout
Documentation page layout with header hero, sticky table of contents, scrollspy, and a responsive content column.
01 Examples
Page-level layout, shown as code
Basic page
<DocsLayout
title="Badge"
description="Status and labels"
maxWidth="lg"
showToc
>
<Section marker id="examples" title="Examples">...</Section>
<Section marker id="api" title="API Reference">...</Section>
</DocsLayout>Collapsing hero with breadcrumbs
<DocsLayout
title="Combobox"
description="Searchable single-select input"
breadcrumbs={[
{ label: 'Blocks', href: '/blocks' },
{ label: 'Primitives', href: '/blocks/primitives' }
]}
stability="stable"
sourceHref="https://example.com/blob/main/Combobox.svelte"
showToc
>
<Section id="playground" title="Playground">...</Section>
</DocsLayout>02 Accessibility
The landmarks a page gets for free
The layout renders the page's <main>, the table of contents as a named <nav>, and the breadcrumb strip as a second one. A page built on it
therefore starts with a complete landmark set — which is why hand-rolling a breadcrumb row
instead of passing breadcrumbs costs more than the sticky bar.
Scroll-spy marks, it does not move focus
Scrolling sets aria-current="location" on the active table-of-contents link and
changes nothing else. Focus stays where the reader put it — dragging it along with the scroll
position would make the page unusable with a keyboard.
The collapsing hero keeps its heading
When the header scrolls away the compact bar takes over visually, but the page's <h1> stays in the document — the bar is a second presentation of it, not
a replacement. A screen reader still finds one, and only one, top-level heading.
Reader-controlled code visibility
The code toggle in the header is a real control with aria-pressed, and every CodeExample on the page follows it. Someone who reads code rather than previews
sets it once instead of expanding each example.
03 API Reference
16 propsProp | Type | Default | Description | |
|---|---|---|---|---|
breadcrumbs | BreadcrumbItem[] | — | Structured breadcrumb trail (ancestors only, title is appended automatically). A top-level page needs none — the strip then shows the title alone. | |
centered variant | true | false | Controls the centered behavior and appearance of the DocsLayout component. Available options: true. | |
children | Snippet | — | Page body content. | |
class | string | — | Extra classes merged onto the root container. | |
description | string | — | Short description rendered below the title. | |
maxWidth variant | smmdlgxl +2 more | lg | Controls the maxWidth behavior and appearance of the DocsLayout component. Available options: sm, md, lg, and 3 more. | |
related | RelatedLink[] | — | Optional related-links list — passed through to the TableOfContents
as a // RELATED block below the page sections. Each entry needs a
pre-resolved href; the layout does not call resolve() on it. | |
showCodeToggle | boolean | true | Show the global code-visibility toggle for collapsing all code examples. | |
showToc | boolean | false | Show a table of contents built from the page's titled <Section>s: the
sticky rail on desktop, a popover in the pinned strip below lg. Both
halves follow this one prop, so switching it off leaves neither behind;
a page without a titled section shows neither. | |
sidebar variant | true | false | Controls the sidebar behavior and appearance of the DocsLayout component. Available options: true. | |
slotClasses | Partial<Record<DocsLayoutSlots, string>> | — | Per-slot class overrides. | |
sourceHref | string | — | GitHub blob URL for the component's source file — rendered as a
source ↗ link next to the stability badge when present. | |
stability | experimentalbetastabledeprecated | — | Editorial stability badge — drives the [STABLE] / [BETA] / etc.
stamp above the page title. When omitted, no badge renders; the
default is applied upstream in docs-gen, so component pages
receive 'stable' automatically via componentData?.stability. | |
title | string | — | Page title rendered as an h1 in the header area. | |
unstyled | boolean | false | Remove all default tv styles. | |
...DocsLayoutVariantProps variant | VariantProps | — | Styling variants from DocsLayoutVariantProps |
04 Types
Name | Kind | Category | Used by | Description | |
|---|---|---|---|---|---|
BreadcrumbItem | interface | helper | 1 | — | |
DocsLayoutProps | interface | props | — | Standard documentation page layout with optional table of contents.
Provides a responsive two-column layout: a rail on desktop, a popover in the
pinned strip below it.
The strip renders whenever it has something to carry — a title or
breadcrumbs (shown as a trail), a sourceHref, or the mobile table of
contents. It stays pinned for the whole scroll, and the hero title morphs
into its last crumb once the header scrolls out of view.
Anchor jumps land clear of it: the strip publishes its height, and every
<Section> reads the resulting --docs-anchor-offset as its scroll margin.
The table of contents is the page's own outline: every <Section> with a
title registers with the layout as it renders, and the TOC lists them in
render order under their headings. A section nested in a titled one becomes
a child entry; one shown inside a CodeExample or PlaygroundConfigurator
stage stays out. | |
DocsLayoutVariantProps | type | variant | 1 | — | |
DocsLayoutSlots | type | variant | — | The slot names slotClasses accepts. | |
RelatedLink | interface | helper | 1 | — | |
TocNavigationItem | interface | helper | — | A single entry in the table of contents. The list renders in array order.
DocsLayout builds these from the sections its page renders; a standalone
TableOfContents takes them as written. |
05 Installation
Import
import { DocsLayout } from '@urbicon-ui/docs';