> ## Documentation Index > Fetch the complete documentation index at: https://margin.manicule.dev/llms.txt > Use this file to discover all available pages before exploring further. > For every page in one file, fetch https://margin.manicule.dev/llms-full.txt (large). > To search and read these docs as tools, connect the MCP server at https://margin.manicule.dev/api/mcp. > Every agent surface: https://margin.manicule.dev/.well-known/llms-manifest.json # Configuration (/configuration) Related: [Margin](/index.md), [Deploy](/deploy.md), [Extensions](/extensions.md), [Agents and discovery](/agents.md), [Link relations](/link-relations.md) > Configure a site with files, frontmatter, and optional docs.json. `docs.json` is optional and lives at the root of the folder named by `DOCS_DIR`. It extends supported Mintlify fields. Unknown fields produce diagnostics; a malformed known field falls back independently. Unparseable JSON and unsafe or invalid content can fail the build. ## Files and titles `index.mdx` becomes its directory's landing page. Other `.md` and `.mdx` files become paths based on their filenames. A title comes from frontmatter, then the first Markdown H1, then the filename. For example: ```markdown # Quickstart Follow these steps to make a request. ``` Use `meta.json` to order a directory's sidebar entries. `"..."` includes remaining pages: ```json { "title": "Guides", "pages": ["index", "quickstart", "..."] } ``` An explicit `navigation` block in `docs.json` controls the sidebar. Pages left out of it can still be reached by URL; hiding a page is not access control. Do not put confidential content in a public documentation tree. ## Site configuration ```json { "name": "Example Docs", "theme": "aspen", "colors": { "primary": "#2563EB" }, "navigation": { "groups": [{ "group": "Start", "pages": ["index", "quickstart"] }] }, "x-margin": { "search": { "mode": "static" }, "layout": { "sidebarWidth": "300px" } } } ``` Mintlify themes map to framework-owned layout presets. They approximate the upstream layout rather than reproduce it pixel for pixel. Colors, logos, fonts, navigation, OpenAPI references, redirects, and supported analytics settings remain data. Local snippet components can add executable page content, but they do not replace server code or the configuration schema. ## Framework extensions The vendor namespace is `x-margin`. Common settings include: | Field | Effect | | ---------------------- | ------------------------------------------------------------------------- | | `search.mode` | `ai`, `static`, or `off`; AI search also needs a Gateway credential. | | `tokens` | Theme token values, including light/dark pairs. | | `css` | Explicit stylesheet paths, or `null` to disable stylesheet injection. | | `layout` | Content, sidebar, TOC, and header dimensions; tab/chrome mode. | | `head.meta` | Additional static meta tags. | | `assets.allowExternal` | Hosts allowed for supported remote asset resolution. | | `versions.default` | Default product documentation version. | | `seo` | Title template, publisher, language, and provenance facts. | | `agents` | Content signals, index preamble, Markdown behavior, and MCP instructions. | These fields belong inside `x-margin`; for example, `x-margin.search.mode`. Server modules selected by `DOCS_EXTENSIONS` use a separate TypeScript contract. ## Product versions Product versions such as `v1` and `v2` are path partitions inside one content snapshot. They are separate from deployment versions keyed by commit. Directory conventions or explicit navigation can define them. A version root's `meta.json` can label it and choose a default: ```json { "title": "Version 2", "x-margin-version": "v2", "x-margin-version-default": true } ``` ## Assets and styling Keep images, logos, and fonts inside the docs folder. Ingest rewrites admitted asset references to content-addressed URLs. SVGs are sanitized; CSS is parsed and sanitized before serving. Stylesheets cannot introduce arbitrary scripts. Inter and Geist Mono are the bundled text fonts; OG cards use Geist Sans. ## Icons Builds use the MIT-licensed Hugeicons Free set. To use a licensed Hugeicons Pro set, set `HUGEICONS_PRO_TOKEN` in the build environment, optionally choose `HUGEICONS_PRO_STYLE`, then run `bun run icons:build` or redeploy. The script fetches Pro into a temporary directory; it is never a manifest dependency. A missing content glyph falls back to the default icon; a missing chrome glyph fails the build. Never commit the token, the Pro package, or generated Pro SVGs. Your Pro license governs deployment and redistribution. ## Environment variables Outside Vercel, only the database URL and `SITE_ORIGIN` are required. Empty strings count as unset. Keep secrets in your environment or Vercel project, never in `docs.json` or a committed environment file. | Variable | Default / requirement | Purpose | | -------------------------------------------------------------------------- | --------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `DATABASE_URL` / `POSTGRES_URL` | Required; first non-empty wins | Postgres connection. | | `DATABASE_URL_UNPOOLED` / `POSTGRES_URL_NON_POOLING` | Connection URL above | Direct connection for migrations and the ingest advisory lock; supply it when using a transaction-mode pooler. | | `DATABASE_POOL_MAX` | `2` (range `1`–`20`) | Connections per server instance. | | `NODE_EXTRA_CA_CERTS` | Unset | Path to a PEM CA bundle for Postgres signed by a private CA. Set before starting the process, including migrations and ingest; this keeps TLS certificate verification enabled. | | `POSTGRES_PORT` | `5440` | Host port of the Compose database. Update the connection URL too. | | `SITE_ORIGIN` | Required outside Vercel; production project URL or deployment URL on Vercel | Canonical URLs, sitemaps, and OG images. | | `SITE_SLUG` | `docs` | Single-site database slug and cache tag; lowercase letters, digits, and inner hyphens, at most 55 characters. | | `SITE_NAME` | `docs.json` name, then slug | Display name. Read at build time, so a change takes effect on the next deployment. | | `SITE_SECRET` | Database URL | Salt for hashed visitor identifiers. | | `DOCS_DIR` | `docs/`, else `.` when it contains `docs.json` | Folder to ingest. | | `DOCS_CONTENT_SHA` | Vercel commit SHA, then git HEAD, then `dev-` | Content key, resolved once and baked into a deployment. | | `DOCS_INGEST` | `on` | `off` skips ingest; `force` replaces an already-ingested key. | | `DOCS_KEEP_VERSIONS` | `20` | Number of other production versions retained in addition to the age window and protected versions. | | `DOCS_CANONICAL_REDIRECT` | `1` | `0` disables production redirects to the `SITE_ORIGIN` host. | | `DOCS_CHAT_MODEL` | `openai/gpt-5.6-terra` | AI Gateway model for the assistant. | | `AI_GATEWAY_API_KEY` | Unset; Vercel uses OIDC | Optional assistant credential. Outside Vercel, search stays static without it. On Vercel, enable AI Gateway access for the deployment. | | `DOCS_LINK_RELATION_BASE` | Repository's `docs/link-relations.md#` URI | Base for agent discovery relation URIs. | | `HUGEICONS_PRO_TOKEN` / `HUGEICONS_PRO_STYLE` | Unset / `stroke-rounded` | Optional Pro icon set, fetched only while building icons. | | `BLOB_READ_WRITE_TOKEN` | Unset | Optional Vercel Blob storage for large assets and the search corpus. Without it, both stay in Postgres within ingest size limits. | | `GITHUB_TOKEN` | Unset | Raises the repository stars widget's GitHub API rate limit. | | `SENTRY_DSN` | Unset; Sentry off | Optional error reporting. Local development (`VERCEL_ENV`, else `NODE_ENV`, is `development`, as under `bun run dev`) stays silent even with a DSN unless `SENTRY_ENVIRONMENT` is set. | | `SENTRY_ORG`, `SENTRY_PROJECT`, `SENTRY_AUTH_TOKEN` | Unset | Source-map uploads require all three and the DSN. | | `SENTRY_ENVIRONMENT`, `SENTRY_RELEASE` | Deployment environment / platform-derived release when available | Optional Sentry metadata overrides. Setting `SENTRY_ENVIRONMENT` also opts local development into reporting. | | `POSTHOG_KEY` / `POSTHOG_HOST` | Unset / `https://us.i.posthog.com` | Agent-journey analytics; off without a key. | | `DOCS_EXTENSIONS` | Built-in single-site module | Build-time path to a module exporting `extensions: DocsExtensions`. | | `NITRO_PRESET` | `vercel` | Server build target; use `node-server` for self-hosting. | | `PORT` / `NODE_ENV` | Vite default / `development` | Dev server port and runtime environment. The example uses port 3000. | | `VERCEL_ENV`, `VERCEL_URL`, `VERCEL_PROJECT_PRODUCTION_URL` | Supplied by Vercel | Preview behavior and inferred origin. | | `VERCEL_GIT_COMMIT_SHA`, `VERCEL_GIT_PULL_REQUEST_ID`, `VERCEL_OIDC_TOKEN` | Supplied by Vercel | Content version, preview metadata, and Gateway authentication. | The deployment standard defines the supported field inventory, precedence, and MDX security contract; see also [deployment](/deploy) and [extensions](/extensions).