Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.markapidown.net/llms.txt

Use this file to discover all available pages before exploring further.

Every MarkApiDown project starts with a single file — api-docs/mad.md — that anchors your workspace. It declares your project name, which environment to use by default, global request behaviour, web preview options, and any plugins. MarkApiDown reads this file automatically by walking up from your current directory to the nearest Git root, so you can run any mad command from any subdirectory of your project without specifying a path.
mad.md is auto-located by walking up from the current working directory until MarkApiDown finds an api-docs/mad.md file at the Git root. You never need to pass --config during normal use, but the flag is available when you need to point at a non-standard location.
Run mad init in your project root to scaffold mad.md, _shared/env.md, and an example endpoint in one step. It detects your project name from package.json, Cargo.toml, pyproject.toml, or other common manifests.

​
Complete example

The file uses YAML frontmatter for identity fields and fenced yaml code blocks for each configuration section. 
---
name: jsonplaceholder
version: 1
default-env: dev
---
# JSONPlaceholder

Example MarkApiDown project using the JSONPlaceholder REST API.

## Defaults

\`\`\`yaml
timeout: 5000
retry:
  attempts: 0
  backoff: fixed
auth: none
\`\`\`

## Web preview

\`\`\`yaml
port: 8080
host: 127.0.0.1
theme: auto
autosave: 2s
\`\`\`

## Plugins

\`\`\`yaml
plugins: []
\`\`\`

​
Frontmatter fields

These three fields live between the --- delimiters at the very top of mad.md.
​
name
string
required
The display name for your project. Shown in the web preview header and in mad doctor output. Use the same slug you’d use in a package.json or Cargo.toml — lowercase, hyphens allowed.
name: payments-api
​
version
integer
required
The configuration schema version. Always set this to 1. MarkApiDown uses this field to detect incompatible config formats in future releases.
version: 1
​
default-env
string
required
The environment name MarkApiDown selects when you run a command without an explicit --env flag. Must match a section name defined in _shared/env.md.
default-env: dev

​
Defaults section

The ## Defaults section configures request behaviour that applies to every endpoint in your project. Individual endpoint specs can override any of these values in their own frontmatter.
​
timeout
integer
Maximum time in milliseconds to wait for a response before aborting the request. Applies to every endpoint unless overridden per spec.Default: 5000
timeout: 5000
​
retry.attempts
integer
Number of times to retry a failed request. Set to 0 to disable retries entirely.Default: 0
retry:
  attempts: 3
​
retry.backoff
string
Strategy for spacing out retry attempts.
ValueBehaviour
fixedWaits the same interval between every retry
exponentialDoubles the wait time after each retry
Default: fixed
retry:
  backoff: exponential
​
auth
string
Default authentication scheme for all requests. Endpoint specs can override this per-request.
ValueBehaviour
noneNo Authorization header added
bearerInjects Authorization: Bearer {{token}}
basicInjects Authorization: Basic <base64(user:pass)>
Default: none
auth: bearer

​
Full Defaults block

timeout: 5000
retry:
  attempts: 0
  backoff: fixed
auth: none

​
Web preview section

The ## Web preview section controls mad serve, the local browser UI that renders your specs interactively.
​
port
integer
TCP port the web preview server binds to. Change this if port 8080 is already in use on your machine.Default: 8080
port: 3000
​
host
string
Host address the server listens on. Keep 127.0.0.1 for local-only access. Use 0.0.0.0 only when you need the preview reachable on your local network — MarkApiDown will warn you when you do this.Default: 127.0.0.1
host: 127.0.0.1
​
theme
string
Colour theme for the web preview UI.
ValueBehaviour
autoFollows the OS / browser preference
lightAlways renders in light mode
darkAlways renders in dark mode
Default: auto
theme: dark
​
autosave
string
Controls when the browser UI writes unsaved edits back to disk.
ValueBehaviour
manualOnly saves when you explicitly trigger a save
2s (or any duration)Saves automatically after the specified idle period
Default: manual
autosave: 2s

​
Full Web preview block

port: 8080
host: 127.0.0.1
theme: auto
autosave: manual

​
Plugins section

The ## Plugins section lists any MarkApiDown plugins your project loads. Plugins extend the CLI and web preview with custom reporters, importers, or middleware. 
plugins: []
This section is required even when empty — MarkApiDown expects it to be present in every mad.md file. Leave it as an empty list until you install a plugin.
When you run any mad command, the CLI walks up the directory tree from your current working directory looking for api-docs/mad.md. It stops at the Git root — the directory that contains .git/. This means you can cd into any subdirectory, such as api-docs/apis/users/, and run mad exec get-user.md without specifying a config path.To override the auto-detected path, pass --config path/to/mad.md as a global flag:
mad --config ./infra/api-docs/mad.md serve