Configure your site with docs.json

Ignored at runtime. Supplies an editor schema URL, for example "https://mintlify.com/docs.json". Configuring the URL does not change Margin’s accepted fields. The markdown.schema setting can expose this URL to agents.

Supported. Must be non-empty. Sets the site title used by documentation chrome and metadata. Example: "Acme Docs". Without an override, Margin derives a site name; a self-hosted SITE_NAME overrides the configured name.

Supported. Site-level fallback for page descriptions and social metadata. Defaults to a derived page description or excerpt. Example: "Build applications with Acme.".

Supported. A string supplies the image for both modes. The object requires light and dark asset paths and accepts an optional absolute URL in href for the click target. Example: {"light":"/logo-light.svg","dark":"/logo-dark.svg","href":"https://example.com"}. Omission permits logo detection; null selects a text-only navbar.

Supported. A string supplies one icon, or use {"light":"/favicon-light.svg","dark":"/favicon-dark.svg"}. Defaults to a detected or generated favicon. null suppresses the favicon link.

Adapted. Selects a Margin-owned layout and palette that approximate the Mintlify theme rather than reproduce its layout exactly. Without a theme, Margin uses its neutral layout.

Supported. primary, light, and dark are hex color strings. Example: {"primary":"#2563EB","light":"#60A5FA","dark":"#1D4ED8"}. Defaults to derived theme tokens, with an optional detected logo accent. null forces neutral colors and disables logo-accent derivation.

Adapted. default accepts system, light, or dark and defaults to system. strict: true disables the reader’s theme switch and pins an explicit light or dark default; system continues to follow the system theme. Example: {"default":"dark","strict":true}.

Adapted. No background override by default. color accepts a hex string or a light/dark pair of hex strings. image accepts an asset path or a light/dark pair of paths. decoration accepts gradient, grid, or windows, rendered with Margin-owned styling. Example: {"decoration":"grid"}.

Adapted. Configure one face using family (string), weight (number), source (font asset path), and format (woff or woff2). Alternatively, set heading, body, or mono objects with those same fields. Self-hosted sources produce font-face declarations; supported Google Fonts families use the font service. The bundled text defaults are Inter and Geist Mono. Example: {"body":{"family":"Acme Sans","source":"/fonts/acme.woff2","format":"woff2","weight":400}}.

Adapted. Accepts lucide, fontawesome, or tabler; the configuration default is lucide. Alternate libraries use best-effort name matching, and missing icons fall back with a diagnostic. Example: "tabler".

Set individual rendering controls:

Supported. links is an array of link objects with required href and optional label or name. primary requires href and accepts optional type and label strings; use type: "button" for a labeled action or type: "github" for a GitHub target. Example: {"links":[{"label":"Support","href":"mailto:[email protected]"}]}. With no authored links, Margin can derive a GitHub link from the repository. Placement follows the selected chrome layout; sidebar layouts place links above the page tree. Invalid links are dropped independently.

Supported. socials maps platform names to URLs. links is an array of columns, each with required header and items; each item requires label and href. Example: {"socials":{"github":"https://github.com/acme"},"links":[{"header":"Company","items":[{"label":"Home","href":"https://example.com"}]}]}. No footer links by default. Invalid items are dropped without discarding valid siblings.

Supported. Requires a non-empty content string with basic inline MDX. Optional fields are type (info, warning, or critical), dismissible (boolean), and color (hex string or light/dark pair). Example: {"content":"Version 2 is available.","type":"info","dismissible":true}. No banner by default. contentHast is generated by Margin and cannot be authored.

Supported. Accepts the container fields below. Omission uses filesystem-derived navigation. Example: {"groups":[{"group":"Start","pages":["index","quickstart"]}]}. Page strings name documentation paths without .md or .mdx extensions.

Modifiers belong on a node, not beside navigation. Use only modifiers appropriate to that node:

