diff --git a/guides/migrating-from-mdx.mdx b/guides/migrating-from-mdx.mdx index 8b2779452..6945da7d7 100644 --- a/guides/migrating-from-mdx.mdx +++ b/guides/migrating-from-mdx.mdx @@ -2,53 +2,14 @@ title: "Migrating MDX API pages to OpenAPI navigation" sidebarTitle: "Migrate from MDX to OAS" description: "Migrate your manually written MDX API pages to automated OpenAPI-generated documentation with flexible navigation and endpoint grouping." -keywords: ["API migration", "mint migrate-mdx", "OpenAPI migration", "x-mint extension"] +keywords: ["API migration", "OpenAPI migration", "x-mint extension"] --- If you are currently using individual MDX pages for your API endpoints, you can migrate to autogenerating pages from your OpenAPI specification while retaining the customizability of individual pages. This can help you reduce the number of files you need to maintain and improve the consistency of your API documentation. You can define metadata and content for each endpoint in your OpenAPI specification and organize endpoints where you want them in your navigation. -## CLI migration - -The `mint migrate-mdx` command is the recommended way to migrate from MDX endpoint pages to autogenerated pages. - -This command: -- Parses your `docs.json` navigation structure. -- Identifies MDX pages that generate OpenAPI endpoint pages. -- Extracts content from MDX files and moves it to the `x-mint` extension in your OpenAPI specification. -- Updates your `docs.json` to reference the OpenAPI endpoints directly instead of MDX files. -- Deletes the original MDX endpoint files. - - -If you already have `x-mint` defined for an endpoint and also have an MDX page with content for that endpoint, the MDX content overwrites existing `x-mint` settings. - -If you have multiple MDX pages for the same endpoint with different content, the script uses the content from the page that appears last in your `docs.json`. - -The migration tool does not support previewing changes before applying them. - - - - - Ensure your OpenAPI specification is valid and includes all endpoints you want to document. - - Any MDX pages you want to migrate must have the `openapi:` frontmatter referencing an endpoint. - - - Validate your OpenAPI file using the [Swagger Editor](https://editor.swagger.io/) or [Mint CLI](https://www.npmjs.com/package/mint). - - - - If needed, install or update the [Mint CLI](/installation). - - - ```bash - mint migrate-mdx - ``` - - - -## Manual migration steps +## Migration steps diff --git a/installation.mdx b/installation.mdx index 68eca503e..9c6451e60 100644 --- a/installation.mdx +++ b/installation.mdx @@ -17,7 +17,7 @@ keywords: ["CLI", "npm", "local development", "Node.js", "pnpm", "mint dev", "br Use the [CLI](https://www.npmjs.com/package/mint) to preview your documentation locally as you write and edit. View changes in real-time before deploying, test your documentation site's appearance and features, and catch issues like broken links or accessibility problems. -The CLI also has utilities for maintaining your documentation, including commands to rename files, validate OpenAPI specifications, and migrate content between formats. +The CLI also has utilities for maintaining your documentation, including commands to validate OpenAPI specifications, view analytics, and authenticate your account. ## Prerequisites @@ -258,98 +258,212 @@ mint workflow The CLI prompts you for a name, trigger type, and other settings, then creates a `.md` file in `.mintlify/workflows/`. -### Rename files +### Export for offline viewing -Rename and update all references to files with the following command: +Export your entire documentation site as a self-contained zip archive for offline viewing and distribution: ```bash -mint rename +mint export ``` -Use `--force` to rename files and skip errors: +Use `--output` to set a custom filename, `--groups` to include pages restricted by [user groups](/deploy/authentication-setup#control-access-with-groups), and `--disable-openapi` to skip OpenAPI processing. ```bash -mint rename --force +mint export --output customer-docs.zip --groups enterprise ``` -### Migrate MDX endpoint pages +See [Offline export](/deploy/export) for details on all options and distributing the exported archive. + +### Upgrade configuration -Migrate MDX endpoint pages to autogenerated pages from your OpenAPI specification with the following command: +Convert a `mint.json` configuration file to the current `docs.json` format: ```bash -mint migrate-mdx +mint upgrade ``` -This command converts individual MDX endpoint pages to autogenerated pages defined in your `docs.json`, moves MDX content to the `x-mint` extension in your OpenAPI specification, and updates your navigation. See [Migrating from MDX](/guides/migrating-from-mdx) for detailed information. +See [Global settings](/organize/settings) for more information about `docs.json`. -### Export for offline viewing +### Check version -Export your entire documentation site as a self-contained zip archive for offline viewing and distribution: +Display the current CLI and client version: ```bash -mint export +mint version ``` -Use `--output` to set a custom filename, `--groups` to include pages restricted by [user groups](/deploy/authentication-setup#control-access-with-groups), and `--disable-openapi` to skip OpenAPI processing. +## Authentication + +Sign in to your Mintlify account from the CLI to access authenticated features like analytics. + +### Log in + +Authenticate your Mintlify account: ```bash -mint export --output customer-docs.zip --groups enterprise +mint login ``` -See [Offline export](/deploy/export) for details on all options and distributing the exported archive. +The command opens your browser for authentication. After you authorize, the CLI stores your credentials locally using your system keychain. -### Import content +### Check authentication status -Scrape content from an external documentation site or OpenAPI specification using the `mint scrape` commands. This is useful when you migrate your documentation from another platform to Mintlify. +View your current authentication status, including your email and organization: -**Import an entire site:** +```bash +mint status +``` + +### Log out + +Remove your stored credentials: ```bash -mint scrape +mint logout ``` -Use the `--filter` (or `-f`) flag to limit scraping to URLs matching a specific path prefix: +## Analytics + + + You must be logged in with `mint login` before using analytics commands. + + +View analytics for your documentation site directly from the terminal with the `mint analytics` command. This is useful for monitoring traffic, reviewing user feedback, and understanding how visitors interact with your docs. + +### View key metrics + +Display a summary of views, visitors, searches, feedback, and assistant usage: ```bash -mint scrape --filter= +mint analytics stats ``` -**Import a single page:** +Use `--from` and `--to` to specify a date range (defaults to the last 7 days): ```bash -mint scrape page +mint analytics stats --from 2026-01-01 --to 2026-01-31 ``` -**Generate pages from an OpenAPI spec:** +Filter to a specific page or traffic source: ```bash -mint scrape openapi +# Filter to a specific page +mint analytics stats --page /quickstart + +# Show only human traffic +mint analytics stats --humans + +# Show only agent traffic +mint analytics stats --agents ``` +### View search analytics + +See what users are searching for in your documentation: + +```bash +mint analytics search +``` + +Filter by search query or top clicked page: + +```bash +mint analytics search --query "authentication" +mint analytics search --page /api-reference +``` + +### View feedback + +Display feedback submitted by users on your documentation pages: + +```bash +mint analytics feedback +``` + +View page-level feedback aggregation: + +```bash +mint analytics feedback --type page +``` + +Filter to code snippet feedback: + +```bash +mint analytics feedback --type code +``` + +### View assistant conversations + +List conversations from the AI assistant: + +```bash +mint analytics conversation list +``` + +View a specific conversation by ID: + +```bash +mint analytics conversation view +``` + +### View conversation buckets + +List grouped conversation categories: + +```bash +mint analytics conversation buckets list +``` + +View conversations within a specific bucket: + +```bash +mint analytics conversation buckets view +``` + +### Shared flags + +All analytics commands support the following flags: + | Flag | Description | | --- | --- | -| `--outDir` | Directory to write generated files. Defaults to `./docs`. | -| `--overwrite` | Overwrite existing files. | -| `--no-writeFiles` | Preview output without writing files. | +| `--subdomain` | Documentation subdomain. Defaults to the value set with `mint config set subdomain`. | +| `--from` | Start date in `YYYY-MM-DD` format. Defaults to 7 days ago or the value set with `mint config set dateFrom`. | +| `--to` | End date in `YYYY-MM-DD` format. Defaults to today or the value set with `mint config set dateTo`. | +| `--format` | Output format: `table` (pretty), `plain` (pipeable), `json` (raw), or `graph` (bar charts). Defaults to `plain`. | +| `--agent` | Agent-friendly output, equivalent to `--format json`. Automatically detected when running inside AI coding agents. | -### Upgrade configuration +## Configuration -Convert a `mint.json` configuration file to the current `docs.json` format: +Manage persistent CLI settings with the `mint config` command. These settings provide defaults for other commands like `mint analytics`. + +### Set a value ```bash -mint upgrade +mint config set ``` -See [Global settings](/organize/settings) for more information about `docs.json`. +### Get a value -### Check version +```bash +mint config get +``` -Display the current CLI and client version: +### Clear a value ```bash -mint version +mint config clear ``` +### Available keys + +| Key | Description | +| --- | --- | +| `subdomain` | Default documentation subdomain for analytics commands. | +| `dateFrom` | Default start date for analytics date ranges. | +| `dateTo` | Default end date for analytics date ranges. | + +Configuration is stored in `~/.config/mintlify/config.json`. + ## Formatting While developing locally, we recommend using extensions in your IDE to recognize and format MDX files. diff --git a/migration.mdx b/migration.mdx index de2d45b10..74649c14f 100644 --- a/migration.mdx +++ b/migration.mdx @@ -170,18 +170,12 @@ To migrate your content to Mintlify, you need: 1. If your content is already in Markdown format, copy the content to your Mintlify project. Otherwise, convert your content to MDX format. 2. Create your `docs.json` referencing the paths to your Markdown pages. -3. If you have OpenAPI specifications, add them to your `docs.json` and configure the API playground. You can also generate MDX pages from your spec using the `mint scrape openapi` command: +3. If you have OpenAPI specifications, add them to your `docs.json` and configure the API playground. You can also generate MDX pages from your spec using the `@mintlify/scraping` package: ```bash -mint scrape openapi +npx @mintlify/scraping@latest openapi-file ``` -| Flag | Description | -| --- | --- | -| `--outDir` | Directory to write generated files. Defaults to `./docs`. | -| `--overwrite` | Overwrite existing files. | -| `--no-writeFiles` | Preview output without writing files. | - If you migrate your content as `.md` files, convert them to `.mdx` to support interactive features like React components.