> ## Documentation Index
> [HTML page](https://blode.md/docs/guides/migrate-from-mintlify)
> [Documentation index](https://blode.md/docs/llms.txt)
> Use the index to discover all available pages before exploring further.

# Migrate from Mintlify

Move a Mintlify docs repo to Blode.md. Copy the MDX, rewrite docs.json to the smaller schema, validate, preview, push, and keep your domain.

Mintlify's git workflow is MDX in the repo, a `docs.json` beside it, a web
editor that commits back, and a marketplace. Blode.md is the git path without
the editor or the marketplace: the same MDX files, a smaller `docs.json`, and
one command to publish.

> [!WARNING]
> Blode.md's `docs.json` is deliberately smaller than Mintlify's. Top-level keys
>   such as `name`, `navigation`, `navbar`, and `logo` exist in both, but `theme`,
>   `colors`, `fonts`, `icons`, `background`, and `styling` are not supported, and
>   `blodemd validate` reports every key it does not recognise as an error. Expect
>   to edit the file, not just copy it.

## Prerequisites

- [Node.js](https://nodejs.org) 24.x
- The CLI: `npm i -g blodemd`
- A Blode.md account: run `blodemd login` once (it opens GitHub OAuth)

## Steps

  1. **Copy the MDX files**

Your pages carry over as they are. Move the `.mdx` files, the images they
    reference, and your logo and favicon assets into one docs directory, with
    `docs.json` at its root. Keep the same relative layout so page paths and
    image links do not change.

    Frontmatter needs a `title`; `description` is optional but used for meta
    tags and search results. See [Frontmatter](/content/frontmatter) for the
    full field list.

    The CLI resolves the docs directory in this order: the current directory,
    `./docs`, then `./apps/docs`. If your Mintlify content lived somewhere
    else, pass the path explicitly to every command below.
  1. **Write docs.json**

Start from the two required keys and add only what Blode.md supports:

    ```json title="docs.json"
    {
      "$schema": "https://blode.md/docs.json",
      "name": "Acme Docs",
      "slug": "acme-docs",
      "logo": {
        "light": "/logo/light.svg",
        "dark": "/logo/dark.svg"
      },
      "favicon": "/favicon.svg",
      "navbar": {
        "links": [{ "label": "GitHub", "href": "https://github.com/acme/docs" }]
      },
      "navigation": {
        "groups": [
          { "group": "Getting started", "pages": ["index", "quickstart"] },
          { "group": "Guides", "pages": ["guides/auth", "guides/deploy"] }
        ]
      }
    }
    ```

    Map your navigation groups across one at a time. Blode.md `navigation`
    accepts `pages`, `groups`, `tabs`, `anchors`, `dropdowns`, `versions`,
    `languages`, and `products`, and groups can nest. See
    [Navigation](/configuration/navigation) for each shape.

    `slug` sets your `{slug}.blode.md` subdomain. The remaining supported
    top-level keys are `description`, `appearance`, `api`, `contextual`,
    `search`, `seo`, and `metadata`; everything else is documented in the
    [docs.json reference](/configuration/docs-json). If you want a scaffold to
    edit instead of a blank file, `blodemd new` writes a minimal `docs.json`
    and `index.mdx` into a `docs/` folder.
  1. **Validate**

```bash
    blodemd validate
    ```

    Validation is strict and needs no login. Every unrecognised key is listed
    as an error, so paste the output back into your editor and delete or
    rename keys until it prints `docs.json is valid.` Validation checks the
    config file only; a `pages` entry with no matching file shows up as a 404
    in the preview step, not here.
  1. **Preview**

```bash
    blodemd dev
    ```

    This runs the production renderer locally on port 3030 and opens a
    browser. Click through the sidebar and check that callouts, tabs, and code
    groups render. `docs.json` edits trigger a full reload, so you can keep
    tuning navigation while the preview stays open.
  1. **Push**

```bash
    blodemd push
    ```

    The CLI validates again, uploads the directory, and promotes the deploy.
    If the slug has no project yet, it offers to create one. Your docs are
    live at `your-slug.blode.md`. For automatic deploys on every commit,
    install the Blode.md GitHub App from the project's **Git** tab in the
    dashboard, or see [Continuous deployment](/deployment/ci).
  1. **Keep your domain**

Once the push succeeds, move your hostname over and then cut DNS.

    - **Docs on their own hostname** (for example `docs.example.com`): add the
      domain in the dashboard and point a CNAME at `cname.vercel-dns.com`. See
      [Custom domains](/features/custom-domains).
    - **Docs under a path** (for example `example.com/docs`): keep DNS as is
      and rewrite `/docs` and `/_docs` to your Blode.md site from the server
      you already run. Paste-ready configs:
      [Vercel](/guides/proxy-vercel), [Cloudflare](/guides/proxy-cloudflare),
      and [Nginx](/guides/proxy-nginx). Set `seo.siteUrl` to the public URL so
      canonicals, the sitemap, and `llms.txt` point at your domain.

## What carries over

- MDX pages, images, logo, and favicon files.
- Frontmatter `title` and `description`.
- `navigation` groups, tabs, and nested pages, once mapped to the shapes above.
- `navbar.links` and the `logo` and `favicon` light/dark pattern.
- OpenAPI references, through the `api` object. See [OpenAPI](/features/openapi).
- Callout shorthands `<Note>`, `<Warning>`, `<Info>`, `<Tip>`, `<Check>`, and
  `<Danger>`, plus `<Callout type="...">`.

## What does not carry over

- **The web editor.** Blode.md has no browser editor that commits back. Writing
  stays in your editor and in git; that is the product, not a gap to fill.
- **Marketplace integrations.** There is no integrations catalog. Analytics is
  a single PostHog key set in the dashboard (or `blodemd analytics set`); see
  [PostHog analytics](/features/analytics). It is not a `docs.json` key.
- **Theme, color, and font config.** `theme`, `colors`, `fonts`, `icons`,
  `background`, and `styling` are rejected. Branding is `logo`, `favicon`, and
  `appearance` only; see [Appearance and branding](/configuration/theming).
- **Components outside Blode.md's set.** The supported components are
  Accordion, Callout, Card, CodeGroup, Columns, Expandable, Frame, Installer,
  Steps, Tabs, Tree, and TypeTable. Any other JSX tag in your MDX will fail
  to render, so grep for component names and replace or remove the ones that
  are not on that list. Browse the [Components](/components/callout) tab for
  each component's props.

## Troubleshooting

- **`blodemd validate` lists keys you never wrote**: nested Mintlify-only
  options are reported with their full dotted path. Delete the parent object
  if it has no supported equivalent.
- **A page 404s after push**: the `pages` entry must match the file path
  without the `.mdx` extension, relative to `docs.json`.
- **The site renders unstyled behind a proxy**: the `/_docs/*` rewrite is
  missing. Each proxy guide above calls it out.