Development

Preview and publish this documentation site with the Mintlify CLI

This page is for people editing this docs repo (Mintlify). For ImageMagick itself, use Getting started.

Prerequisites:

• Node.js 20.17 or newer (LTS recommended; required by current Mintlify CLI)
• A clone of this repository with docs.json at the project root

Follow these steps to install and run Mintlify locally.

1. Install the Mintlify CLI

   npm i -g mint
   
2. Preview locally

   Navigate to your docs directory where your docs.json file is located, and run the following command:

   mint dev
   

   A local preview is usually at http://localhost:3000. If that port is busy, the CLI prints the next free port (for example 3001); use the URL shown in the terminal.

Custom ports

By default, Mintlify tries port 3000. Set an explicit port with --port:

mint dev --port 3333

If you attempt to run Mintlify on a port that’s already in use, it will use the next available port:

Port 3000 is already in use. Trying 3001 instead.

Mintlify versions

Each CLI release pins a Mintlify framework version. If your local preview does not match production, update the CLI:

mint update

Validating links

The CLI can assist with validating links in your documentation. To identify any broken links, use the following command:

mint broken-links

Documentation Index / llms.txt callout (Mintlify)

If the live site shows a blockquote such as “Documentation Index” or “Fetch the complete documentation index at … /llms.txt” on every page, that UI is produced by Mintlify’s hosted shell, not by MDX in this repository. Toggle or report that behavior in the Mintlify dashboard for your deployment (AI / ingestion or support) if you want it hidden; there is often no repo-local switch for that banner.

This project still exposes the machine-readable index at /llms.txt (and /.well-known/llms.txt) and links it from the site footer under Tools. Root-level style.css hides the Mintlify “Documentation Index” blockquote everywhere via blockquote:has(a[href*="llms.txt"]) so the promo does not compete with article content; MDX blockquotes without an llms.txt link are unchanged. The heading ## Snippet verification (CI) {#snippet-verification-ci} in this file is the stable anchor for /development#snippet-verification-ci.

Site-wide blurbs for SEO and generated llms.txt use the optional description field in docs.json; keep it aligned with the homepage when you change positioning.

Snippet verification (CI)

ImageMagick examples in MDX are checked by a small shell harness so obvious regressions are caught in CI.

bash scripts/verify-snippets.sh

Requirements:

• Either ImageMagick 7 on your PATH (magick --version), or a working Docker daemon (the script runs dpokidov/imagemagick:latest).

GitHub Actions runs the same script on pushes and pull requests that touch **/*.mdx, docs.json, or scripts/**. For a full platform matrix (Linux, macOS, Windows) and sign-off, use the checklist in VERIFICATION.md in this repo (maintainer reference, not part of the Mintlify navigation).

Deployment

Connect the GitHub repo in the Mintlify dashboard and install the GitHub app so pushes to the default branch deploy the site. In GitHub Actions or your host, a successful deploy shows all checks passing on the pull request or workflow run.

If production does not match GitHub: In Mintlify, confirm the project is wired to https://github.com/Fimber/docs (or your fork) and the production branch is main. Compare the footer commit or your deploy log to the latest commit on main. Trigger a manual redeploy from the Mintlify dashboard if the integration missed a push, and hard-refresh the browser (or try an incognito window) to bypass a stale CDN cache.

Code formatting

We suggest using extensions on your IDE to recognize and format MDX. If you’re a VSCode user, consider the MDX VSCode extension for syntax highlighting, and Prettier for code formatting.

Troubleshooting

Error: Could not load the "sharp" module using the darwin-arm64 runtime

This may be due to an outdated Node version or a mismatched global install. Try the following:

1. Remove the CLI: npm remove -g mint
2. Upgrade to Node 20.17 or newer (see node -v).
3. Reinstall: npm i -g mint

Issue: Encountering an unknown error

Solution: Go to the root of your device and delete the ~/.mintlify folder. Then run mint dev again.

Curious about what changed in the latest CLI version? Check out the CLI changelog.