# Migrating from the previous writedocs

Projects built with the previous writedocs have a `config.json` with `websiteName`, `navbar` and `sidebars`. In that project's folder, run:

```bash
writedocs convert --writedocs
```

It writes `writedocs.json` next to `config.json`, lists what couldn't be carried over as-is, and checks your pages - see [`writedocs convert`](/docs/cli/#writedocs-convert). Pass `--dry-run` first to review the result without writing anything.

Only `config.json` is converted. Your pages stay where they are, as they are.

## What it converts

| config.json | writedocs.json |
| --- | --- |
| `websiteName`, `description` | `name`, `description`. |
| `images.logo`, `images.darkLogo` | `styles.logo` - one image, or `{ light, dark }`. |
| `images.favicon`, `images.metadata` | `styles.favicon`, `seo.ogImage`. |
| `images.background`, `images.darkBackground` | `styles.background.images`. |
| `styles.mainColor`, `styles.darkModeMainColor` | `styles.colors.primary`, `styles.colors.dark.primary`. |
| `styles.navbarColor`, `styles.navbarDarkModeColor` | `styles.navbar.light`, `styles.navbar.dark`. |
| `styles.backgroundDarkModeColor` | `styles.background.colors.dark`. |
| `navbar` items pointing at a sidebar | Tabs. With only one, the sidebar is the whole navigation - no tab bar. |
| `navbar` items with a `link` | Tabs that link out. |
| `navbar` items with a `dropdown` | A tab with a dropdown in its sidebar, one entry per sidebar. |
| Navbar icons (Phosphor names, like `BookOpen`) | The matching Lucide icon (`book-open`), when there is one. |
| `sidebars` categories, groups (`groupName`, `page`, `subpages`) | Groups, with the group's own page. |
| Sidebar pages generated from `apiFiles` | An OpenAPI group per spec - see below. |
| `languages` (more than one) and `translations/` | A navigation per language, using a page's translation where there is one, and `translations.json` for tab and group names. |
| `homepage` (a page) | A redirect from `/` to that page. |
| `externalLinks` | Topbar links. |
| `integrations.gtag`, `integrations.posthog` | `integrations.ga4` (or `googleTagManager` for a `GTM-` id), `integrations.posthog`. |

Page ids work the same way the previous writedocs read them: `Guides/intro` is `docs/Guides/intro.mdx`, and a page whose file name starts with `_` stays out of the navigation. In `writedocs.json` a page is its path from the project folder, so it becomes `docs/Guides/intro`.

## Page addresses

A page with a `slug` in its frontmatter keeps its address. A page without one moves: writedocs builds its address from the file's path, folder included - `docs/guides/setup.mdx` is served at `/docs/guides/setup/`, where the previous writedocs served `/guides/setup`.

`convert` adds a redirect from each old address to the new one, so links to the old site keep working. An old address with spaces or other special characters can't be matched by a redirect - `convert` says how many there are. To keep those, add a `slug` to the page.

## API reference

The previous writedocs generated a page per operation from each spec in `apiFiles`, and the sidebars listed those pages. writedocs does the same from an [OpenAPI group](/docs/openapi/overview/): `convert` finds the sidebar categories whose pages came from a spec and replaces them with an OpenAPI group for that spec - a page for every operation, grouped by tag. Hand-written pages in those categories, like a tag's introduction, stay above the generated ones.

- A spec that's a URL isn't downloaded. Save it in the project (`openAPI/` is fine) and run `convert --force` again.
- Generated pages get new addresses, and no redirects are added for them.

## What isn't converted

`convert` lists each of these when your `config.json` has it:

- **An HTML homepage** (`homepage.html`). `/` opens the first page instead. For a landing page, add `index.mdx` with `mode: custom` and rebuild the homepage there.
- **The changelog** (`changelog: true` and its folder). Rewrite it as a page with an `<Update>` entry per release.
- **`colorMode`** - writedocs follows the reader's system theme and always shows the light/dark toggle.
- **`styles.logoSize`, `styles.pagination`, `apiOptions`, `codeLanguages`, `translatedApiFiles`, `footer.copyright`, `protected`.**
- **`integrations.askAi`**, which connected a support tool. writedocs' Ask AI is [DocsBot](/docs/configuration/integrations/).
- **`custom.css`** - writedocs loads it on every page too, but rules for Docusaurus' class names (`.navbar`, `.menu`, ...) do nothing now.

## Your pages

Pages from the previous writedocs often use its own components and Docusaurus features. Run [`writedocs validate`](/docs/cli/#writedocs-validate) after converting: it lists every page the build would fail on - for example, an import from `@site/src/components` - and every component writedocs doesn't have, with file and line.