Skip to content
Mementropy Docs

How This Site Is Structured

Why the structure looks like this

Section titled “Why the structure looks like this”

The shape is simple on purpose.

This site started from two inputs:

  1. the high-level topics visible in catalyst-ops
  2. the official Starlight authoring patterns for content, frontmatter, and components

That led to a docs tree with a few distinct jobs:

  • foundations/ for enduring concepts
  • architecture/ for system framing and portability ideas
  • runbooks/ for repeatable operational steps
  • reference/ for terse lookup pages
  • examples/ for Starlight feature demos
  • authoring/ for the notes that help future-you keep writing

Markdown first, MDX when it helps

Section titled “Markdown first, MDX when it helps”

Use Markdown

Reach for plain .md when the page is mostly headings, lists, notes, tables, and code fences. That will be most pages.

Use MDX

Switch to .mdx when you want imported Starlight components like cards, tabs, steps, file trees, or buttons and they genuinely improve the page.

Current docs tree

Section titled “Current docs tree”
  • Directorysrc/
    • Directorycontent/
      • Directorydocs/
        • index.mdx
        • Directoryauthoring/
          • how-this-site-is-structured.mdx
          • page-templates.mdx
        • Directoryfoundations/
          • ai-operating-model.mdx
        • Directoryarchitecture/
          • platform-overview.mdx
          • provider-portability-boundary.mdx
          • migration-assurance.mdx
          • service-delivery-method.mdx
        • Directoryrunbooks/
          • publish-docs.mdx
          • new-runbook-template.md
        • Directorydeploy/
          • cloudflare-static.mdx
          • protect-docs-with-access.mdx
        • Directoryreference/
          • glossary.md
          • frontmatter-patterns.md
          • launch-checklist.md
        • Directoryexamples/
          • starlight-patterns.mdx

How to add the next page

Section titled “How to add the next page”
  1. Decide whether the page is a foundation, architecture note, runbook, reference page, or example.
  2. Start from the closest template in /authoring/page-templates/.
  3. Keep the first draft short and honest about what is still fuzzy.
  4. Add the page to the matching sidebar group in astro.config.mjs.
  5. Only introduce MDX components when they genuinely improve readability.

Naming advice that will age well

Section titled “Naming advice that will age well”
  • Prefer names that reflect the reader’s question, not your internal file chronology.
  • Keep one main idea per page.
  • If a topic is broad, start with a framing page and split the details later.
  • Use runbooks for action, reference pages for lookup, and architecture pages for models and tradeoffs.