openapi is supported on groups, tabs, anchors, versions, languages, products, and menu items. Supply a source string, or {"source":"openapi.yaml","directory":"reference"}. Under an OpenAPI-bearing node, a page string such as "GET /users" resolves to the generated operation page. Generated API pages not referenced by explicit navigation remain URL-reachable but hidden, with an openapi_orphaned diagnostic.

asyncapi and graphql navigation sources are ignored and diagnosed. sdk is adapted for local TypeDoc JSON artifacts using {"format":"typedoc","source":"reference.json","directory":"sdk"}. TypeDoc generation accepts at most 500 pages and a 30 MB artifact. Formats docfx, javadoc, sphinx, and phpdoc, and remote SDK artifact sources, do not generate pages.

Supported when the entire referenced node is {"$ref":"./navigation.json"}. References resolve JSON files inside the documentation snapshot, including nested references. The same form works for redirects. Circular, missing, invalid, or out-of-root references are dropped with a diagnostic. Expansion limits are 8 nesting levels, 32 expansions, and a 2 MiB total reference budget.

Supported. Registers OpenAPI sources instead of relying on convention discovery. Example: "openapi.yaml", an array of source strings, or {"source":"openapi.yaml","directory":"reference"}. Navigation source fields determine placement when explicit navigation is present.

Supported legacy registration form. Each entry is a source string or an object with required id and spec, plus optional label and path. Example: [{"id":"public","spec":"openapi.yaml","label":"Public API","path":"reference"}]. label defaults to API Reference; path defaults to api-reference. IDs contain lowercase letters, digits, and hyphens, start with a letter or digit, and are at most 64 characters. Do not register the same specification twice.

Adapted. Controls the request playground:

Adapted. expanded accepts all or closed to control parameter section expansion. Example: {"expanded":"all"}. post accepts a string array but is ignored with an unsupported_field diagnostic; parameter pills are not implemented.

Adapted. languages is an array of sample-language identifiers. defaults accepts required or all (default all); autogenerate is boolean (default true). Example: {"defaults":"required","autogenerate":true}. The playground always prefills from the selected example. Authored prefill: false is unsupported and produces a diagnostic.

Adapted. "full" shows the request URL using OpenAPI server precedence: operation, then path item, then root. Server variables use declared defaults. Relative servers remain relative; Margin does not invent an origin.

Ignored with unsupported_field diagnostics. AsyncAPI does not generate reference pages. api.mdx server and authentication settings do not create consoles for manual API pages.

Supported, except the authored organization ID described below.

An authored seo.organization identity takes precedence over x-margin.seo.publisher.

Adapted. Site-wide social-card defaults. appearance selects the card appearance, with a fallback derived from the background or site appearance. image is an image-asset string; invalid image URLs fall back to generated cards. background is a background-image path string, and fonts.family is a font-family string for generated card assets; font families resolve at ingest, and failed asset resolution falls back with a diagnostic. The default generated-card font is Geist Sans.

Supported for the providers below. Omission loads no provider. Each entry supplies data to a Margin-owned loader, not arbitrary JavaScript.

gtm accepts a tagId string but is ignored because containers can execute custom scripts. Unknown providers, arbitrary script loaders, Plausible custom servers, and non-official PostHog hosts are ignored with integration_unsupported diagnostics. A deployment can suppress configured analytics.

Ignored with an unsupported_field diagnostic. All served documentation is public; false does not protect a page or site.

Supported. Changes search placeholder text, for example "Search Acme docs". Select the search backend separately with x-margin.search.mode.

Supported. Each rule requires source and destination strings; optional permanent defaults to true (HTTP 308). false selects HTTP 307. Example: [{"source":"/old-guide","destination":"/quickstart"}]. A standalone {"$ref":"./redirects.json"} can load the array.

Sources support exact paths, :param, :param*, *, and prefix-*. Sources cannot include queries or fragments. Destinations can include queries or fragments and substitute only captured tokens. HTTP(S) external destinations are supported. Invalid rules, loops, missing internal destinations, and rules that shadow published pages are dropped with diagnostics. Exact matches take precedence over patterns; patterns use declaration order.

