Skip to content
Blocks

Docs site

This site is a pattern, not a bespoke build: the chassis lives in @gridd/ui, and a new docs site — an API reference, an operator handbook — is an app.config and a folder of pages.

What the layer ships

Extending @gridd/ui gives an app the whole documentation chassis. Nothing below is written twice.

  • The docs layout — navbar, nav rail, drawer below 1200px, ⌘K palette, theme control, and the app-frame scroll contract.
  • GdDocsPage — the full-bleed page header band plus the body column, and the contents-rail registration.
  • GdDocsSection — an anchored section: heading, lede, prose at the measure.
  • GdDocsSpecimen — the live-example frame. Live is the point: it renders the real component, so the docs cannot drift from the code.
  • GdDocsSearch — the palette. The nav indexes every page for free; searchExtras adds anchors and the words people actually type.
  • Head hygiene — the standfirst becomes the meta description, the theme is stamped before first paint, and the layout links /favicon.svg: the app ships the file, because the chassis must not impose a brand on every consumer.

The recipe

Three files. The nav is the one place a page is listed — prerendering crawls links, so listing a route is what publishes it.

1 · Declare the content

// app/app.config.ts
export default defineAppConfig({
  griddDocs: {
    brand: "API",                    // the wordmark suffix
    siteTitle: "GRIDD API Reference", // the <title> suffix
    nav: NAV,                        // GdNavSection[] — sections, items, children
    searchExtras: SEARCH_EXTRAS      // GdDocsSearchEntry[] — in-page anchors + synonyms
  }
})

2 · Opt into the layout

<!-- app/app.vue -->
<template>
  <div>
    <a class="gd-skip-link" href="#content">Skip to content</a>
    <NuxtLayout name="docs">
      <NuxtPage />
    </NuxtLayout>
  </div>
</template>

3 · Write pages

<!-- app/pages/endpoints/parcels.vue -->
<GdDocsPage eyebrow="Endpoints" title="Parcels" standfirst="…" :toc="TOC">
  <GdDocsSection id="request" title="Request">
    <p>Prose at the measure.</p>
    <GdDocsSpecimen label="…" note="…">
      <!-- live components -->
    </GdDocsSpecimen>
  </GdDocsSection>
</GdDocsPage>

What you get

The behaviours are the pattern — every one of them was earned here, and a new site inherits them without re-learning why.

  • App-frame scrolling — at 1200px and up the document never scrolls; the middle column does, and the rails hold still.
  • A contents rail that tracks reading — computed from scroll position against a reading line, so it works at the top, the bottom, and on short pages.
  • A breakpoint that is watched, not assumed — crossing up closes the drawer instead of stranding it over the rail.
  • ⌘K anywhere — the palette listens globally and the rail's search control is the visible way in.
  • Three-state theme — system by default; light and dark pin data-gd-theme and native chrome follows via color-scheme.
  • One grid — --gd-docs-column and --gd-docs-gutter put the header's words, the prose and the specimens on the same left edge.

Navigate

Esc