# REST API overview (https://blode.md/docs/api/overview) Use the Blode.md REST API for programmatic access to projects, deployments, and domains when you need custom tooling beyond the CLI workflows. The base URL for all requests is `https://api.blode.md`. > [!NOTE] > The CLI handles deployments automatically. Use the REST API for custom > integrations or tooling built on top of blodemd. ## Authentication Every endpoint uses the Supabase user session token issued by `blodemd login`: ``` Authorization: Bearer ``` The CLI attaches this header automatically. ## Error format All errors return JSON with an `error` string and an optional `issues` field for validation errors. ```json { "error": "string", "issues": [] } ``` --- ## Health | Method | Path | Description | | ------ | --------- | --------------------------------- | | GET | `/health` | Returns `{ ok: true, timestamp }` | --- ## Projects | Method | Path | Description | | ------ | ---------------------- | -------------------------------------------- | | GET | `/projects/` | List all projects for the authenticated user | | POST | `/projects/` | Create a project | | GET | `/projects/:projectId` | Get a project | | PATCH | `/projects/:projectId` | Update a project | **POST /projects/: request body** - `name` (type: string): Display name for the project. - `slug` (type: string): URL-safe identifier. Used as the subdomain at `{slug}.blode.md`. - `description` (type: string, default: undefined): Optional short description. Returns the created project. **PATCH /projects/:projectId: request body** - `name` (type: string, default: undefined): New display name. - `description` (type: string, default: undefined): New description. - `deploymentName` (type: string, default: undefined): Override the active deployment label. --- ## Deployments Deployments follow a three-step flow: create → upload files → finalize. | Method | Path | Description | | ------ | -------------------------------------------------- | --------------------- | | POST | `/projects/slug/:slug/deployments` | Create a deployment | | POST | `/projects/slug/:slug/deployments/:id/files/batch` | Upload files in batch | | POST | `/projects/slug/:slug/deployments/:id/finalize` | Finalize and promote | **POST /projects/slug/:slug/deployments: request body** - `branch` (type: string, default: "main"): Git branch name. - `commitMessage` (type: string, default: undefined): Commit message attached to this deployment. - `environment` (type: string, default: undefined): Deployment environment label. **POST .../files/batch: request body** **POST .../finalize: request body** - `promote` (type: boolean, default: true): Promote this deployment to production immediately. --- ## Domains | Method | Path | Description | | ------ | ----------------------------------------------------- | ---------------------------- | | GET | `/projects/:projectId/domains` | List domains | | POST | `/projects/:projectId/domains` | Add a custom domain | | DELETE | `/projects/:projectId/domains/:domainId` | Remove a domain | | GET | `/projects/:projectId/domains/:domainId/verification` | Get DNS verification records | | POST | `/projects/:projectId/domains/:domainId/verify` | Trigger domain verification | **POST /projects/:projectId/domains: request body** - `hostname` (type: string): The fully-qualified domain name to add, e.g. `docs.example.com`. - `pathPrefix` (type: string, default: undefined): Mount the docs at a subpath, e.g. `/docs`. # blodemd analytics (https://blode.md/docs/cli/analytics) Use blodemd analytics to read and write PostHog project keys for a tenant, script rollouts in CI, and keep analytics config in your docs repo. `blodemd analytics` reads and writes the per-project analytics config that the dashboard exposes at **Settings → Analytics**. Use it to script rollouts, wire analytics into CI, or keep your docs repo the source of truth. ## Subcommands ```bash title="Read current config" blodemd analytics get [--project ] [--json] ``` ```bash title="Set PostHog" blodemd analytics set posthog [--host ] [--project ] ``` ```bash title="Remove a provider" blodemd analytics unset posthog [--project ] ``` The project slug is resolved in this order: `--project`, `BLODEMD_PROJECT`, `slug` in your local `docs.json`. Run from inside your docs repo and you never need to pass it. ## Examples ```bash # Set PostHog with the EU cloud host blodemd analytics set posthog phc_abc123def456 --host `eu.i.posthog.com` # Check what's configured, as JSON, so you can pipe it blodemd analytics get --json # Remove PostHog blodemd analytics unset posthog ``` ## Options - `--project ` (type: string): Project slug. Defaults to BLODEMD_PROJECT or docs.json. - `--api-url ` (type: string): Blode.md API URL. Override for self-hosted deployments. - `--json` (type: boolean, default: false): Print the analytics config as JSON (only on `get`). - `--host ` (type: string): PostHog host (only on `set posthog`). Defaults to `us.i.posthog.com.` ## Validation The CLI validates inputs before hitting the API: - **PostHog project key** must start with `phc_` and be at least 24 characters. Personal API keys (`phx_`) are rejected: they have far more privilege than the project key needs and would leak to the browser. - **PostHog host** must be an `https://` URL. ## Authentication `blodemd analytics` requires you to be logged in. Run `blodemd login` if the CLI reports you are not authenticated. # blodemd dev (https://blode.md/docs/cli/dev) Start a local Blode.md preview server with hot reload so you can write MDX and see production-quality docs update as you save. Run the full Blode.md rendering engine locally so you can preview your documentation as you write. Start `blodemd dev` while editing MDX so you see the same components, navigation, and search behavior as production. The file watcher reloads content changes automatically, and updates to `docs.json` trigger a full reload so sidebar and branding changes show up immediately. A common loop: run `blodemd validate` once after editing config, then `blodemd dev` and keep the preview open while you write. When pages look right locally, deploy with `blodemd push`. If the server fails to start, check that `docs.json` exists (run `blodemd new` if you are starting from scratch). ```bash blodemd dev ``` ## How it works The dev server starts a local Next.js instance that renders your documentation with the same engine used in production. A file watcher monitors your docs directory and triggers automatic browser refreshes when content changes. Changes to `docs.json` trigger a full server reload. ## Options - `--no-open` (type: boolean, default: false): Do not open the browser automatically when the server starts. ## Examples ```bash title="Start with defaults" blodemd dev ``` ```bash title="Custom port" blodemd dev --port 4000 ``` ```bash title="Specific directory, no browser" blodemd dev --dir ./my-docs --no-open ``` ## File watching The dev server watches all files in your docs directory for changes: - **Content changes** (`.mdx`, `.md`, `.json` files) trigger a hot reload in the browser. - **Config changes** (`docs.json`) trigger a full server reload to pick up navigation, branding, and API config updates. > [!INFO] > The dev server requires a valid `docs.json` in your docs directory. Run > `blodemd new` first if you are starting from scratch. ## Related pages - [blodemd validate](https://blode.md/docs/cli/validate) -- check docs.json before starting the dev server - [blodemd push](https://blode.md/docs/cli/push) -- publish after local preview looks correct - [blodemd new](https://blode.md/docs/cli/new) -- scaffold the docs directory dev expects # blodemd login (https://blode.md/docs/cli/login) Authenticate the Blode.md CLI with GitHub in your browser, store a local OAuth session, and unlock deploy commands like blodemd push. Authenticate your CLI session so you can deploy documentation with `blodemd push`. You only need `blodemd login` once per machine unless you run `blodemd logout` or your session expires. After login, the CLI stores OAuth tokens locally and refreshes them automatically when you run commands like `blodemd push` or `blodemd whoami`. Local deploys use your GitHub session; CI pipelines should use a project deploy key instead (see [Continuous deployment](https://blode.md/docs/deployment/ci)). First-time setup often looks like: install the CLI from [CLI overview](https://blode.md/docs/cli/overview), run `blodemd new`, then `blodemd login` and `blodemd push`. If port 8787 is in use, pass `--port` or use `--no-open` in headless environments. ```bash blodemd login ``` ## How it works `blodemd login` opens your browser to sign in with GitHub via Supabase OAuth (PKCE). After you authorize, the CLI receives an access token and stores it locally. No API keys, ever. The CLI starts a temporary local server on port 8787 to receive the OAuth callback. If the browser does not open automatically, copy the printed URL manually. ## Options - `--port ` (type: number, default: 8787): Port for the local OAuth callback server. - `--timeout ` (type: number, default: 180): How long to wait for browser authorization before timing out. - `--no-open` (type: boolean, default: false): Print the authorization URL instead of opening the browser. ## Examples ```bash title="Browser sign-in" blodemd login ``` ```bash title="Custom port and no browser" blodemd login --port 9090 --no-open ``` ## Credential storage Credentials are stored at `~/.config/blodemd/credentials.json`. The OAuth session includes a refresh token so the CLI can renew your session automatically. Run `blodemd logout` to remove stored credentials. ## Related pages - [blodemd whoami](https://blode.md/docs/cli/whoami) -- confirm the signed-in email - [blodemd logout](https://blode.md/docs/cli/logout) -- remove stored credentials - [blodemd push](https://blode.md/docs/cli/push) -- deploy after authentication # blodemd logout (https://blode.md/docs/cli/logout) Remove the Blode.md CLI credentials file from your machine so the local OAuth session ends and future deploys require login again. Delete the credentials file saved by `blodemd login` from your local machine. Use `blodemd logout` when you finish on a shared computer, need to switch GitHub accounts, or want to confirm no local credentials remain before handing off a machine. After logout, commands that require auth, such as `blodemd push`, prompt you to run `blodemd login` again. To switch accounts, run `blodemd logout`, then `blodemd login` and verify with `blodemd whoami`. Logout only removes the local credentials file; it does not revoke access in the Blode.md dashboard or delete deployed docs. ```bash blodemd logout ``` The CLI stores credentials at `~/.config/blodemd/credentials.json` (or `%APPDATA%\blodemd\` on Windows). `blodemd logout` removes that file. If the CLI finds no credentials file, it prints a message and exits cleanly. This command has no flags. ## Examples ```bash title="Log out" blodemd logout ``` ### Output ```bash $ blodemd logout ~ Logged out successfully. i Done ``` ```bash $ blodemd logout i No credentials found. ``` ## Related pages - [blodemd login](https://blode.md/docs/cli/login) -- sign in again after logout - [blodemd whoami](https://blode.md/docs/cli/whoami) -- confirm which account is active - [CLI overview](https://blode.md/docs/cli/overview) -- credentials storage and global CLI behavior # blodemd new (https://blode.md/docs/cli/new) Scaffold a new Blode.md docs site with docs.json and an index.mdx starter page, either in the current folder or a docs subdirectory. Create a starter documentation directory with a `docs.json` configuration file and an `index.mdx` page. ```bash blodemd new [directory] ``` Interactive `blodemd new` inspects the current directory first: - If the current directory is empty, it scaffolds there and prompts for the project slug. - If the current directory is not empty, it asks whether to create the docs in a subdirectory or scaffold the current directory. - If prompts are skipped with `--yes` or in a non-interactive environment, it falls back to `docs/`. ## What it creates If you create the docs in a `docs/` subdirectory, `blodemd new` generates the following file tree: - docs/ - docs.json - index.mdx ### docs.json The generated configuration uses the hosted Blode.md schema and a single "Getting Started" navigation group. The `slug` field comes from the slug prompt, `--slug`, or a derived default. The `name` field defaults to a title-cased display name based on that slug unless you pass `--display-name`. ```json title="docs/docs.json" { "$schema": "https://blode.md/docs.json", "name": "My Project", "slug": "my-project", "navigation": { "groups": [ { "group": "Getting Started", "pages": ["index"] } ] } } ``` ### index.mdx A minimal starter page with a title and placeholder content: ```mdx title="docs/index.mdx" --- title: Welcome --- Start writing your docs here. ``` ## Starter template Use the starter template when you want a richer first pass with repo hygiene files, agent instructions, and branding assets: - `.gitignore` - `favicon.svg` - `README.md` - `AGENTS.md` - `CLAUDE.md` - `logo/light.svg` and `logo/dark.svg` - `images/hero-light.svg`, `images/hero-dark.svg`, and `images/checks-passed.svg` - `quickstart.mdx` - `development.mdx` ```bash title="Starter template" blodemd new --template starter ``` `AGENTS.md` links to `CLAUDE.md` when the local filesystem supports symlinks. The default `blodemd new` output stays as the minimal two-file scaffold. > [!INFO] > The starter does not generate a `LICENSE` file. Choose a license explicitly if > the repo will be public or open source. ## Options - `--slug ` (type: string): Project slug written to docs.json. If omitted, interactive mode prompts and non-interactive mode derives it from the chosen location. - `--name ` (type: string): Deprecated alias for `--slug`. - `--display-name ` (type: string): Display name written to docs.json `name`. Defaults to a title-cased version of the slug. - `--template ` (type: string, default: "minimal"): Scaffold an alternate template. Use "starter" for repo hygiene, helper files, and branding assets. - `--yes` (type: boolean, default: false): Accept defaults without prompting. ## Examples ```bash title="Default directory" blodemd new ``` ```bash title="Create docs/ explicitly" blodemd new docs ``` ```bash title="Scaffold the current directory" blodemd new . ``` ```bash title="Set the slug explicitly" blodemd new --slug acme-docs ``` ```bash title="Set slug and display name" blodemd new --slug docs --display-name "Blode.md" ``` ```bash title="Custom directory" blodemd new my-docs ``` ```bash title="Starter template" blodemd new --template starter ``` > [!INFO] > `blodemd new` stops with an error if the target directory already contains any > scaffolded files. It also refuses to scaffold into a non-empty directory > unless you confirm that interactively. ## Next steps 1. Review `docs.json` and change `slug` if you want a different deployment target or `{slug}.blode.md` subdomain. Change `name` if you want a different visible site title. 2. If you used the starter template, replace the generated helper files and brand assets with project-specific content. 3. Add more `.mdx` pages and update the `navigation` array. 4. Run `blodemd push` to deploy. ## Related pages - [blodemd dev](https://blode.md/docs/cli/dev) -- preview the scaffold locally - [blodemd validate](https://blode.md/docs/cli/validate) -- check docs.json after edits - [CLI overview](https://blode.md/docs/cli/overview) -- install and command reference # CLI overview (https://blode.md/docs/cli/overview) Install the blodemd CLI, authenticate with GitHub, and use login, new, validate, dev, push, and analytics commands from your terminal. The blodemd CLI lets you authenticate, create, validate, preview, and deploy documentation from your terminal. ## Installation ```bash npm i -g blodemd ``` Requires Node.js 24.x. The current version is **0.0.8**. ## Commands - `login` (type: command): Authenticate with Blode.md via GitHub in your browser. - `logout` (type: command): Remove stored credentials from your machine. - `whoami` (type: command): Show the current authentication status. - `new` (type: command): Create a new documentation site with a starter docs.json and index page. - `validate` (type: command): Validate your docs.json configuration file against the schema. - `push` (type: command): Deploy documentation to Blode.md. - `dev` (type: command): Start a local development server for real-time preview. ## Command reference ### [blodemd login](https://blode.md/docs/cli/login) Sign in with GitHub in your browser. ### [blodemd new](https://blode.md/docs/cli/new) Create a docs directory with starter files. ### [blodemd push](https://blode.md/docs/cli/push) Deploy your documentation to Blode.md. ### [blodemd dev](https://blode.md/docs/cli/dev) Run a local dev server with live reload. ### [blodemd validate](https://blode.md/docs/cli/validate) Validate your docs.json before deploying. ## Global behavior ### Credentials The CLI stores all authentication state at `~/.config/blodemd/credentials.json` and never sends credentials to any third party. ### Environment variables You can configure the CLI with environment variables instead of flags. - `BLODEMD_API_URL` (type: string, default: https://api.blode.md): Override the API base URL. - `BLODEMD_PROJECT` (type: string): Project slug. Overrides docs.json `slug`. - `BLODEMD_BRANCH` (type: string): Git branch name for the deployment. - `BLODEMD_COMMIT_MESSAGE` (type: string): Commit message attached to the deployment. ## Related pages - [blodemd login](https://blode.md/docs/cli/login) -- authenticate with GitHub - [blodemd new](https://blode.md/docs/cli/new) -- scaffold a new docs site - [Continuous deployment](https://blode.md/docs/deployment/ci) -- automate deploys from GitHub Actions # blodemd push (https://blode.md/docs/cli/push) Deploy your local MDX docs to Blode.md with blodemd push, using a browser session locally or a project deploy key in CI pipelines. Upload your documentation files and publish them to Blode.md in a single command. ```bash blodemd push [dir] ``` Authenticate once with `blodemd login` first. The CLI uses your browser GitHub session for local deploys. For CI, use a project deploy key in `BLODEMD_API_KEY`: see [Continuous deployment](https://blode.md/docs/deployment/ci). ## Directory resolution If you omit the `dir` argument, the CLI searches for a `docs.json` file in these locations (in order): 1. The current working directory 2. `./docs` 3. `./apps/docs` If none contain a `docs.json`, the current directory is used. ## Options - `--project ` (type: string): Project slug. Falls back to the BLODEMD_PROJECT environment variable, then docs.json `slug`. - `--api-key ` (type: string): Project deploy key for CI. Falls back to the BLODEMD_API_KEY environment variable, then stored credentials from `blodemd login`. - `--api-url ` (type: string, default: "https://api.blode.md"): API base URL. - `--branch ` (type: string, default: "main"): Git branch name attached to the deployment. Auto-detected from git if not provided. - `--message ` (type: string): Deploy message. Auto-detected from the latest git commit if not provided. ## Deployment flow When you run `blodemd push`, the CLI executes these steps: 1. **Validate configuration** Reads and parses `docs.json` from the resolved docs directory. 1. **Collect files** Recursively collects all files in the directory. Dotfiles and `node_modules` are skipped automatically. 1. **Create deployment** Sends a request to the Blode.md API to create a new deployment record with the branch and commit message. 1. **Upload files** Uploads files in batches of up to 4 MB each. Large documentation sets are split across multiple requests. 1. **Finalize and promote** The CLI marks the deployment as complete and promotes it to production. Your docs are live immediately. ## Auto-create projects If the project slug does not match an existing project, the CLI prompts you to create one using your authenticated GitHub session. ## Examples ```bash title="Push from default location" blodemd push ``` ```bash title="Push a specific directory" blodemd push ./my-docs ``` ```bash title="Push with explicit project and branch" blodemd push --project my-project --branch staging ``` ## Deploying from CI Prefer not to run the CLI at all? Install the **Blode.md GitHub App** from the project Git tab in the dashboard. Pushes to your configured branch deploy automatically: no CLI, no tokens, no workflows. This is the recommended default. To run the deploy yourself from GitHub Actions or another CI provider, use a project deploy key in `BLODEMD_API_KEY`. See [Continuous deployment](https://blode.md/docs/deployment/ci). ## Skipped files The CLI skips the following entries during file collection: - Files and directories starting with `.` (dotfiles) - The `node_modules` directory ## Related pages - [blodemd login](https://blode.md/docs/cli/login) -- authenticate before your first push - [blodemd validate](https://blode.md/docs/cli/validate) -- fail fast on config errors - [Continuous deployment](https://blode.md/docs/deployment/ci) -- deploy from CI with a project key # blodemd validate (https://blode.md/docs/cli/validate) Validate docs.json and your docs directory before deploy so the CLI catches schema errors, missing files, and common config mistakes early. Check that your `docs.json` file is valid JSON and can be parsed by the CLI before deploying. Run `blodemd validate` early in your workflow to catch schema errors, missing navigation pages, and malformed config before you spend time on preview or deploy. Unlike `blodemd push`, validate does not require authentication, which makes it a good fit for pre-commit hooks and CI jobs that only check configuration. A practical sequence: scaffold with `blodemd new`, edit `docs.json` and add pages, run `blodemd validate`, then `blodemd dev` to preview and `blodemd push` when you are ready. If validate fails, fix the reported issue in `docs.json` or your page paths before trying again. ```bash blodemd validate [dir] ``` ## Directory resolution If you omit the `dir` argument, the CLI searches for `docs.json` in these locations (in order): 1. The current working directory 2. `./docs` 3. `./apps/docs` ## Options ## Examples ```bash title="Validate from default location" blodemd validate ``` ```bash title="Validate a specific directory" blodemd validate ./my-docs ``` ### Successful output ```bash $ blodemd validate ~ docs.json is valid. i Done ``` > [!INFO] > Running `blodemd push` also validates `docs.json` as its first step. A > standalone validate step is useful when you want to fail fast without needing > authentication. ## Related pages - [blodemd push](https://blode.md/docs/cli/push) -- deploy after validate passes - [blodemd new](https://blode.md/docs/cli/new) -- scaffold docs.json and index.mdx - [docs.json reference](https://blode.md/docs/configuration/docs-json) -- schema fields validate checks # blodemd whoami (https://blode.md/docs/cli/whoami) Print the email for the active Blode.md CLI session, refresh stored OAuth credentials when needed, and confirm you are logged in before deploying. Print the email of the active browser session. Run `blodemd whoami` when you need to confirm which GitHub account the CLI will use for deploys. This is especially helpful on shared machines, after switching between personal and work accounts, or when a `blodemd push` fails with an auth error. The command refreshes stored OAuth credentials when possible, so a successful run means your session is still valid for push and dashboard-linked commands. Typical workflow: run `blodemd login` once, then `blodemd whoami` before your first push on a new laptop. If whoami shows the wrong email, run `blodemd logout` and sign in again. ```bash blodemd whoami ``` The CLI reads your stored OAuth session, refreshes it if needed, and displays your email. If your session has expired and can't be refreshed, the CLI prints a warning and asks you to run `blodemd login` again. This command has no flags. ## Examples ```bash $ blodemd whoami ~ Logged in as you@example.com i Done ``` ## Related pages - [blodemd login](https://blode.md/docs/cli/login) -- sign in with GitHub when whoami shows no session - [blodemd logout](https://blode.md/docs/cli/logout) -- clear credentials before switching accounts - [CLI overview](https://blode.md/docs/cli/overview) -- full command list and install steps # Accordion (https://blode.md/docs/components/accordion) Use Accordion and AccordionGroup to hide FAQs and long details behind toggles, keeping docs scannable while still exposing deeper answers on demand. Use the `Accordion` component to hide content behind a toggle. Group multiple accordions together with `AccordionGroup` for a clean, bordered container. ## Basic accordion ```mdx Blode.md uses MDX, which combines standard Markdown with JSX components. You can also reference OpenAPI specs for auto-generated API docs. ``` ### What formats does blodemd support? Blode.md uses MDX, which combines standard Markdown with JSX components. You can also reference OpenAPI specs for auto-generated API docs. ## Accordion group Wrap multiple accordions in an `AccordionGroup` to render them in a single bordered container with dividers: ```mdx Run `blodemd new` in your project directory, then `blodemd dev` to preview locally. Yes. After deploying, add a custom domain in your project settings and update your DNS records. Blode.md offers a generous free tier for open-source and personal projects. ``` ### How do I get started? Run `blodemd new` in your project directory, then `blodemd dev` to preview locally. ### Can I use custom domains? Yes. After deploying, add a custom domain in your project settings and update your DNS records. ### Is there a free tier? Blode.md offers a generous free tier for open-source and personal projects. ## Default open Set `defaultOpen` to expand an accordion on page load: ```mdx You can use this for content that should be visible immediately but still collapsible. ``` ### This section is open by default You can use this for content that should be visible immediately but still collapsible. ## With a description Add a `description` prop to display secondary text below the title: ```mdx Run `blodemd push` to deploy your documentation. Changes go live in seconds. ``` ### Deployment Run `blodemd push` to deploy your documentation. Changes go live in seconds. ## Props ### Accordion - `title` (type: string, required: true): The heading text shown in the toggle button. - `description` (type: string, required: false): Secondary text displayed below the title. - `defaultOpen` (type: boolean, required: false, default: false): Whether the accordion starts expanded. - `id` (type: string, required: false): Custom anchor ID. Defaults to a slugified version of the title. - `icon` (type: ReactNode, required: false): Icon displayed before the title. - `children` (type: ReactNode, required: true): Content revealed when the accordion is open. ### AccordionGroup `AccordionGroup` accepts `children` (one or more `Accordion` components) and renders them in a bordered container. # Callout (https://blode.md/docs/components/callout) Highlight tips, warnings, and critical notes with Callout boxes so readers notice important guidance without breaking the flow of your docs. Use the `Callout` component to draw attention to important information. Each callout type has a distinct color to signal its intent. ## Basic usage Wrap your content in a `` with a `type` prop: ```mdx This is an informational callout. ``` > [!INFO] > This is an informational callout. ## Types There are seven built-in callout types: > [!NOTE] > Use **note** for general-purpose annotations. > [!INFO] > Use **info** for supplemental context. > [!TIP] > Use **tip** for helpful suggestions and best practices. > [!CHECK] > Use **check** to confirm a successful outcome. > [!WARNING] > Use **warning** when something could cause issues. > [!DANGER] > Use **danger** for critical information about destructive actions. > [!SUCCESS] > Use **success** to highlight a positive result. ## Shorthand aliases Each callout type has a shorthand component that you can use without the `type` prop: ```mdx A concise note for your readers. This action cannot be undone. You can combine callouts with other components. ``` > [!NOTE] > A concise note for your readers. > [!WARNING] > This action cannot be undone. > [!INFO] > Shorthand aliases keep your MDX clean and readable. > [!TIP] > You can combine callouts with other components. > [!CHECK] > Your configuration is valid. > [!DANGER] > Deleting a project removes all associated data permanently. The available aliases are ``, ``, ``, ``, ``, and ``. ## With a title Add a `title` prop to display a heading above the callout content: ```mdx The `v2` API removes the `legacy` parameter. Update your integration before upgrading. ``` > [!WARNING] > The `v2` API removes the `legacy` parameter. Update your integration before > upgrading. ## Props - `type` (type: "info" | "success" | "warning" | "danger" | "note" | "tip" | "check", required: false, default: "info"): Visual style of the callout. - `title` (type: string, required: false): Optional heading displayed above the content. - `icon` (type: ReactNode, required: false): Custom icon rendered before the content. - `color` (type: string, required: false): Custom border and background color (hex or CSS color). - `children` (type: ReactNode, required: true): The callout content. # Card (https://blode.md/docs/components/card) Present features, links, and related pages in Card containers, alone or in grids, with optional icons and hrefs for clearer docs navigation. Use the `Card` component to present content in a bordered container. Cards work well for feature highlights, navigation links, and content grids. ## Basic card ```mdx Learn how to set up your first documentation project. ``` ### Getting started Learn how to set up your first documentation project. ## Link card Add an `href` prop to make the entire card clickable. An arrow indicator appears automatically: ```mdx Set up a documentation site in under five minutes. ``` ### [Quickstart guide](https://blode.md/docs/quickstart) Set up a documentation site in under five minutes. ## Card with call to action Use the `cta` prop to display a text label at the bottom of the card: ```mdx Serve your docs from your own domain with automatic SSL. ``` ### [Custom domains](https://blode.md/docs/features/custom-domains) Serve your docs from your own domain with automatic SSL. ## Card grid Combine cards with `Columns` to create a responsive grid: ```mdx Commands for building and deploying docs. Customize your project settings. Write documentation with Markdown and JSX. Full-text search built into every project. ``` ### [CLI reference](https://blode.md/docs/cli/overview) Commands for building and deploying docs. ### [Configuration](https://blode.md/docs/configuration/docs-json) Customize your project settings. ### [MDX basics](https://blode.md/docs/content/mdx-basics) Write documentation with Markdown and JSX. ### [Search](https://blode.md/docs/features/search) Full-text search built into every project. ## Horizontal layout Set `horizontal` to arrange the icon and content side by side: ```mdx Content flows beside the icon in a horizontal layout. ``` ### Horizontal card Content flows beside the icon in a horizontal layout. ## Props - `title` (type: string, required: false): Heading displayed at the top of the card. - `icon` (type: ReactNode, required: false): Icon rendered above the title. - `color` (type: string, required: false): Custom color for the icon. - `href` (type: string, required: false): URL that makes the card clickable. External links open in a new tab. - `horizontal` (type: boolean, required: false): Arrange icon and content side by side. - `img` (type: string, required: false): Image URL displayed at the top of the card. - `cta` (type: string, required: false): Call-to-action text displayed at the bottom. - `children` (type: ReactNode, required: false): Card body content. # Code group (https://blode.md/docs/components/code-group) Show related code samples in a CodeGroup with tabbed navigation so readers can switch languages, package managers, or tools in one place. Use the `CodeGroup` component to show multiple related code blocks in a single tabbed container. This is useful for showing the same command or snippet across different languages or tools. Use `CodeGroup` whenever readers need the same instruction in more than one form: package managers, programming languages, or shell variants. It keeps the page shorter than stacking separate code blocks and lets readers pick their stack without scrolling past irrelevant commands. Tab labels come from each fence's `title` attribute, so name tabs explicitly when two blocks share a language. On quickstart pages, a common pattern is a `CodeGroup` with npm, pnpm, and yarn install commands followed by `blodemd new`. For API reference pages, group Node.js, Python, and cURL examples so integrators can copy the sample that matches their backend. ## Basic usage Wrap two or more fenced code blocks inside ``. Each tab is labeled from the `title` attribute on the code block: ```text ```bash title="npm" npm install blodemd ``` ```bash title="pnpm" pnpm add blodemd ``` ```bash title="yarn" yarn add blodemd ``` ``` ```bash title="npm" npm install blodemd ``` ```bash title="pnpm" pnpm add blodemd ``` ```bash title="yarn" yarn add blodemd ``` ## Multi-language example Show the same API call in different programming languages: ```text ```javascript title="Node.js" const res = await fetch("https://api.blode.md/v1/projects", { headers: { Authorization: `Bearer ${API_KEY}` }, }); const data = await res.json(); ``` ```python title="Python" import requests res = requests.get( "https://api.blode.md/v1/projects", headers={"Authorization": f"Bearer {API_KEY}"}, ) data = res.json() ``` ```bash title="cURL" curl -H "Authorization: Bearer $API_KEY" \ https://api.blode.md/v1/projects ``` ``` ```javascript title="Node.js" const res = await fetch("https://api.blode.md/v1/projects", { headers: { Authorization: `Bearer ${API_KEY}` }, }); const data = await res.json(); ``` ```python title="Python" import requests res = requests.get( "https://api.blode.md/v1/projects", headers={"Authorization": f"Bearer {API_KEY}"}, ) data = res.json() ``` ```bash title="cURL" curl -H "Authorization: Bearer $API_KEY" \ https://api.blode.md/v1/projects ``` ## Tab labels Tabs are labeled in this order of priority: 1. The `title` attribute on the code fence, such as ```bash title="npm" 2. The language identifier (e.g., `javascript`, `python`) 3. A generic fallback like "Tab 1" > [!TIP] > Always set explicit `title` attributes when the language alone does not > distinguish the tabs. ## Related pages - [Code blocks](https://blode.md/docs/content/code-blocks) -- syntax highlighting and titles for single snippets - [Tabs](https://blode.md/docs/components/tabs) -- tabbed prose or mixed content, not just code - [Installer](https://blode.md/docs/components/installer) -- copyable install command when only one package manager matters # Columns (https://blode.md/docs/components/columns) Arrange Cards and other content in responsive Columns that stack on small screens and expand into multi-column layouts on larger viewports. Use the `Columns` component to create responsive grid layouts. Columns stack on small screens and expand on larger viewports. ## Two-column layout The default `cols` value is `2`: ```mdx Use standard Markdown with built-in components. Push your changes and go live in seconds. ``` ### Write in MDX Use standard Markdown with built-in components. ### Deploy instantly Push your changes and go live in seconds. ## Three-column layout Set `cols={3}` for a three-column grid: ```mdx Build and deploy from your terminal. Rich UI elements for your content. Full-text search out of the box. ``` ### [CLI](https://blode.md/docs/cli/overview) Build and deploy from your terminal. ### [Components](https://blode.md/docs/components/callout) Rich UI elements for your content. ### [Search](https://blode.md/docs/features/search) Full-text search out of the box. ## With Column wrapper Use the `Column` component when you need to place non-card content in the grid: ```mdx ### Left side You can put any Markdown or components in a column. ### Right side Columns are useful for side-by-side comparisons. ``` ### Left side You can put any Markdown or components in a column. ### Right side Columns are useful for side-by-side comparisons. ## Props ### Columns - `cols` (type: 1 | 2 | 3 | 4, required: false, default: 2): Number of columns in the grid. - `children` (type: ReactNode, required: true): Grid content (cards, Column components, or other elements). ### Column `Column` accepts `children` and renders them inside a single grid cell. # Expandable (https://blode.md/docs/components/expandable) Hide nested properties, optional fields, and advanced options behind Expandable sections so reference docs stay readable without losing detail. Use the `Expandable` component to hide supplementary details behind a toggle. This is useful for documenting nested objects, optional configuration, or advanced options without overwhelming the reader. ## Basic usage ```mdx - **name** (`string`): Display name of the item. - **value** (`number`): Numeric value associated with the item. - **metadata** (`object`): Additional key-value pairs. ``` ### child properties - **name** (`string`): Display name of the item. - **value** (`number`): Numeric value associated with the item. - **metadata** (`object`): Additional key-value pairs. ## Default open Set `defaultOpen` to reveal the content on page load: ```mdx - **id** (`string`): Unique identifier. - **status** (`"active" | "archived"`): Current status. - **createdAt** (`string`): ISO 8601 timestamp. ``` ### response fields - **id** (`string`): Unique identifier. - **status** (`"active" | "archived"`): Current status. - **createdAt** (`string`): ISO 8601 timestamp. ## Nested expandables You can nest expandables to document deeply nested structures: ```mdx - **name** (`string`): Project name. - **config** (`object`): Project configuration. - **appearance** (`object`): Light and dark mode settings. - **navigation** (`array`): Sidebar navigation items. ``` ### project properties - **name** (`string`): Project name. - **config** (`object`): Project configuration. ### config properties - **appearance** (`object`): Light and dark mode settings. - **navigation** (`array`): Sidebar navigation items. ## Props - `title` (type: string, required: false, default: "properties"): Label for the toggle button. - `defaultOpen` (type: boolean, required: false, default: false): Whether the section starts expanded. - `children` (type: ReactNode, required: true): Content revealed when expanded. # Frame (https://blode.md/docs/components/frame) Wrap screenshots, diagrams, and media in a Frame with an optional caption to separate visuals from body copy in your documentation pages. Use the `Frame` component to visually set apart screenshots, diagrams, or other media with a bordered container and an optional caption. Reach for `Frame` when a screenshot or diagram needs more visual weight than an inline image. Product walkthroughs, dashboard tours, and configuration guides benefit from a bordered container that separates the visual from surrounding prose. Add a `caption` to explain what the reader should notice, or a `hint` when the image is clickable or opens in a lightbox-style view in your theme. On a feature page, write the steps in prose, drop in a `Frame` with the relevant UI screenshot, then continue with the next section. Captions work well for before-and-after comparisons or calling out a specific control in a busy dashboard. ## Basic frame ```mdx ![Dashboard overview](https://blode.md/docs/images/dashboard.png) ``` ## With a caption Add a `caption` prop to display centered text below the frame: ```mdx ![Dashboard overview](https://blode.md/docs/images/dashboard.png) ``` A placeholder for a screenshot or diagram. Caption: The project dashboard shows recent deployments and page analytics. ## With a hint Use the `hint` prop to display helper text above the frame: ```mdx ![Navigation config](https://blode.md/docs/images/nav-config.png) ``` Click to enlarge A placeholder for a screenshot or diagram. Caption: Navigation configuration in docs.json ## Props - `caption` (type: string, required: false): Text displayed below the frame as a figcaption. - `hint` (type: string, required: false): Helper text displayed above the frame. - `children` (type: ReactNode, required: true): Content rendered inside the bordered container. ## Related pages - [Callout](https://blode.md/docs/components/callout) -- highlight tips or warnings alongside screenshots - [Card](https://blode.md/docs/components/card) -- link to related feature pages from visual sections - [Code blocks](https://blode.md/docs/content/code-blocks) -- show configuration snippets next to UI screenshots # Installer (https://blode.md/docs/components/installer) Display a copyable package install command with the Installer component, including a styled default command generated from a package path. Use the `Installer` component to show a copyable installation command in a styled container. Place an `Installer` near the top of quickstart and onboarding pages so readers can install the CLI before they run other commands. The built-in copy button means they do not need to select text from a plain code block. If your docs cover multiple package managers, pass a custom `command` prop or pair this component with [Code group](https://blode.md/docs/components/code-group) for npm, pnpm, and yarn variants on the same page. A typical getting started flow: show the install command, link to [CLI overview](https://blode.md/docs/cli/overview), then walk through `blodemd new` and `blodemd dev`. On the CLI overview page itself, `Installer` renders the global install command with one line of MDX. ## Basic usage Pass a `command` prop with the full install command: ```mdx ``` ```bash npm install blodemd ``` ## Default command If you omit the `command` prop, a default command is generated from the `path` value: ```mdx ``` ## Props - `path` (type: string, required: true): Package path used to generate the default command. - `command` (type: string, required: false): Custom install command. Overrides the default generated from `path`. ## Related pages - [CLI overview](https://blode.md/docs/cli/overview) -- install the CLI and browse all commands - [Code group](https://blode.md/docs/components/code-group) -- show npm, pnpm, and yarn install commands in tabs - [Tabs](https://blode.md/docs/components/tabs) -- switch between related install or setup instructions # Steps (https://blode.md/docs/components/steps) Guide readers through numbered instructions with Steps and Step components so setup, install, and deploy workflows stay clear and sequential. Use the `Steps` and `Step` components to present sequential instructions. Each step is automatically numbered. ## Basic usage ```text Run the install command for your package manager: ```bash npm i -g blodemd ``` Create a new docs project in the current directory: ```bash blodemd new ``` Preview your documentation locally: ```bash blodemd dev ``` ``` 1. **Install the CLI** Run the install command for your package manager: ```bash npm i -g blodemd ``` 1. **Create your project** Create a new docs project in the current directory: ```bash blodemd new ``` 1. **Start the dev server** Preview your documentation locally: ```bash blodemd dev ``` ## Title sizing Control the heading level of step titles with `titleSize`, either on individual steps or on the parent `Steps` component: ```mdx Edit `docs.json` to set your project name and navigation. Create MDX files in the `docs/` directory. ``` 1. **Configure your project** Edit `docs.json` to set your project name and navigation. 1. **Write your content** Create MDX files in the `docs/` directory. ## Props ### Steps - `titleSize` (type: "p" | "h2" | "h3" | "h4", required: false, default: "p"): Default heading level for all child steps. - `children` (type: ReactNode, required: true): One or more Step components. ### Step - `title` (type: string, required: true): The step heading text. - `icon` (type: ReactNode, required: false): Custom icon to replace the step number. - `stepNumber` (type: number, required: false): Override the automatic step number. - `titleSize` (type: "p" | "h2" | "h3" | "h4", required: false, default: "p"): Heading level for this step. Overrides the parent value. - `children` (type: ReactNode, required: false): Content displayed below the step title. # Tabs (https://blode.md/docs/components/tabs) Organize alternate content into Tabs and Tab panels so readers can switch between related options without leaving the documentation page. Use the `Tabs` and `Tab` components to let readers switch between related content without leaving the page. ## Basic tabs Each `Tab` needs a `title` prop to label its tab button: ```text `npm install blodemd` `pnpm add blodemd` `yarn add blodemd` ``` ### npm `npm install blodemd` ### pnpm `pnpm add blodemd` ### yarn `yarn add blodemd` ## Content tabs Tabs work with any content, not just code: ```mdx Blode.md turns your Markdown files into a production-ready documentation site. - Full-text search - Custom domains - OpenAPI integration - Built-in components ``` ### Overview Blode.md turns your Markdown files into a production-ready documentation site. ### Features - Full-text search - Custom domains - OpenAPI integration - Built-in components ## Default tab Use `defaultTabIndex` on `Tabs` to set which tab is active on load (zero-indexed): ```mdx This tab is not selected by default. This tab is selected by default. ``` ### First This tab is not selected by default. ### Second This tab is selected by default. ## Props ### Tabs - `defaultTabIndex` (type: number, required: false, default: 0): Index of the tab to show on initial render. - `children` (type: ReactNode, required: true): One or more Tab components. ### Tab - `title` (type: string, required: false): Label displayed on the tab button. You can also use `label` as an alias. - `icon` (type: ReactNode, required: false): Icon displayed before the tab label. - `children` (type: ReactNode, required: true): Content shown when the tab is active. # Tree (https://blode.md/docs/components/tree) Visualize file and folder hierarchies with the Tree component, including collapsible folders for interactive project structure examples. Use the `Tree` component to visualize file and folder hierarchies. Folders are collapsible by default, giving readers an interactive way to explore project structures. ## Basic usage ```mdx ``` - docs/ - index.mdx - quickstart.mdx - components/ - callout.mdx - card.mdx - tabs.mdx - docs.json - package.json ## Collapsed by default Omit `defaultOpen` to keep folders collapsed. Readers can click to expand them: ```mdx ``` - src/ - components/ - header.tsx - footer.tsx - lib/ - utils.ts - index.ts ## Non-openable folders Set `openable={false}` to display a folder that cannot be expanded, useful for indicating a directory without listing its contents: ```mdx ``` - public/ - src/ - app.tsx - node_modules/ ## Props ### Tree `Tree` renders a bordered container for the file hierarchy. It accepts `children`. ### Tree.Folder - `name` (type: string, required: true): Folder name displayed in the tree. - `defaultOpen` (type: boolean, required: false, default: false): Whether the folder starts expanded. - `openable` (type: boolean, required: false, default: true): Whether the folder can be toggled open and closed. - `children` (type: ReactNode, required: false): Nested files and folders. ### Tree.File - `name` (type: string, required: true): File name displayed in the tree. # Type table (https://blode.md/docs/components/type-table) Document props, API fields, and config shapes with TypeTable so readers can scan types, requirements, defaults, and descriptions in one place. Use the `TypeTable` component to document object shapes, API responses, and component props in a structured table. ## Basic usage Pass a `type` object where each key is a field name and the value describes its type, description, and constraints: ```mdx ``` - `id` (type: string, required: true): Unique project identifier. - `name` (type: string, required: true): Display name of the project. - `slug` (type: string, required: true): URL-safe project slug. - `customDomain` (type: string, required: false): Custom domain if configured. - `createdAt` (type: string, required: true): ISO 8601 timestamp of project creation. ## With default values When any field includes a `default` property, a Default column appears automatically: ```mdx ``` - `appearance` (type: "system" | "light" | "dark", required: false, default: "system"): Initial color mode for the site. - `lang` (type: string, required: false, default: "plaintext"): Default language for code blocks. - `toc` (type: boolean, required: false, default: true): Show a table of contents on each page. ## Field options Each field in the `type` object supports these properties: - `description` (type: string, required: false): Human-readable explanation of the field. - `type` (type: string, required: false): The field's type annotation. - `required` (type: boolean, required: false): Whether the field is required. Defaults to the inverse of `optional`. - `optional` (type: boolean, required: false): Whether the field is optional. Inverse of `required`. - `default` (type: string, required: false): Default value shown in the table. # docs.json reference (https://blode.md/docs/configuration/docs-json) Reference every supported docs.json field for navigation, branding, collections, OpenAPI, analytics, and deployment settings in your Blode.md project. Every Blode.md project is configured through a single `docs.json` file at the root of your docs directory. > [!INFO] > If you are coming from Mintlify, Blode.md intentionally keeps this contract > smaller. `theme`, `colors`, `fonts`, `icons`, `background`, and `styling` are > not supported in `docs.json`. ## Minimal example ```json title="docs.json" { "$schema": "https://blode.md/docs.json", "name": "My Project", "slug": "my-project", "navigation": { "groups": [{ "group": "Getting started", "pages": ["index"] }] } } ``` ## Branded example ```json title="docs.json" { "$schema": "https://blode.md/docs.json", "name": "My Project", "slug": "my-project", "description": "Documentation for my product.", "logo": { "light": "/logo/light.svg", "dark": "/logo/dark.svg", "alt": "Example Co. logo", "href": "/" }, "favicon": "/favicon.svg", "appearance": { "default": "system" }, "navbar": { "links": [{ "label": "GitHub", "href": "`github.com/example/docs`" }] }, "navigation": { "tabs": [ { "tab": "Guides", "groups": [ { "group": "Getting started", "pages": ["index", "quickstart"] } ] } ] }, "contextual": { "options": ["copy", "view", "chatgpt", "claude"] }, "api": { "openapi": "openapi.yaml", "playground": { "display": "interactive" } }, "seo": { "indexing": "all" } } ``` ## Top-level fields - `$schema` (type: string): JSON Schema URL for editor autocomplete. Use `https://blode.md/docs.json`. - `name` (type: string, required: true): Display name for your site, project, or organization. - `slug` (type: string): Recommended URL-safe project slug used for deployments and the default `{slug}.blode.md` hostname. - `description` (type: string): Short project description used in metadata and SEO. - `logo` (type: string | { light, dark, alt?, href? }): Logo shown in the header. Accepts a single path or `{ light, dark, alt?, href? }`. - `favicon` (type: string | { light, dark }): Browser tab icon. Accepts a single path or `{ light, dark }`. - `appearance` (type: object): Light and dark mode settings. Set `default` to `dark`, `light`, or `system`. Use `strict` to lock the site mode. - `navbar` (type: object): Header links shown above your content. - `navigation` (type: object, required: true): Sidebar and tab structure. Defines the hierarchy of your pages. See [Navigation](https://blode.md/docs/configuration/navigation). - `api` (type: object): API reference configuration for OpenAPI and AsyncAPI sources plus playground settings. - `contextual` (type: object): Contextual action buttons shown on each page, such as copy, view source, or assistant shortcuts. - `search` (type: object): Search configuration. - `seo` (type: object): Search engine indexing settings. - `metadata` (type: object): Metadata configuration. ## Branding fields - `logo.light` (type: string): Logo path for light mode. - `logo.dark` (type: string): Logo path for dark mode. - `logo.alt` (type: string): Accessible alt text for the logo image. - `logo.href` (type: string): Optional destination when someone clicks the logo. Defaults to the docs homepage. - `favicon.light` (type: string): Favicon path for light mode. - `favicon.dark` (type: string): Favicon path for dark mode. - `appearance.default` (type: 'system' | 'light' | 'dark'): Initial color mode. Defaults to `system`. - `appearance.strict` (type: boolean): When `true`, hides the mode toggle and locks the site to the selected default mode. ## API reference The `api` object controls OpenAPI and AsyncAPI rendering plus playground behavior. - `api.openapi` (type: string | string[] | OpenApiSource): Path to your OpenAPI spec. Accepts a string, array of strings, or a source object with `source`, `basePath`, `directory`, and `include`. - `api.asyncapi` (type: string | string[] | OpenApiSource): Path to your AsyncAPI spec. Same format as `openapi`. - `api.playground` (type: { display?: 'auth' | 'interactive' | 'none' | 'simple', proxy?: boolean, credentials?: boolean }): API playground settings. - `api.examples` (type: { autogenerate?: boolean, defaults?: 'all' | 'required', languages?: string[], prefill?: boolean }): Autogenerated code example settings. - `api.params` (type: { expanded?: 'all' | 'closed' }): Parameter display settings. - `api.mdx` (type: { auth?: { method, name }, server?: string | string[] }): MDX API page settings. - `api.url` (type: 'full'): URL display mode for endpoint headers. ## Contextual actions - `contextual.display` (type: 'header' | 'toc'): Where to render the action buttons. - `contextual.options` (type: Array): Array of built-in presets or custom action objects. Built-in option presets: `copy`, `view`, `chatgpt`, `claude`, `perplexity`, `grok`, `aistudio`, `cursor`, `vscode`, `windsurf`, `devin`, `mcp`, `add-mcp`, `devin-mcp`, `assistant`. ## Validation Run `blodemd validate` to check your `docs.json` against the schema before deploying: ```bash blodemd validate ``` Validation is strict: an unknown key is an error, so a typo like `nvaigation` fails before it ships rather than silently doing nothing. A published site is served leniently. If a deployed `docs.json` contains a key the platform does not recognise: because it was written for a newer version, or a field was retired: the site keeps rendering and the key is ignored. Only genuine problems, like a navigation tree of the wrong shape, stop a page from being served. Your docs never go down because of a config key. ## Related pages - [Navigation](https://blode.md/docs/configuration/navigation) -- configure sidebar groups, tabs, and page ordering - [Appearance and branding](https://blode.md/docs/configuration/theming) -- configure logo, favicon, and color mode behavior # Navigation (https://blode.md/docs/configuration/navigation) Configure sidebar groups, tabs, nested pages, hidden routes, and page ordering in docs.json to control how readers browse your documentation site. You control the sidebar hierarchy, tabbed sections, and hidden pages through the `navigation` object in `docs.json`. This page covers every navigation feature. ## Groups Groups organize pages into collapsible sidebar sections. Each group has a label and a list of page slugs. ```json title="docs.json" { "navigation": { "groups": [ { "group": "Getting started", "pages": ["index", "quickstart"] }, { "group": "Guides", "pages": ["guides/authentication", "guides/deployment"] } ] } } ``` - `group` (type: string): Display label for the sidebar section. - `pages` (type: string[]): Array of page slugs. Each slug maps to an MDX file relative to your docs root. - `expanded` (type: boolean): Whether the group is expanded by default. Defaults to `true` for the first group. - `hidden` (type: boolean): Hide this group from the sidebar while keeping its pages accessible by URL. ### Directory paths Page slugs map directly to file paths. A slug like `domains/custom-domains` resolves to `domains/custom-domains.mdx` in your docs directory. ``` docs/ domains/ custom-domains.mdx -> slug: "domains/custom-domains" ssl.mdx -> slug: "domains/ssl" index.mdx -> slug: "index" ``` ## Tabs Tabs add top-level sections to your documentation. Each tab contains its own set of groups, creating separate sidebar navigations. ```json title="docs.json" { "navigation": { "tabs": [ { "tab": "Guides", "groups": [ { "group": "Getting started", "pages": ["index", "quickstart"] } ] }, { "tab": "API reference", "groups": [ { "group": "Endpoints", "pages": ["api/users", "api/projects"] } ] }, { "tab": "Changelog", "href": "/changelog" } ] } } ``` - `tab` (type: string, required: true): Display label for the tab. This is the `label` field in the schema. - `groups` (type: Array): Array of sidebar groups displayed when this tab is active. - `pages` (type: string[]): Flat list of page slugs (alternative to groups for simple tabs). - `href` (type: string): External URL. When set, clicking the tab navigates away instead of showing a sidebar. - `icon` (type: string): Icon name displayed next to the tab label. > [!INFO] > A tab must define at least one of `groups`, `pages`, or `href`. ## Hidden pages Use the `hidden` array to keep pages accessible by URL without showing them in the sidebar. This is useful for deprecated pages, redirects, or unlisted content. ```json title="docs.json" { "navigation": { "hidden": ["internal/debug", "legacy/old-api"], "groups": [{ "group": "Guides", "pages": ["index", "quickstart"] }] } } ``` ## OpenAPI auto-generated pages You can generate API reference pages directly from an OpenAPI spec by adding an `openapi` field to a group instead of listing pages manually. ```json title="String source" { "group": "API reference", "openapi": "openapi.yaml" } ``` ```json title="Object source" { "group": "API reference", "openapi": { "source": "openapi.yaml", "basePath": "/api", "directory": "api-ref", "include": ["GET /users", "POST /users"] } } ``` - `source` (type: string, required: true): Path to your OpenAPI spec file. - `basePath` (type: string): Base path prefix for generated page slugs. - `directory` (type: string): Output directory for generated MDX files. - `include` (type: string[]): Filter to specific operations (e.g., `GET /users`). ## Splitting navigation with $ref For large projects, you can split your navigation into separate JSON files using `$ref`. This keeps your main `docs.json` manageable. ```json title="docs.json" { "navigation": { "tabs": [{ "$ref": "./nav/guides.json" }, { "$ref": "./nav/api.json" }] } } ``` ```json title="nav/guides.json" { "tab": "Guides", "groups": [{ "group": "Getting started", "pages": ["index", "quickstart"] }] } ``` ## Versions Version dropdowns let you maintain multiple documentation versions from a single project. ```json title="docs.json" { "navigation": { "versions": [ { "label": "v2.0", "url": "/v2" }, { "label": "v1.0", "url": "/v1" } ], "groups": [...] } } ``` - `label` (type: string, required: true): Version label displayed in the dropdown. - `url` (type: string, required: true): URL path or full URL for this version. ## Languages Language selectors let you link to translated versions of your documentation. ```json title="docs.json" { "navigation": { "languages": [ { "label": "English", "url": "/en" }, { "label": "Japanese", "url": "/ja", "locale": "ja" } ], "groups": [...] } } ``` - `label` (type: string, required: true): Language name displayed in the selector. - `url` (type: string, required: true): URL path or full URL for this language. - `locale` (type: string): BCP 47 locale code (e.g., `ja`, `fr`, `zh-CN`). ## Global anchors Global anchors appear as persistent links in the navigation, visible across all tabs. Use them for external resources like your dashboard, community, or changelog. ```json title="docs.json" { "navigation": { "global": { "anchors": [ { "label": "Community", "href": "/community" }, { "label": "Dashboard", "href": "/app" } ], "links": [ { "label": "Blog", "href": "/blog" } ] }, "groups": [...] } } ``` - `global.anchors` (type: Array<{ label: string, href: string }>): Persistent anchor links shown across all tabs. - `global.links` (type: Array<{ label: string, href: string }>): Additional navigation links shown globally. ## Complete navigation schema The full navigation object supports all of the following fields: - `tabs` (type: Array): Top-level tabbed sections. Each tab has its own sidebar. - `groups` (type: Array): Sidebar groups when not using tabs. - `pages` (type: string[]): Flat list of page slugs (simplest form, no grouping). - `hidden` (type: string[]): Page slugs accessible by URL but not shown in the sidebar. - `versions` (type: Array<{ label, url }>): Version dropdown entries. - `languages` (type: Array<{ label, url, locale? }>): Language selector entries. - `global` (type: { anchors?, links? }): Global anchors and links visible across all tabs. > [!INFO] > Your navigation must define at least one of `groups`, `pages`, `tabs`, > `languages`, or `versions`. # Appearance and branding (https://blode.md/docs/configuration/theming) Configure logo, favicon, and appearance settings in docs.json, including separate light and dark assets and supported branding options for your site. Blode.md keeps site branding intentionally narrow. Use `logo`, `favicon`, and `appearance` in `docs.json` to control the parts of the visual identity that are currently supported. The `logo` and `favicon` shapes follow Mintlify's light and dark asset pattern, and Blode.md also accepts `logo.alt` for accessible text. > [!INFO] > Blode.md does not support Mintlify's `theme`, `colors`, `fonts`, `icons`, > `background`, or `styling` fields. ## Logo Use `logo` to show a single mark everywhere or separate assets for light and dark mode. ### Tab ```json title="docs.json" { "logo": { "light": "/logo/light.svg", "dark": "/logo/dark.svg", "alt": "Example Co. logo", "href": "/" } } ``` ### Tab ```json title="docs.json" { "logo": "/logo/logo.svg" } ``` - `light` (type: string): Logo image path or URL for light mode. - `dark` (type: string): Logo image path or URL for dark mode. - `href` (type: string): Optional destination when someone clicks the logo. Defaults to your docs homepage. - `alt` (type: string): Accessible alt text for the logo image. ## Favicon Use `favicon` for the browser tab icon. ```json title="Single favicon" { "favicon": "/favicon.svg" } ``` ```json title="Light and dark variants" { "favicon": { "light": "/favicon-light.svg", "dark": "/favicon-dark.svg" } } ``` ## Appearance Use `appearance` to control the initial light or dark mode and whether readers can switch modes. ```json title="docs.json" { "appearance": { "default": "dark", "strict": true } } ``` - `default` (type: 'system' | 'light' | 'dark'): Default color mode. Choose `system`, `light`, or `dark`. - `strict` (type: boolean): When `true`, locks the site to the default mode and hides the theme toggle. ## Example ```json title="docs.json" { "$schema": "https://blode.md/docs.json", "name": "Example Docs", "slug": "example-docs", "logo": { "light": "/logo/light.svg", "dark": "/logo/dark.svg", "alt": "Example Co. logo", "href": "/" }, "favicon": "/favicon.svg", "appearance": { "default": "system" }, "navigation": { "groups": [{ "group": "Getting started", "pages": ["index"] }] } } ``` Blode.md uses its built-in visual system for layout, typography, and component styling. Branding today is about the assets and mode behavior you provide here, not per-site theme tokens. # Code blocks (https://blode.md/docs/content/code-blocks) Use fenced code blocks with Shiki syntax highlighting, optional titles for filenames, and CodeGroup tabs for multi-file or multi-language examples. Fenced code blocks are automatically syntax-highlighted using Shiki with dual themes (light and dark). ## Basic usage Use triple backticks with a language identifier: ```text ```javascript const greeting = "Hello, world!"; console.log(greeting); ``` ``` ## Titles Add a filename or label with the `title` attribute: ```text ```typescript title="src/config.ts" export const config = { name: "my-project", version: "1.0.0", }; ``` ``` ## Supported languages Shiki supports over 300 languages, including: `javascript`, `typescript`, `python`, `go`, `rust`, `bash`, `json`, `yaml`, `mdx`, `sql`, `css`, `html`, and many more. ## Multi-file examples Use the `CodeGroup` component to show multiple related code blocks with tabbed navigation: ```text ```bash title="npm" npm install blodemd ``` ```bash title="pnpm" pnpm add blodemd ``` ```bash title="yarn" yarn add blodemd ``` ``` Tabs are automatically labeled from the `title` attribute. If no title is set, the language name is used. ## Inline code Use single backticks for inline code: `` `blodemd push` `` renders as `blodemd push`. # Frontmatter (https://blode.md/docs/content/frontmatter) Reference every YAML frontmatter field for Blode.md pages, including title, description, sidebarTitle, icon, and SEO options with examples. Every MDX page starts with YAML frontmatter between `---` delimiters. The `title` field is required. All other fields are optional. ## Fields - `title` (type: string, required: true): Page title displayed in the header and browser tab. - `description` (type: string): Summary used in meta tags and search results. - `sidebarTitle` (type: string): Override the title shown in the sidebar navigation. - `icon` (type: string): Icon displayed next to the page title in the sidebar. - `iconType` (type: "regular" | "solid" | "light" | "thin" | "sharp-solid" | "duotone" | "brands"): Icon style variant. - `mode` (type: "default" | "wide" | "custom" | "frame" | "center", default: "default"): Page layout mode. - `hidden` (type: boolean, default: false): Hide this page from navigation. The page is still accessible via direct URL. - `deprecated` (type: boolean, default: false): Mark the page as deprecated. Displays a deprecation badge. - `noindex` (type: boolean, default: false): Prevent search engines from indexing this page. - `keywords` (type: string[]): Additional keywords for search indexing. - `tag` (type: string): Display a tag badge next to the page title. - `url` (type: string): Override the navigation link to point to an external URL. - `hideApiMarker` (type: boolean): Hide the API method badge on OpenAPI pages. - `hideFooterPagination` (type: boolean): Hide the previous/next navigation at the bottom of the page. ## Example ```yaml --- title: Authentication description: Learn how to authenticate API requests. icon: lock tag: Updated mode: wide --- ``` # MDX basics (https://blode.md/docs/content/mdx-basics) Learn how to write Blode.md documentation with standard Markdown, GFM syntax, and built-in JSX components that need no import statements. MDX combines Markdown with JSX components. You write standard Markdown, and when you need richer elements, you use built-in components directly in your content. No imports are needed. ## Markdown All standard Markdown syntax works, including GitHub Flavored Markdown (GFM): - **Headings**: `#`, `##`, `###`, etc. - **Bold** and _italic_ text - Lists (ordered and unordered) - [Links](https://blode.md) and images - Blockquotes - Tables - Fenced code blocks with syntax highlighting ## Using components Blode.md provides over 30 built-in components. Use them directly in your MDX without any import statements: ```mdx This is a paragraph with standard Markdown. This is a callout component rendered inline. ``` Components accept props just like JSX: ```mdx Card content goes here. ``` ## Frontmatter Every page starts with YAML frontmatter between `---` delimiters: ```mdx --- title: My page title description: A brief summary of this page. --- Page content starts here. ``` The `title` field is required. See the [frontmatter reference](https://blode.md/docs/content/frontmatter) for all available fields. ## File naming Pages are referenced by their file path without the `.mdx` extension. A file at `getting-started/installation.mdx` is referenced as `"getting-started/installation"` in your navigation config. > [!NOTE] > File names become URL slugs. Use lowercase with hyphens: `my-page.mdx`, not > `My Page.mdx`. ## Component reference Browse all available components in the [Components](https://blode.md/docs/components/callout) tab. # Continuous deployment (https://blode.md/docs/deployment/ci) Deploy docs automatically with the GitHub App on every push, or run blodemd push from GitHub Actions and other CI providers using a deploy key. Blode.md deploys your docs on every push. The GitHub App is the zero-config default; if you'd rather run the deploy yourself, use a project deploy key from CI. ## GitHub App (recommended) Connect your repository in the dashboard **Git** tab. Every push to your configured branch deploys automatically -- no tokens, no workflow file, no CLI. This is the simplest path and the right default for most projects. > [!INFO] > The GitHub App handles authentication for you. You only need a deploy key if > you deploy from your own CI pipeline instead. ## Deploy from CI (GitHub Actions) To run the deploy yourself, add a workflow that calls `blodemd push` with a project deploy key in the `BLODEMD_API_KEY` secret: ```yaml title=".github/workflows/deploy.yml" name: Deploy docs on: push: branches: [main] jobs: deploy: runs-on: ubuntu-latest steps: - uses: actions/checkout@v5 - uses: actions/setup-node@v5 with: node-version: 24 - run: npx blodemd@latest push --project your-project-slug env: BLODEMD_API_KEY: ${{ secrets.BLODEMD_API_KEY }} ``` Store the key as a repository secret named `BLODEMD_API_KEY`. See [Getting a deploy key](#getting-a-deploy-key) below. ## Other CI providers The same command works on any CI provider: 1. Add your deploy key as a secret named `BLODEMD_API_KEY`. 2. Run `npx blodemd@latest push --project ` in your deploy step. If you prefer to pass the key inline instead of the environment variable, use the `--api-key ` flag. The CLI reads the project slug from your `docs.json` `slug` field when `--project` is omitted, and it auto-detects the branch from `GITHUB_REF_NAME` (or the current git branch) so deployments are tagged correctly. ## Getting a deploy key Deploy keys are project-scoped and deploy-only. Create one in two ways: - **Dashboard**: open your project, go to **Settings → Deploy keys**, and choose **Create key**. The `bmd_...` value is shown once -- copy it immediately. - **First push**: the first time you run `blodemd push` for a project that doesn't exist yet while logged in, the CLI auto-creates the project and prints a `bmd_...` key for CI. > [!WARNING] > Store deploy keys as CI secrets. Never commit them to your repository. ## Related pages - [Deploying with push](https://blode.md/docs/deployment/push) -- the `push` command and its options --- Content truncated to keep this response under crawler size limits. Use https://blode.md/docs/llms.txt for the full page index and fetch individual .md pages for uncapped content.