01 / 10
Speaker notes
writechoice
WriteChoice · Technical walkthrough
Documentation Migration to Mintlify

Source to Mintlify, step by step, with the commands used at each step.

Repository Live URL wcc Mintlify
Tooling: @writechoice/mint-cli (wcc) · cli.writechoice.io
The process
  1. 1IntakeDays
  2. 2ScopeDays
  3. 3Convert~1–1.5 days
  4. 4Structure and configSame week
  5. 5Bug bashSame week
  6. 6ReviewRest of week+
  7. 7Content changesAs needed
  8. 8Handoff—
Overview

Eight steps

Steps 3–5 · under a week
1
Intake
Source access, assets, decisions agreed
Days
2
Scope
Page count, structure map, flag list
Days
3
Convert
MDX pages and navigation
~1–1.5 days
4
Structure and config
docs.json, theme, API reference, snippets, redirects
Same week
5
Bug bash
Parse, links, pages and images clean
Same week
6
Review
Every page checked against its source
Rest of week+
7
Content changes
Changed pages re-converted, checked and reviewed
As needed
8
Handoff
Repository transferred, preview live
—
Step 1

Intake

Inputs
  • Source: repository or zip (preferred), or live URL
  • Existing redirect rules
  • API specs: OpenAPI / AsyncAPI
  • Brand assets and design constraints
  • Shared Slack channel and a point of contact
Decisions before starting
  • Keep the information architecture, or a new one provided upfront
  • Keep the URL pattern, or new URLs with redirects
  • Content freeze, or changes tracked and sent as diffs
  • Who reviews, and where feedback is tracked
Setup
$ wcc config
Generates config.json with source (original site), target (local mint dev) and preview (deployed preview).
Custom repository: the converter is a one-off script; config.json still drives the checks.
Step 2

Scope

Pages
Inventory from sitemaps, navigation and links.
Page count
Structure
Tabs, groups and hierarchy of the source navigation.
Navigation map
Components
Each source component matched to a native Mintlify component, or flagged.
Native / to be built
Flag list
Items with no one-to-one equivalent. Each goes to the customer with a recommendation: closest alternative, custom rebuild, or drop.
Customer decision
Step 3

Convert

InputTooling
Docusaurus repo
wcc docusaurus convertwcc docusaurus navwcc docusaurus slugify
ReadMe
wcc readme convertwcc readme navwcc readme openapi
Any live site
wcc scrape(wcc session first if the site requires login)
Custom repository
One-off converter written for that source, outside the CLI

Project-specific behavior lives in config.json: content selectors, elements to remove, component mappings, and pre/post hook scripts. A custom repository gets its own converter; the checks in step 5 apply the same way.

Step 4

Structure and config

docs.json
Navigation (tabs, groups, ordering) and platform configuration.
Theme
Colors, logo, typography, footer.
API reference
OpenAPI / AsyncAPI specs wired to reference pages.
Snippets
Custom components rebuilt where there is no native equivalent.
Redirects
Existing rules, path changes, and wcc find redirects for redirects discovered on the source.
Metadata
wcc metadata copies meta tags from source pages into frontmatter.
Step 5

Bug bash

+ custom scripts
Beyond these commands

Bugs they don't solve get case-specific fix scripts. Every docs set ends up needing a few.

CheckWhat it does
wcc check parseEvery file compiles as MDX
wcc check linksLinks and anchors resolve, compared on the source and on mint dev
wcc check pagesEvery page in the navigation renders
wcc check imagesEvery image on every page loads
wcc check katexMath renders without errors
Loop

Repeat until every check passes.

FixWhat it does
wcc fix parseVoid tags and stray angle brackets flagged by check parse
wcc fix void-tagsSelf-close HTML void elements
wcc fix dollar-signsEscape prices so they aren't read as math
wcc fix importsAdd missing imports for custom components
wcc fix linksRewrite broken anchors from the check links report
wcc fix redirectsPoint links at final URLs, not redirect sources
wcc fix imagesWrap standalone images in Frame; --download fetches missing ones
wcc fix inlineimagesImages inside text become InlineImage
wcc fix tabsCode-only tabs become CodeGroup
wcc fix accordionsSibling accordions become AccordionGroup
wcc fix codeblocksSet expandable, lines and wrap
wcc fix h1Remove H1s that repeat the title
Step 6

Review

Every page, against its source
Source
Mintlify
  • Line breaks and paragraph separation
  • Inline and block formatting
  • Heading levels and titles
  • Indentation in nested lists and code
  • Spacing
How
  1. Each page's permalink opens the source side by side
  2. Findings that need a decision go to the flag list in Slack
  3. Customer review in batches, or all at once at the end
  4. Checks re-run after review edits
Step 7

Content changes

1
Two options:
content freeze for the duration
or
the customer sends a diff, or a new copy of the repository
2
We re-run conversion on the changed pages only
3
Checks and review on those pages
Avoid

No full re-scrape or re-pull: it would discard the bug bash and review already done.

Step 8

Handoff

customer-docstransferred
docs.jsonnavigation, theme, redirects, API
*.mdxpages
snippets/rebuilt components
openapi/API specs
images/assets
Delivered
  • Repository transferred to the customer
  • Preview site matching what was reviewed
Customer provides
  • Source and access
  • Answers on flagged items
  • Redirects, API specs, brand assets
  • Notice of content changes