Skip to content
AnvilBase

Publishing These Docs

These pages are written as portable Markdown with YAML frontmatter (title + description on every page). That frontmatter is understood by every mainstream documentation engine, so you can render this folder with whatever you choose later without rewriting content. This page records the recommendation and gives you drop-in navigation config for the most common engines.

Recommendation: Starlight on Astro

For AnvilBase specifically, Starlight on Astro is the best fit:

RequirementHow Starlight meets it
Full-text page index / searchShips Pagefind out of the box — a static, zero-infra search index generated at build time. This is exactly the “pageindex” capability you asked for.
Markdown + MDXRenders .md and .mdx natively; our frontmatter (title, description) maps directly to Starlight’s schema.
Tabbed multi-language code samples<Tabs> / <TabItem> components — ideal for our curl / TS / Python / Dart snippets.
Auto-generated sidebarCan auto-derive the sidebar from the folder tree, or use the explicit config below.
Self-hostable, no SaaSStatic output — deploys to any static host (Netlify, Cloudflare Pages, S3+CDN, nginx). Matches AnvilBase’s self-host ethos.
Versioned docsVia the community starlight-versions plugin when you start shipping breaking changes.
License/costMIT, free.

Alternatives, depending on your priorities:

  • Mintlify — hosted, beautiful defaults, great API playground. Best if you want a managed service and an interactive “try it” console. Uses docs.json.
  • Docusaurus — React-based, huge plugin ecosystem, Algolia DocSearch. Heavier but extremely extensible.
  • Docsify — zero-build, renders Markdown at runtime in the browser. Lowest effort; weaker search and no SSG/SEO.
  • README.com — if you specifically want the ReadMe platform, import this folder; the frontmatter and relative links transfer cleanly.

If you have no strong reason to pick something else, use Starlight.

Quickstart: render this folder with Starlight

Terminal window
# Scaffold a Starlight site next to your repo
npm create astro@latest anvilbase-docs -- --template starlight --typescript strict --no-install
cd anvilbase-docs
npm install


# Point Starlight at this docs folder (symlink or copy)
ln -s ../anvilbase/docs src/content/docs
npm run dev          # http://localhost:4321
npm run build        # static site in ./dist (Pagefind index included)

Then paste the sidebar config below into astro.config.mjs.

Starlight sidebar (astro.config.mjs)

import { defineConfig } from 'astro/config';
import starlight from '@astrojs/starlight';


export default defineConfig({
  integrations: [
    starlight({
      title: 'AnvilBase',
      tagline: 'Forged for your infrastructure.',
      social: { github: 'https://github.com/paxtone-studio/anvilbase' },
      sidebar: [
        { label: 'Introduction', autogenerate: { directory: 'introduction' } },
        { label: 'Getting Started', autogenerate: { directory: 'getting-started' } },
        { label: 'Database', autogenerate: { directory: 'database' } },
        { label: 'REST API', autogenerate: { directory: 'rest-api' } },
        { label: 'Auth', autogenerate: { directory: 'auth' } },
        { label: 'Realtime', autogenerate: { directory: 'realtime' } },
        { label: 'Storage', autogenerate: { directory: 'storage' } },
        { label: 'Edge Functions', autogenerate: { directory: 'functions' } },
        { label: 'Platform Features', autogenerate: { directory: 'guides' } },
        { label: 'Security', autogenerate: { directory: 'security' } },
        { label: 'eIDAS 2.0', autogenerate: { directory: 'eidas' } },
        { label: 'Self-Hosting', autogenerate: { directory: 'self-hosting' } },
        { label: 'CLI', autogenerate: { directory: 'cli' } },
        { label: 'Tools', autogenerate: { directory: 'tools' } },
        { label: 'Reference', autogenerate: { directory: 'reference' } },
      ],
    }),
  ],
});

