Project structure

One mental model covers all navigation in Fiskil Docs:

content/docs/{product}/{section}/{page}.mdx  →  /{product}/{section}/{page}

Products are the top-level switcher (declared in docs.json). Sections are the tab row within a product — and they're just folders. Everything inside a section is that section's sidebar.

A complete example

content/docs/
├── index.mdx                      → /            (your landing page)
└── payments/                      → the "payments" product
    ├── meta.json                  → section order for this product
    ├── guides/                    → /payments/guides/...
    │   ├── meta.json
    │   ├── index.mdx              → /payments/guides
    │   └── getting-started/
    │       └── quickstart.mdx     → /payments/guides/getting-started/quickstart
    ├── api-reference/             → /payments/api-reference/...
    │   └── index.mdx              → intro page above the generated endpoints
    └── changelog/                 → /payments/changelog
        └── index.mdx

Three rules worth knowing:

1. Every top-level folder under a product becomes a section tab. Add a folder, get a tab — no registration step. The guides section always sorts first, and /{product} redirects to /{product}/guides.
2. meta.json is optional control, not required config. Order sections with the product-level file, order and label pages with per-folder files. No meta.json means alphabetical order and titles from frontmatter.
3. Two section names carry extra behavior. api-reference (or any section you mount an API at) renders generated endpoint docs alongside your MDX; changelog is just a convention — any section works, but the changelog components make it shine.

The landing page

content/docs/index.mdx renders at / as a full-width authored page — the site header stays, the sidebar goes away, and every component works. Delete the file and the engine generates a product-aware home for you instead. This site's landing page is an authored index.mdx; the default generated home is what you see on a fresh fiskil init before you customize.

Localized content

Translations live in a locale subfolder that mirrors the default tree:

content/docs/
├── payments/guides/quickstart.mdx        ← default locale (unprefixed URLs)
└── es/payments/guides/quickstart.mdx     ← Spanish, served at /es/payments/...

Pages you haven't translated yet fall back per your i18n.fallback setting — see Locales.

Everything else in the repo