npm package: @helpnest/mintlify
Description: Migrate Mintlify docs to HelpNest
Latest version: 0.1.1

# @helpnest/mintlify

Migrate your [Mintlify](https://mintlify.com) docs into [HelpNest](https://github.com/babble-open-source/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

```bash
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

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

## Commands

### `preview`

Preview what would be migrated without touching HelpNest:

```bash
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:

```bash
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](https://github.com/babble-open-source/helpnest/blob/main/CONTRIBUTING.md).

## License

MIT © HelpNest Contributors