DocsShell

Code

import { useState } from "react";import { DocsShell } from "@fadymondy/nasaq/web";const nav = [  { id: "intro", title: "Introduction" },  { id: "guides", title: "Guides", children: [{ id: "install", title: "Installation" }] },];const pages = {  intro: { id: "intro", title: "Introduction", markdown: "## Why\n\nText.\n\n> [!TIP]\n> Start small." },  install: { id: "install", title: "Installation", markdown: "## Install\n\nRun `pnpm add`." },};export function Docs() {  const [id, setId] = useState<keyof typeof pages>("intro");  return <DocsShell nav={nav} page={pages[id]} onNavigate={(next) => setId(next as keyof typeof pages)} brand="Nasaq Docs" />;}

Layout · beta

Live examples and controls: DocsShell in the lab.

InstallCopy Anchor Link

npx shadcn@latest add https://docs.nasaqui.com/r/docs-shell.json

The frame of a documentation site. A top bar, a tree of pages on the side (a drawer on phones) with a filter, and the page itself: breadcrumb, title, a "Copy page" button that puts the page on the clipboard as Markdown, the body with callouts, an "On this page" rail that highlights the heading you are reading, and previous and next links. It shows the page you pass and calls onNavigate; routing is yours.

The body is rendered by the blog's PostBody, and the rail is the blog's TableOfContents with useActiveHeading.

When to useCopy Anchor Link

• Product documentation, guides and API references written in Markdown.
• Any multi-page reading experience with a tree of pages.

When not to useCopy Anchor Link

• A single article: use blog-post.
• App navigation: use SidebarLayout or AppShell.
• Terms and privacy pages: use legal-page.

ImportCopy Anchor Link

import { DocsShell } from "@fadymondy/nasaq/web";
// inside this monorepo: "@nasaq/web"

Quick startCopy Anchor Link

import { useState } from "react";
import { DocsShell } from "@fadymondy/nasaq/web";

const nav = [
  { id: "intro", title: "Introduction" },
  { id: "guides", title: "Guides", children: [{ id: "install", title: "Installation" }] },
];
const pages = {
  intro: { id: "intro", title: "Introduction", markdown: "## Why\n\nText.\n\n> [!TIP]\n> Start small." },
  install: { id: "install", title: "Installation", markdown: "## Install\n\nRun `pnpm add`." },
};

export function Docs() {
  const [id, setId] = useState<keyof typeof pages>("intro");
  return <DocsShell nav={nav} page={pages[id]} onNavigate={(next) => setId(next as keyof typeof pages)} brand="Nasaq Docs" />;
}

AnatomyCopy Anchor Link

DocsShell             data-slot="docs-shell"
├─ top bar            brand, menu button (phones), actions
├─ sidebar            data-slot="docs-sidebar"  filter + TreeView (Sheet on phones)
├─ article
│   ├─ Breadcrumb
│   ├─ title + CopyButton
│   ├─ "On this page" (collapsed, below the xl breakpoint)
│   ├─ body           data-slot="docs-body"  PostBody
│   ├─ updated date and edit link
│   └─ previous / next
└─ rail               data-slot="docs-toc"  TableOfContents

APICopy Anchor Link

HelpersCopy Anchor Link

Pure and exported: docsPages, docsTrail, docsAncestorIds, docsPrevNext, filterDocsTree, docsSectionIds, docsPageMarkdown.

ExamplesCopy Anchor Link

<DocsShell nav={nav} page={page} onNavigate={go} renderBody={(p) => <RichMarkdown>{p.markdown}</RichMarkdown>} />

<DocsShell nav={nav} page={{ ...page, updated: "2026-09-12", editHref: "https://github.com/acme/docs/edit/main/x.md" }} onNavigate={go} actions={<ThemeSwitch />} />

Callouts are written in the Markdown as > [!NOTE], > [!TIP], > [!IMPORTANT], > [!WARNING] or > [!CAUTION].

AccessibilityCopy Anchor Link

• The sidebar is a nav with a tree; the current page is selected. The rail marks the current heading with aria-current="location".
• The drawer on phones is a modal with a title, and closes after a page is chosen.
• Filtering shows a message when nothing matches.

RTL & i18nCopy Anchor Link

• The sidebar sits on the reading start side and the rail on the end side; arrows and the tree keys follow the direction.
• Titles and headings use dir="auto". Code blocks stay left-to-right.
• Previous and next chevrons mirror.

Styling & tokensCopy Anchor Link

Uses the surface, border, selected and focus tokens. Target data-slot of the parts. The sidebar shows from the lg breakpoint and the rail from xl.

Do / Don'tCopy Anchor Link

• Do give every page a stable id and keep the tree shallow (two or three levels).
• Do write ## and ### headings so the rail has something to show.
• Don't nest the shell inside another sticky header. It manages its own.

RelatedCopy Anchor Link

• blog-post, tree-view, markdown, legal-page

LabCopy Anchor Link

https://docs.nasaqui.com/?path=/docs/components-layout-docs-shell--docs