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:
writedocs convert --writedocsIt writes writedocs.json next to config.json, lists what couldn’t be carried over as-is, and checks your pages - see 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: 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 runconvert --forceagain. - 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, addindex.mdxwithmode: customand rebuild the homepage there. - The changelog (
changelog: trueand 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.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 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.