docs.json Reference
Every field in docs.json -- themes, colors, navigation, OpenAPI, and branding.
The docs.json file is the central configuration for your Jamdesk documentation site.
Key settings from your docs.json are displayed in the Dashboard under Project Settings → Configuration Highlights. This view is read-only and updates automatically after each successful build.
Required Fields
name
Type: string (required)
Your documentation site's name. Displayed in the header and browser tab.
{ "name": "Acme API Docs" }theme
Type: "jam" | "nebula" | "pulsar" (required)
Clean, modern design with Inter font. Header-based navigation.
Best for: Most documentation sites, API references
colors
Type: object (required)
| Field | Type | Required | Description |
|---|---|---|---|
primary | string (hex) | Yes | Main brand color |
light | string (hex) | No | Light theme accent |
dark | string (hex) | No | Dark theme accent |
{
"colors": {
"primary": "#635BFF",
"light": "#7C75FF",
"dark": "#4F46E5"
}
}Branding
favicon
Type: string
Path to your favicon file (SVG recommended).
{ "favicon": "/images/favicon.svg" }logo
Type: object
| Field | Type | Description |
|---|---|---|
light | string | Logo for light mode |
dark | string | Logo for dark mode |
href | string | URL when logo is clicked |
{
"logo": {
"light": "/images/logo-light.webp",
"dark": "/images/logo-dark.webp",
"href": "https://yoursite.com"
}
}OpenAPI
api.openapi
Type: string | string[]
List the OpenAPI 3.x spec files you want Jamdesk to validate and use for endpoint pages. Use paths relative to your docs.json.
{
"api": {
"openapi": ["/openapi/api.yaml"]
}
}Once configured, you can generate endpoint pages by adding an openapi field in a page’s frontmatter:
---
title: Create Ticket
openapi: /openapi/api.yaml POST /tickets
---If you only have one spec listed, you can also use the short format:
---
title: Create Ticket
openapi: POST /tickets
---See OpenAPI Example for a live endpoint page and Directory Structure for file placement.
Navigation
tabsPosition
Type: "top" | "left"
Controls where navigation tabs are displayed.
| Value | Description |
|---|---|
"top" | Tabs appear in the header tab bar |
"left" | Tabs appear at the top of the sidebar |
Default value depends on your theme:
| Theme | Default |
|---|---|
| jam | "left" |
| nebula | "left" |
| pulsar | "top" |
{ "tabsPosition": "left" }anchors
Type: array
External links that appear at the top of the sidebar on all pages.
| Field | Type | Required | Description |
|---|---|---|---|
name | string | Yes | Display text |
href | string | Yes | URL (external link) |
icon | string | No | Font Awesome icon name |
{
"anchors": [
{ "name": "Blog", "href": "https://blog.example.com", "icon": "newspaper" }
]
}navigation (structure)
Type: object
The navigation structure for your documentation. See Navigation for detailed documentation.
Pages can be strings (title auto-generated from filename) or objects with a custom title:
"pages": [
"introduction",
{ "page": "content/mdx-basics", "title": "MDX Basics" }
]{
"navigation": {
"tabs": [
{
"tab": "Docs",
"icon": "book-open",
"groups": [
{
"group": "Getting Started",
"pages": ["introduction", "quickstart"]
}
]
}
]
}
}Navbar & Footer
navbar
Type: object
| Field | Type | Description |
|---|---|---|
links | array | Navigation links |
primary | object | Primary CTA button |
{
"navbar": {
"links": [
{ "label": "Blog", "href": "/blog" }
],
"primary": {
"type": "button",
"label": "Dashboard",
"href": "https://app.example.com"
}
}
}footer
Type: object
Configure the page footer with social links and custom link columns.
{
"footer": {
"socials": {
"github": "https://github.com/yourorg",
"x": "https://x.com/yourhandle",
"discord": "https://discord.gg/yourserver"
},
"links": [
{
"header": "Resources",
"items": [
{ "label": "Blog", "href": "https://example.com/blog" },
{ "label": "Changelog", "href": "/changelog" }
]
}
]
}
}| Field | Type | Description |
|---|---|---|
socials | object | Social media platform URLs |
links | array | Link column configurations |
links[].header | string | Column heading |
links[].items | array | Array of { label, href } objects |
Supported social platforms: github, x, twitter, linkedin, discord, slack, youtube, instagram, facebook, reddit, telegram, bluesky, threads, medium, hacker-news, website
Styling
styling.latex
Type: boolean
Enable LaTeX math rendering with KaTeX. When enabled, you can use $...$ for inline math and $$...$$ for block equations.
{
"styling": {
"latex": true
}
}See Math & LaTeX for usage details.
Full Example
{
"$schema": "https://jamdesk.com/docs.json",
"name": "Acme Documentation",
"description": "Learn how to use Acme",
"theme": "jam",
"colors": {
"primary": "#635BFF"
},
"favicon": "/images/favicon.svg",
"logo": {
"light": "/images/logo-light.webp",
"dark": "/images/logo-dark.webp"
},
"styling": {
"latex": true
},
"anchors": [
{ "name": "Blog", "href": "https://blog.acme.com", "icon": "newspaper" }
],
"navbar": {
"links": [
{ "label": "Support", "href": "/support" }
],
"primary": {
"type": "button",
"label": "Dashboard",
"href": "https://app.acme.com"
}
},
"navigation": {
"tabs": [
{
"tab": "Docs",
"icon": "book-open",
"groups": [
{
"group": "Get Started",
"pages": ["introduction", "quickstart"]
}
]
},
{
"tab": "API Reference",
"icon": "code",
"groups": [
{
"group": "Endpoints",
"pages": ["api/users", "api/posts"]
}
]
}
]
}
}