@helpnest/mintlify

Migrate your Mintlify docs into HelpNest — the open-source customer help center.

Reads your mint.json navigation, converts MDX pages to Markdown, and creates the equivalent Collections and Articles in HelpNest. Supports filtering by section and a dry-run preview mode.

Installation

npm install -g @helpnest/mintlify
# or run directly
npx @helpnest/mintlify <command>

Prerequisites

A HelpNest API key — generate one from your HelpNest dashboard under Settings → API Keys.

Setup

cp .env.example .env
# Edit .env with your HelpNest credentials

Commands

preview

Preview what would be migrated without touching HelpNest:

npx @helpnest/mintlify preview --docs-dir ./my-docs

Output:

Mintlify project: "Acme Docs"

Collections to create:
  Getting Started — 4 article(s)
  Guides — 8 article(s)
  API Reference — 12 article(s)

Total: 24 articles across 3 collections

migrate

Migrate the full project:

npx @helpnest/mintlify migrate \
  --docs-dir ./my-docs \
  --helpnest-url https://help.yourcompany.com \
  --helpnest-key hn_live_xxx \
  --workspace your-workspace-slug

Flags:

| Flag | Description | |------|-------------| | --docs-dir <path> | Path to your Mintlify project root (where mint.json lives) | | --helpnest-url | Your HelpNest base URL | | --helpnest-key | HelpNest API key | | --workspace | HelpNest workspace slug | | --dry-run | Preview without creating anything | | --collections-only | Create collections only, skip articles | | --group <name> | Only migrate pages from a specific nav group (partial match) |

How it works

1. Reads mint.json — parses the navigation structure to discover all pages and group them into Collections.
2. Loads MDX files — reads each .mdx or .md file from disk.
3. Strips MDX syntax — removes JSX components, import/export statements, and converts Mintlify-specific components (<Callout>, <Note>, etc.) to Markdown blockquotes.
4. Creates Collections — one HelpNest Collection per top-level nav group.
5. Creates Articles — one HelpNest Article per page, linked to its Collection.

What gets migrated

| Mintlify | HelpNest | |----------|----------| | Top-level nav group | Collection | | .mdx / .md page | Article | | title frontmatter | Article title | | description frontmatter | Article excerpt | | Page content (MDX → Markdown) | Article body |

What doesn't migrate

• API reference pages with OpenAPI/Swagger specs (content is preserved as text but not rendered as an API reference)
• Custom MDX components beyond the built-in Mintlify ones
• Images (referenced by their original relative paths — update them manually after migration)
• tabs in mint.json (pages under tabs are still migrated, but the tab structure becomes flat collections)

Contributing

PRs welcome! See CONTRIBUTING.md.

License

MIT © HelpNest Contributors