diff --git a/installation.mdx b/installation.mdx index c6bc3d661..cdfb58a44 100644 --- a/installation.mdx +++ b/installation.mdx @@ -83,12 +83,22 @@ mint dev A local preview of your documentation is available at `http://localhost:3000`. +The local preview: +- Hot-reloads when you save changes to MDX files or `docs.json` +- Mirrors your production documentation's appearance and functionality +- Validates your content and displays warnings for issues +- Works offline once initially loaded + Alternatively, if you do not want to install the CLI globally, you can run a one-time script: ```bash npx mint dev ``` + +Using `npx` downloads and runs the CLI without installing it globally. This is useful for trying the CLI or running it in CI/CD environments, but `mint dev` is faster for regular development. + + ### Custom ports By default, the CLI uses port 3000. You can customize the port using the `--port` flag. To run the CLI on port 3333, for instance, use this command: @@ -103,7 +113,12 @@ If you attempt to run on a port that is already in use, the CLI uses the next av Port 3000 is already in use. Trying 3001 instead. ``` -## Skip OpenAPI processing +This is useful when: +- Port 3000 is already in use by another application +- You need to run multiple documentation sites simultaneously +- Your development environment requires specific ports + +### Skip OpenAPI processing If you have many OpenAPI files, skip OpenAPI file processing during local development to improve performance by using the `--disable-openapi` flag: @@ -111,6 +126,12 @@ If you have many OpenAPI files, skip OpenAPI file processing during local develo mint dev --disable-openapi ``` +This significantly speeds up the development server startup time when you have large or multiple OpenAPI specifications. Your API documentation pages will show placeholder content instead of generated content. + + +Use this flag only during content development. Always test with OpenAPI processing enabled before deploying to ensure your API documentation renders correctly. + + ### Preview as a specific group If you use partial authentication to restrict access to your documentation, you can preview as a specific authentication group by using the `--groups [groupname]` flag. @@ -121,6 +142,12 @@ For example, if you have a group named `admin`, you can preview as a member of t mint dev --groups admin ``` +This allows you to: +- Test group-specific content visibility +- Verify authentication rules work correctly +- Preview documentation as different user types +- Ensure restricted content displays properly for authorized groups + ## Create a new project To create a new documentation project, run the following command: @@ -137,9 +164,16 @@ This command clones the [starter kit](https://github.com/mintlify/starter) into The CLI tool prompts you for a project name and [theme](/customize/themes) to finish setting up your project. +The starter kit includes: +- Pre-configured `docs.json` with common settings +- Sample MDX pages demonstrating components and formatting +- Example navigation structure +- Basic styling and theme configuration +- Ready-to-use folder structure + You can run `mint new` with the following flags: -* `--theme`: Set the theme of the new project. +* `--theme`: Set the theme of the new project (options: `quill`, `linden`, `venus`, `petal`). * `--name`: Set the name of the new project. * `--force`: Overwrite the current directory if it already exists. @@ -148,6 +182,10 @@ For example, to create a new project in the `docs` directory with the name `my-p ```bash mint new docs --name my-project --theme linden ``` + + +After creating a new project, run `mint dev` in the project directory to preview your documentation and start customizing it. + ## Update the CLI If your local preview is out of sync with what you see on the web in the production version, update your local CLI: @@ -156,6 +194,12 @@ If your local preview is out of sync with what you see on the web in the product mint update ``` +You should update the CLI when: +- Your local preview doesn't match production +- New features or components aren't rendering locally +- You encounter unexpected errors or warnings +- Release notes mention CLI updates + If this `mint update` command is not available on your local version, re-install the CLI with the latest version: @@ -168,6 +212,10 @@ If this `mint update` command is not available on your local version, re-install ``` + +Check for CLI updates regularly to ensure you have the latest features and bug fixes. Run `mint --version` to see your current version. + + ## Additional commands ### Find broken links @@ -180,6 +228,11 @@ mint broken-links The command ignores files matching [.mintignore](/organize/mintignore) patterns. Links that point to ignored files are reported as broken. +This is useful for: +- Catching broken links before deploying to production +- Identifying outdated references after restructuring your documentation +- Ensuring all navigation items point to valid pages + ### Find accessibility issues Test the color contrast ratios and search for missing alt text on images and videos in your documentation with the following command: @@ -198,6 +251,12 @@ mint a11y --skip-contrast mint a11y --skip-alt-text ``` +The accessibility checker helps you: +- Meet WCAG 2.1 AA standards for color contrast +- Ensure all images and videos have descriptive alt text +- Improve documentation usability for users with visual impairments +- Identify accessibility issues before they reach production + ### Check OpenAPI spec Check your OpenAPI file for errors with the following command: @@ -208,6 +267,14 @@ mint openapi-check Pass a filename (for example, `./openapi.yaml`) or a URL (for example, `https://petstore3.swagger.io/api/v3/openapi.json`). +This command validates: +- OpenAPI specification syntax and structure +- Required fields and proper formatting +- Schema definitions and references +- Compatibility with Mintlify's API documentation features + +Use this before deploying to catch specification errors early and ensure your API documentation renders correctly. + ### Rename files Rename and update all references to files with the following command: @@ -216,6 +283,14 @@ Rename and update all references to files with the following command: mint rename ``` +This command automatically: +- Renames the specified file +- Updates all internal links pointing to the old filename +- Updates navigation references in `docs.json` +- Preserves your documentation's link integrity + +This is safer than manually renaming files, which can break internal links and navigation. + ### Migrate MDX endpoint pages Migrate MDX endpoint pages to autogenerated pages from your OpenAPI specification with the following command: @@ -226,6 +301,36 @@ mint migrate-mdx 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. +Benefits of migration: +- Automatically sync API documentation with your OpenAPI spec +- Reduce manual maintenance of endpoint documentation +- Ensure consistency between your API spec and documentation +- Keep custom content while leveraging auto-generation + +### Get CLI version + +Check your current CLI version with the following command: + +```bash +mint --version +``` + +Use this to verify you're running the latest version or when troubleshooting issues. + +### Get help + +View all available commands and options with the following command: + +```bash +mint --help +``` + +For help with a specific command, use: + +```bash +mint --help +``` + ## Formatting While developing locally, we recommend using extensions in your IDE to recognize and format MDX files.