> ## 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 Edda. 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. Edda is the git path without
the editor or the marketplace: the same MDX files, a smaller `docs.json`, and
one command to publish.

> [!WARNING]
> Edda'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
>   `edda 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 edda-docs`
- A Edda account: run `edda 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 Edda 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. Edda `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, `edda new` writes a minimal `docs.json`
and `index.mdx` into a `docs/` folder.
  1. **Validate**

```bash
edda 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
edda 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
edda 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 Edda 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 Edda 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.** Edda 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 `edda 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 Edda'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

- **`edda 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.