Starlight Patterns

Asides

Note

Use asides for supporting information that helps the reader without hijacking the page.

Prefer restraint

Most pages do not need every component. Reach for them when they improve the read, not when the page merely feels a little too plain.

Badges, icons, and buttons

stub private ready

Small icon accents work best when they support nearby text instead of carrying the whole message.

Open page templates

Cards and link cards

Use cards for summaries

Cards work well for short concept summaries, feature overviews, and landing-page navigation.

Cloudflare static deploy Keep deployment simple and fully static on Cloudflare Pages.

Protect docs with Access Put identity in front of docs.mementropy.com before the site starts circulating.

Tabs

Markdown

Use Markdown for most pages.

- headings
- lists
- code fences
- tables
- asides

MDX

Use MDX when you need imported components:

- cards
- tabs
- steps
- file trees

Steps

1. Create a file in the right directory.
2. Add useful frontmatter.
3. Write the shortest page that still says something real.
4. Add the page to the sidebar.
5. Build before you deploy.

File tree

• Directorysrc/

  • Directorycontent/

    • Directorydocs/

      • Directoryauthoring/

        • …
      • Directoryfoundations/

        • …
      • Directoryarchitecture/

        • …
      • Directoryrunbooks/

        • …
      • Directorydeploy/

        • …
      • Directoryreference/

        • …
      • Directoryexamples/

        • …
• astro.config.mjs
• wrangler.jsonc
• .nvmrc

Code block component

astro.config.mjs

// @ts-check
import { defineConfig } from "astro/config";
import starlight from "@astrojs/starlight";

// https://astro.build/config
export default defineConfig({
  site: "https://docs.mementropy.com",

  integrations: [
    starlight({
      title: "Mementropy Docs",
      description:
        "Stub documentation for AI, ML, and operations work, built with Astro Starlight.",
      customCss: ["./src/styles/custom.css"],
      disable404Route: true,
      sidebar: [
        { label: "Home", link: "/" },
        {
          label: "Start Here",
          items: [
            { label: "Getting Started", slug: "guides/getting-started" },
            {
              label: "How This Site Is Structured",
              slug: "authoring/how-this-site-is-structured",
            },
            { label: "Page Templates", slug: "authoring/page-templates" },
          ],
        },
        {
          label: "Foundations",
          items: [
            {
              label: "AI Operating Model",
              slug: "foundations/ai-operating-model",
            },
          ],
        },
        {
          label: "Architecture",
          items: [
            {
              label: "Platform Overview",
              slug: "architecture/platform-overview",
            },
            {
              label: "Provider Portability Boundary",
              slug: "architecture/provider-portability-boundary",
            },
            {
              label: "Migration Assurance",
              slug: "architecture/migration-assurance",
            },
            {
              label: "Service Delivery Method",
              slug: "architecture/service-delivery-method",
            },
          ],
        },
        {
          label: "Runbooks",
          items: [
            { label: "Publish Docs", slug: "runbooks/publish-docs" },
            {
              label: "New Runbook Template",
              slug: "runbooks/new-runbook-template",
            },
          ],
        },
        {
          label: "Deploy",
          items: [
            {
              label: "Cloudflare Static Deploy",
              slug: "deploy/cloudflare-static",
            },
            {
              label: "Protect Docs With Access",
              slug: "deploy/protect-docs-with-access",
            },
          ],
        },
        {
          label: "Reference",
          items: [
            { label: "Glossary", slug: "reference/glossary" },
            {
              label: "Frontmatter Patterns",
              slug: "reference/frontmatter-patterns",
            },
            {
              label: "Launch Checklist",
              slug: "reference/launch-checklist",
            },
          ],
        },
        {
          label: "Examples",
          items: [
            {
              label: "Starlight Patterns",
              slug: "examples/starlight-patterns",
            },
          ],
        },
      ],
    }),
  ],
});

When to stop

If a page already reads well in plain Markdown, stop there. The best Starlight pages usually feel clear and calm rather than component-heavy.