WriteChoice Mint CLI

CLI tool for Mintlify documentation validation and utilities.

Installation

npm install -g @writechoice/mint-cli
npx playwright install chromium

Both writechoice and wcc are available as the command name.

Quick Start

# Generate a config.json with all available options
writechoice config

# Edit config.json — at minimum set your source URL
# "source": "https://docs.example.com"

# Then run any command without arguments
writechoice check parse
writechoice check links
writechoice scrape

Commands

Check

| Command | Description | |---|---| | writechoice check parse | Validate MDX files for parsing errors | | writechoice check links [baseUrl] | Validate internal links and anchors | | writechoice check pages [baseUrl] | Validate every page in docs.json loads successfully | | writechoice check images [baseUrl] | Validate that all images on docs pages load | | writechoice check katex [baseUrl] | Check for KaTeX render errors across all pages |

Fix

| Command | Description | |---|---| | writechoice fix parse | Fix void tags and stray angle brackets | | writechoice fix links | Fix broken anchor links from a validation report | | writechoice fix redirects | Replace stale redirect sources with destinations in MDX files | | writechoice fix codeblocks | Add/remove expandable, lines, wrap on code blocks | | writechoice fix images | Wrap standalone images in <Frame> | | writechoice fix inlineimages | Convert inline images to <InlineImage> | | writechoice fix h1 | Remove H1 headings that duplicate the frontmatter title | | writechoice fix imports | Add missing component imports from the snippets folder |

Scrape

| Command | Description | |---|---| | writechoice scrape [urls...] | Scrape documentation pages and convert them to MDX | | writechoice session <url> | Open a browser to log in and save a session for authenticated scraping |

Nav

| Command | Description | |---|---| | writechoice nav folders | Restructure MDX files to match the docs.json navigation hierarchy | | writechoice nav root | Promote matching first pages as root entries in nested nav groups |

Docusaurus

| Command | Description | |---|---| | writechoice docusaurus convert <folder> | Convert a Docusaurus docs folder to Mintlify MDX | | writechoice docusaurus slugify <folder> | Rename converted MDX files to match their frontmatter slug | | writechoice docusaurus nav <file> | Convert a sidebars.js to Mintlify navigation JSON |

Other

| Command | Description | |---|---| | writechoice metadata [baseUrl] | Fetch meta tags from live pages and write them into frontmatter | | writechoice config | Generate a config.json template | | writechoice update | Update to the latest version |

All commands support --file <path>, --dir <path>, --dry-run, and --quiet where applicable.

Scrape

Converts live documentation pages to MDX files.

writechoice scrape https://docs.example.com/page
writechoice scrape --urls-file urls.json --output output/
writechoice scrape --playwright  # for JS-rendered pages

Table conversion

By default, HTML tables are converted to GFM markdown tables automatically. The original HTML is kept as a JSX comment directly above the markdown table so you can review or restore it:

{/*
<table>...</table>
*/}

| Column A | Column B |
| --- | --- |
| value | value |

Tables that contain lists, code blocks, divs, or nested tables are too complex to convert cleanly and are kept as raw HTML.

To preserve all tables as raw HTML instead, add "table" to html_preserve_elements in config.json:

"html_preserve_elements": ["table", "iframe"]

Authenticated scraping

# Save a session from your browser login
writechoice session https://docs.example.com/login

# Then reference it in config.json
"playwright_config": { "storage_state": "session.json" }

API mode

For documentation platforms that expose a JSON API:

"api": {
  "content": "article.body",
  "filepath": "article.html_url",
  "title": "article.title"
}

Configuration

Create a config.json in your project root to set defaults and avoid repeating arguments:

{
  "source": "https://docs.example.com",
  "target": "http://localhost:3000"
}

Run writechoice config to generate a full template with all options and inline comments.

Documentation

Full command documentation is in docs/commands/.

Troubleshooting

Playwright not installed:

npx playwright install chromium

Too many concurrent requests:

writechoice check links -c 10

Permission error on install:

sudo npm install -g @writechoice/mint-cli
# or use nvm: https://github.com/nvm-sh/nvm

License

MIT — GitHub · npm · Issues