Base Path & Subpaths

Flame always emits a flat .html build, but the URL shape it is served under is configurable. Two independent settings decide that shape, and mixing them up is the usual cause of broken assets after a move:

flowchart TD
    U["https://acme.github.io/handbook/docs/guide/routing.html"]
    O["Origin — https://acme.github.io"]
    R["Deployment root — /handbook, from the meta.baseURL pathname"]
    P["Docs prefix — /docs, from meta.basePath"]
    F["Page — docs/guide/routing.mdx"]

    U --> O
    O --> R
    R --> P
    P --> F

Docs prefix

meta.basePath is where the docs site sits inside the dist and in the URL. It defaults to /docs, so leaving it unset keeps the historical layout:

{
  "meta": {
    "title": "Acme Docs",
    "baseURL": "https://book.acme.dev",
    "basePath": "/handbook"
  }
}

The prefix is applied everywhere a docs URL is produced — the dev server and static routing, internal links and asset paths in rendered pages, canonical and Open Graph URLs, the search index, and the nginx config generated by flame deploy --docker. It is also part of the build cache key, so changing it rebuilds every page instead of reusing HTML that points at the old prefix.

You do not have to rewrite your content when you change it: links authored as /docs/guide/routing are re-based onto the configured prefix, so one docu.json works at /docs, at /handbook, and at the deployment root. See Formatting for the link rules.

Deployment root

meta.baseURL is the origin plus the deployment root — the base a browser prepends to every root-absolute path. Its pathname is the deployment path: empty when the origin serves the dist at /, /repo when the host publishes the artifact under a path.

{
  "meta": {
    "title": "Acme Docs",
    "baseURL": "https://acme.github.io/handbook"
  }
}

Only root-absolute references need it — the 404.html fallback's bundle assets and the search index records, which are clicked directly from the modal and cannot be expressed as a relative climb. It is also the base canonical and Open Graph URLs are resolved against. Everything else already lines up, because pages and assets share the deployment root.

Common setups

For a project site, baseURL must include the repository segment — that is the path GitHub Pages serves the artifact under. Without it, the search index and the 404 fallback point at the origin root and return 404.

Root deployment

Setting "basePath": "" serves the docs at the deployment root. Two details follow from that:

• Pages move to the dist root. docs/getting-started.mdx → .docu/dist/getting-started.html, and the URL is /getting-started.html under the deployment root.
• The landing page owns /. The docs index (docs/index.mdx) is not written — it would collide with the generated landing page — and index.html left over from a previous build is removed. Author links as usual: /docs/guide/routing collapses to /guide/routing.

The docs index is optional in every setup: when docs/index.mdx (or docs/index.md) is absent, the build simply produces no docs index page — the landing page always owns /.

Canonical form

The prefix is both a URL path and an output directory, so it is canonicalized to lowercase segments with no trailing slash, no dot segments, and nothing that needs percent-encoding. The schema describes the accepted shape:

{
  "pattern": "^(|/|/[a-z0-9._~-]+(/[a-z0-9._~-]+)*)$",
  "maxLength": 128
}

Non-canonical values are still honored — Flame normalizes them and logs a warning naming the canonical value, so you can update docu.json and keep the editor quiet:

A non-string value is the only hard failure — it cannot be normalized. Everything else is reported and normalized at the start of flame dev and flame build, before any output is written.

Verify

After a build, the prefix should show up consistently in each of these places: