> ## Documentation Index
> Fetch the complete documentation index at: https://hackmamba-3f164318.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](/quickstart).

<Info>
  **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
</Info>

Follow these steps to install and run Mintlify locally.

<Steps>
  <Step title="Install the Mintlify CLI">
    ```bash theme={null}
    npm i -g mint
    ```
  </Step>

  <Step title="Preview locally">
    Navigate to your docs directory where your `docs.json` file is located, and run the following command:

    ```bash theme={null}
    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.
  </Step>
</Steps>

## Custom ports

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

```bash theme={null}
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:

```md theme={null}
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:

```bash theme={null}
mint update
```

## Validating links

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

```bash theme={null}
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](https://dashboard.mintlify.com) 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.

<h2 id="snippet-verification-ci">
  Snippet verification (CI)
</h2>

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

```bash theme={null}
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`](https://github.com/Fimber/docs/blob/main/VERIFICATION.md) in this repo (maintainer reference, not part of the Mintlify navigation).

## Deployment

Connect the GitHub repo in the [Mintlify dashboard](https://dashboard.mintlify.com) 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`](https://github.com/Fimber/docs/commits/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](https://marketplace.visualstudio.com/items?itemName=unifiedjs.vscode-mdx) for syntax highlighting, and [Prettier](https://marketplace.visualstudio.com/items?itemName=esbenp.prettier-vscode) for code formatting.

## Troubleshooting

<AccordionGroup>
  <Accordion title="Error: Could not load the &#x22;sharp&#x22; 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`
  </Accordion>

  <Accordion title="Issue: Encountering an unknown error">
    Solution: Go to the root of your device and delete the `~/.mintlify` folder. Then run `mint dev` again.
  </Accordion>
</AccordionGroup>

Curious about what changed in the latest CLI version? Check out the [CLI changelog](https://www.npmjs.com/package/mintlify?activeTab=versions).