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://mementropy.com",

  integrations: [
    starlight({
      title: "Mementropy",
      description:
        "Working notes, study tracks, and longer-form writing on AI, ML, and operations work.",
      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",
      },
    }),
  ],
});

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.