docs-mantis

The Mintlify documentation source for privacykey/mantis, a self-hostable canary key service.

Warning

Project status. The badge above is generated from the privacykey status list, which says what I promise for this project and every other one.

---

Read the docs

The published site is not live yet — no docs domain resolves for this project at the moment, so there is nothing to link here. Until it is published, read the pages in this repository directly: they are ordinary Markdown with Mintlify frontmatter, and GitHub renders them.

Start at index.mdx, or jump to Getting started.

Run it locally

npm run dev

That runs npx mint@latest dev, which serves the site at http://localhost:3000. There is no lockfile and nothing to install first — the Mintlify CLI is fetched on demand.

Before opening a pull request, run the same two checks CI runs:

npm run validate     # mint validate — the Mintlify build
npm run check-links  # mint broken-links
npm run check        # scripts/check-docs.mjs — nav, anchors, frontmatter, stray JSX

If you have just installed, just run and just lint are shorthands for the same commands.

File layout

Pages live at the repository root, except the deployment guides which live under deployment/. docs.json holds the theme, colours and navigation; style.css carries the small CSS override for the nav logo. Both README.md files are listed in .mintignore — they are for GitHub readers, not part of the site.

The navigation groups in docs.json, and the files behind them:

Start — index.mdx (site landing page), getting-started.md (CLI install to first key, in five steps), trying-locally.md (Docker evaluation, local-dev setup for contributors, benchmarks), use-cases.md (defensive, detective, operational, and adversarial-research patterns).

Deployment — deployment/index.mdx is the group root and the chooser between local, tunnelled and PaaS options. Then docker-local.md (option A), tailscale.md (B), cloudflare.md (C), railway.md (E1), fly.md (E2), render.md (E3), edge-limits.md (rate limiting, DDoS, WAF), backups.md (Postgres backup strategies), and edge-deployment.md (the stateless mantis-edge Cloudflare Worker variant).

Reference — api.md (endpoints, response kinds, webhook payload shape), configuration.md (required and optional environment variables), cli.md (every command and flag), cli-backup.md, updating.md (update commands per component), changelog.mdx.

Features — file-keys.md (Office/PDF/SVG/HTML/Markdown/email/calendar/contact artifacts, honey-directory ZIP, NFC label PDF, Apple Wallet .pkpass), honey-directory.md (the nine-file .zip bundle for shared drives), host-events.md (shell / login / boot / wake / network installers, web embeds, NFC, smart home, and the X-Mantis-* header reference), uptime-kuma.md (fan-out via Kuma's notification channels), reliability.md (hit dedup, retry queue, UA and bot parsing).

Operating — single-user.md (admin / non-admin behaviour), operational-notes.md (key hashing, disabled-key responses, worker model), dev-inbox.md (built-in webhook capture for local dev).

Recipes — self-hosted-apps.md, per-app recipes for Immich, Paperless, Joplin, Vaultwarden, dashboards and code hosts.

Architecture — architecture.md, a directory map of the product source tree.

Adding a page

1. Create the file, either .md or .mdx, at the root or under deployment/.
2. Give it frontmatter. title and description are required; icon and sidebarTitle are the only other keys npm run check accepts without warning.
3. Register it in docs.json under a navigation group, as a path from the repository root with no extension — host-events, deployment/backups. A page that is not registered will not appear in the sidebar, and npm run check warns about unregistered .mdx files.
4. Link between pages with root-relative, extensionless paths (/getting-started, /deployment/fly). Relative ./file.md links belong only in the two .mintignored README files, which are read on GitHub.
5. Run npm run check and npm run validate.

How it deploys

There is no deploy workflow in this repository. Publishing is meant to run through the Mintlify GitHub App: connect privacykey/docs-mantis in the Mintlify dashboard, install the app for this repository, and set / as the docs source path. Mintlify then builds from main after each push. The app is not connected yet, which is why no site is live.

Three workflows do run here:

• Mintlify (.github/workflows/mintlify.yml) validates the build and checks internal links on every pull request and every push to main.
• Link check (.github/workflows/linkcheck.yml) runs npm run check and then lychee over external links, on content changes and weekly on Mondays. A scheduled failure opens an issue.
• Sync changelog (.github/workflows/sync-changelog.yml) regenerates changelog.mdx daily from GitHub Releases on privacykey/mantis and opens a pull request if the file moved. Do not edit changelog.mdx by hand.