Migrating from ReadMe

A ReadMe site moves to Writedocs with one command. It reads the published site - no ReadMe account or API key needed - and writes a complete project: every page, the API reference, the recipes, the landing page, the images ReadMe hosts, and writedocs.json.

writedocs convert --readme docs.example.com my-docs

Give it the site’s address (its custom domain, or your-project.readme.io) and a folder to write into - an empty one, or one that doesn’t exist yet. It lists what couldn’t be carried over as-is, and then checks every page the way writedocs validate does:

✓ Converted https://docs.example.com into my-docs: 144 pages, 75 of them API operations, 5 recipes, 87 images

ℹ 1 thing couldn't be carried over as-is:

  docs/payouts, docs/transfers
    A recipe card (TutorialTile) links to a recipe that isn't on the site any more - the card is left out.

✓ Checked 144 pages: 0 errors, 0 warnings

Then preview it with writedocs dev and check its links with writedocs broken-links.

What you get

• writedocs.json
• index.mdx
• docs
  • getting-started.mdx
• reference
  • create-user.mdx
• recipes
  • first-payment.mdx
• openapi
  • my-api.json
• images
  • 0392eac-diagram.png
• readme-html.css

Every page keeps its address: /docs/getting-started, /reference/create-user and /recipes/first-payment are the same pages on the new site, so links from elsewhere and search results keep working.

What it converts

Page content

API reference

The API definition is downloaded whole and written to openapi/, one file per API. Each endpoint page names its operation in the definition:

---
title: Create user
openapi: "openapi/my-api.json POST /users"
---

So the page shows the operation - its parameters, responses and an API playground - with its old title, address and place in the sidebar. See OpenAPI. When the whole definition can’t be downloaded, it’s rebuilt from the endpoint pages, and the list says so.

Recipes

A recipe becomes a page with its code pinned in the right-hand column - see RequestExample and ResponseExample - and its steps as Steps. Each step shows the lines of the code it’s about, in every language.

HTML

Hand-written HTML - an <HTMLBlock>, or a landing page built in HTML - is converted to the same HTML, styles and all, written so that a page can hold it: class becomes className, for example. Each block sits in a <div className="readme-html">.

That HTML sets its own colors, usually for a light page only. readme-html.css lets the headings inside it inherit those colors, so they stay readable in dark mode too. The blocks’ own backgrounds don’t change with the theme: to make one follow it, replace it with components, or style it with [data-theme="dark"] - see Custom CSS and scripts.

After converting

• Set your colors for dark mode. A ReadMe site is often light only. When its brand color is too dark to read on a dark page, styles.colors.dark.primary is set to a lighter version of it, and the list says so - change it if your brand has its own.
• Fix the broken links. writedocs broken-links lists every link that doesn’t lead anywhere, with a suggestion. Some were broken on ReadMe too: a page that was renamed, a heading that changed.
• Look at the pages with HTML. Check them in light and dark mode.

Not converted

• Other versions. Only the version the site opens on is converted.
• The changelog, custom pages and discussions. Add changelog entries as pages - the Update component suits them.
• Custom CSS and JavaScript from the project’s appearance settings: ReadMe’s class names have no equivalent. The list mentions them.
• ReadMe’s older [block:...] syntax. A page still written in it is listed, and each block is shown as a code block to rewrite.
• Sites that need a login. The site has to be public.
• Redirects with a pattern (/old/*). Writedocs redirects match one exact path; these are listed.
• SEO titles set apart from the page title. The page’s title is used, and the list names each page.