Ordering tip: Starlight orders auto-generated pages alphabetically unless you add a sidebar: { order: N } key to each page’s frontmatter. The pages in this repo are deliberately named so that the natural reading order is close to alphabetical within each section; add explicit order values if you want exact control.

Mintlify (docs.json navigation)

{
  "name": "AnvilBase",
  "navigation": {
    "groups": [
      { "group": "Introduction", "pages": ["introduction/overview", "introduction/why-anvilbase", "introduction/architecture", "introduction/concepts"] },
      { "group": "Getting Started", "pages": ["getting-started/installation", "getting-started/quickstart", "getting-started/first-project", "getting-started/connect-your-app"] },
      { "group": "Database", "pages": ["database/overview", "database/tables-and-schema", "database/sql-editor", "database/extensions", "database/vector-search", "database/migrations"] },
      { "group": "REST API", "pages": ["rest-api/overview", "rest-api/reading-data", "rest-api/modifying-data", "rest-api/rpc"] },
      { "group": "Auth", "pages": ["auth/overview", "auth/users-and-sessions", "auth/oauth-providers", "auth/email-and-templates"] },
      { "group": "Realtime", "pages": ["realtime/overview", "realtime/postgres-changes", "realtime/broadcast-and-presence"] },
      { "group": "Storage", "pages": ["storage/overview", "storage/working-with-objects", "storage/image-transformations"] },
      { "group": "Edge Functions", "pages": ["functions/overview", "functions/writing-and-deploying"] },
      { "group": "Platform Features", "pages": ["guides/queues", "guides/cache", "guides/cron-and-scheduling", "guides/webhooks", "guides/secrets"] },
      { "group": "Security", "pages": ["security/overview", "security/row-level-security", "security/api-keys-and-scopes", "security/multi-tenancy", "security/rbac-and-team", "security/encryption", "security/audit-logs", "security/network-security"] },
      { "group": "eIDAS 2.0", "pages": ["eidas/overview", "eidas/verifier", "eidas/issuer"] },
      { "group": "Self-Hosting", "pages": ["self-hosting/overview", "self-hosting/docker-compose", "self-hosting/kubernetes", "self-hosting/configuration", "self-hosting/production-checklist", "self-hosting/backups-and-restore", "self-hosting/point-in-time-recovery", "self-hosting/monitoring", "self-hosting/scaling", "self-hosting/upgrades", "self-hosting/disaster-recovery"] },
      { "group": "CLI", "pages": ["cli/reference"] },
      { "group": "Tools", "pages": ["tools/mcp", "tools/sdk-compatibility", "tools/migrate-from-supabase"] },
      { "group": "Reference", "pages": ["reference/management-api", "reference/data-plane-api", "reference/rest-query-syntax", "reference/configuration", "reference/ports", "reference/error-codes", "reference/glossary"] }
    ]
  }
}

Docusaurus / Docsify

  • Docusaurus — drop the folders into docs/, enable @docusaurus/preset-classic with docs.routeBasePath: '/', and either let it auto-generate the sidebar (sidebars: [{type: 'autogenerated', dirName: '.'}]) or transcribe the groups above. Use @docusaurus/theme-search-algolia or the local @easyops-cn/docusaurus-search-local plugin for the page index.
  • Docsify — add an _sidebar.md mirroring the documentation map, set loadSidebar: true, and enable the search plugin for client-side indexing.

Authoring conventions to preserve portability

If you keep extending these docs, stay engine-agnostic:

  1. Every page starts with frontmatter containing title and description.
  2. Use relative links between pages (../auth/overview.md) — they resolve in every engine and on GitHub.
  3. Keep code fences language-tagged (```ts, ```python, ```bash) so syntax highlighting and Pagefind code search work everywhere.
  4. Prefer plain Markdown tables and admonition-style blockquotes over engine-specific components in the body. If you adopt Starlight and want its :::note asides or <Tabs>, add them as an enhancement layer — the plain Markdown still renders fine if you switch engines later.