DocsKnowledge base

Starlight Patterns

Compact examples of the Starlight components and page patterns worth keeping around.

Asides

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 deployKeep deployment simple and fully static on Cloudflare Pages.

Protect Admin with AccessKeep the public lanes open while protecting the standalone Admin host.

Use Markdown for most pages.

- headings
- lists
- code fences
- tables
- asides

Use MDX when you need imported components:

- cards
- tabs
- steps
- file trees

Steps

Create a file in the right directory.
Add useful frontmatter.
Write the shortest page that still says something real.
Add the page to the sidebar.
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

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

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

  integrations: [
    sitemap(),
    starlight({
      title: "Mementropy",
      description:
        "Working notes, study tracks, and longer-form writing on AI, ML, and operations work.",
      social: [
        {
          icon: "github",
          label: "GitHub",
          href: "https://github.com/apd-rhammang",
        },
      ],
      credits: false,
      customCss: ["./src/styles/custom.css"],
      disable404Route: true,
      // Sidebar entries are computed per-request by routeMiddleware based on
      // URL section (academy/blog/whitepapers/docs). The default sidebar
      // here is the fallback for pages that don't match any section.
      sidebar: [],
      routeMiddleware: "./src/lib/routeData.ts",
      components: {
        Header: "./src/components/overrides/Header.astro",
        PageTitle: "./src/components/overrides/PageTitle.astro",
        Sidebar: "./src/components/overrides/Sidebar.astro",
      },
    }),
  ],
});

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.