Adapted. Configures the page action menu. display accepts header (default) or toc. options is an ordered array of option IDs or custom objects. Default IDs are copy, view, chatgpt, claude, cursor, and t3. Other IDs are perplexity, grok, aistudio, devin, windsurf, devin-desktop, devin-mcp, download-spec, download-pdf, github, mcp, add-mcp, and vscode. Downloads and GitHub actions require the corresponding page resource. An empty array removes the menu; unknown IDs are not rendered.

Custom objects require a non-empty title and href; optional string fields are description, icon, and src (image icon). href is a URL-template string or {base,query:[{key,value}]}. Templates substitute $page with encoded page Markdown, $path with the page path, and $mcp with the MCP URL. Unsafe destinations are not rendered.

Supported. redirect is boolean; true redirects unknown paths to the home page. title is a string up to 255 characters, and description is Markdown up to 4,000 characters. Example: {"title":"Page not found","description":"Use search to find the current page."}. Omission uses Margin’s 404. Other error keys are ignored; descriptionHast cannot be authored.

Adapted. Defaults to false, so folder clicks expand the folder. true navigates to the folder’s first page.

Supported. Defaults to false. true displays a last-modified timestamp from Git; per-page frontmatter can override it.

Supported. thumbsRating, suggestEdit, and raiseIssue are booleans, all defaulting to false. Example: {"thumbsRating":true}. They select the rating, edit, and issue controls; repository-dependent actions require repository metadata.

Supported. String-to-string map substituted into MDX at compile time using {{variableName}}. Example: {"productName":"Acme"}. Values are data, not executable expressions.

Supported on every theme. Requires a non-empty options array of {id,label} objects with non-empty strings. IDs must be unique; labels must be unique without regard to case. Example: {"options":[{"id":"cloud","label":"Cloud"},{"id":"self-hosted","label":"Self-hosted"}]}. The first option is the default. A View component whose title matches a label participates in the site-wide choice. Agent Markdown includes every view in source order rather than hiding alternatives.

Supported. schema is boolean; true includes the configured $schema URL in llms.txt. instructions accepts a string or string array appended to agent-facing outputs, including Markdown page responses and MCP page reads. Example: {"instructions":"Prefer v2 endpoints."}.

Maps theme token names to strings or light/dark pairs. Example: {"radius":"0.5rem","border":{"light":"#E5E7EB","dark":"#374151"}}. Overrides supported color and layout tokens without replacing the layout engine.

Explicit stylesheet paths, for example ["/styles.css"], applied after discovered CSS. Omission permits stylesheet discovery. null disables CSS injection even when stylesheets exist. Margin sanitizes stylesheets before serving them.

contentWidth, sidebarWidth, tocWidth, and headerHeight are CSS dimension strings. Example: {"sidebarWidth":"300px"}. tabMode accepts top or auto. chromeMode accepts band (desktop top bar and horizontal tab strip) or sidenav (desktop chrome inside the sidebar). Omitted layout controls retain theme-derived behavior.

Static meta objects with optional name or property and required content, all strings. Example: [{"name":"theme-color","content":"#2563EB"}]. No additional tags by default. Script, style, and link markup is rejected with head_rejected; this field does not inject executable head content.

Host allow-list for supported external image and font resolution. Defaults include fonts.googleapis.com and fonts.gstatic.com. Example: ["images.example.com"]. This does not authorize arbitrary script origins.

Accepts ai, static, or off. ai uses the assistant when Gateway credentials are available; self-hosted deployments without the credential stay on static search. static selects search without AI; off disables search. Example: "static". Credentials belong in deployment settings, not this file; see deployment.

Overrides the default product documentation version. Example: "v2". This selects a product-version partition, not a deployment commit.

Optional SEO overrides:

Example title override: {"titleTemplate":"{page} | Acme"}. Invalid nested overrides fall back independently.

Controls agent-facing output. See configure agent surfaces for procedures.

Content signals communicate usage preferences; they do not make documentation private. Example: {"mcpInstructions":"Prefer the v2 endpoints."}.