From e1c09bfdd6b4ea800ba2f18d140e0c0837deef9d Mon Sep 17 00:00:00 2001 From: adamXbot <111877622+adamXbot@users.noreply.github.com> Date: Sun, 9 Aug 2026 18:44:09 +1000 Subject: [PATCH] docs: restructure the README to the portfolio standard Reorders the README into the standard docs-repo shape: heading, status badge, disclosure block, where to read the docs, local commands, file layout, adding a page, and how it deploys. Corrections: - The one-line description said mantis is a "self-hostable mantis key service". It is a canary key service, per docs.json and index.mdx. - The deploy instructions told you to connect `privacykey/mantis-docs` in the Mintlify dashboard. That name only resolves as a rename redirect; the repository is `privacykey/docs-mantis`. - The README implied the docs site was a going concern. No docs domain for this project resolves, and no Mintlify GitHub App check appears on `main`, so the site is not live. The README now says so instead of pointing readers at a host that does not exist. - "The same checks run in GitHub Actions on pushes and pull requests" covered only two of the three workflows and omitted `npm run check`, the weekly external-link run and the daily changelog sync. All three workflows are now described with their real triggers. - The page index omitted `index.mdx`, `cli.md`, `cli-backup.md`, `changelog.mdx` and `deployment/index.mdx`, which are all in the docs.json navigation. They are listed now, grouped as the navigation groups them. Adds the frontmatter and navigation-registration rules enforced by scripts/check-docs.mjs, and the `just` shorthands from the justfile. No content was removed from the repository; the page annotations from the old link index are preserved in the file-layout section. README.md: 2998 -> 6324 bytes. Co-Authored-By: Claude Opus 5 --- README.md | 89 ++++++++++++++++++++++++++++--------------------------- 1 file changed, 46 insertions(+), 43 deletions(-) diff --git a/README.md b/README.md index 136eeda..76495bc 100644 --- a/README.md +++ b/README.md @@ -1,71 +1,74 @@ -# mantis docs +# docs-mantis -The Mintlify documentation source for [`privacykey/mantis`](https://github.com/privacykey/mantis), a self-hostable mantis key service. +The Mintlify documentation source for [`privacykey/mantis`](https://github.com/privacykey/mantis), a self-hostable canary key service. -## Local preview +[![Project status](https://img.shields.io/endpoint?url=https%3A%2F%2Fraw.githubusercontent.com%2Fprivacykey%2F.github%2Fmain%2Fbadges%2Fdocs-mantis.json)](https://github.com/privacykey/.github/blob/main/STATUS.md#docs-mantis) + + +> [!WARNING] +> **Project status.** The badge above is generated from [the privacykey status list](https://github.com/privacykey/.github/blob/main/STATUS.md), 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`](./index.mdx), or jump to [Getting started](./getting-started.md). + +## Run it locally ```bash npm run dev ``` -Mintlify serves the local preview at `http://localhost:3000`. +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. -## Validate +Before opening a pull request, run the same two checks CI runs: ```bash -npm run validate -npm run check-links +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 ``` -The same checks run in GitHub Actions on pushes and pull requests. +If you have [`just`](https://github.com/casey/just) installed, `just run` and `just lint` are shorthands for the same commands. -## Deploy with Mintlify +## File layout -Connect `privacykey/mantis-docs` in the Mintlify dashboard, install the Mintlify GitHub App for this repository, and use `/` as the docs source path. Mintlify will deploy automatically from `main` after each push. +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. -## Getting started +The navigation groups in `docs.json`, and the files behind them: -- [Getting started](./getting-started.md) — CLI install → first key, in five steps -- [Trying it locally](./trying-locally.md) — Docker evaluation, local-dev setup for contributors, benchmarks -- [Use cases](./use-cases.md) — defensive, detective, operational, and adversarial-research patterns +**Start** — [`index.mdx`](./index.mdx) (site landing page), [`getting-started.md`](./getting-started.md) (CLI install to first key, in five steps), [`trying-locally.md`](./trying-locally.md) (Docker evaluation, local-dev setup for contributors, benchmarks), [`use-cases.md`](./use-cases.md) (defensive, detective, operational, and adversarial-research patterns). -## Deployment +**Deployment** — [`deployment/index.mdx`](./deployment/index.mdx) is the group root and the chooser between local, tunnelled and PaaS options. Then [`docker-local.md`](./deployment/docker-local.md) (option A), [`tailscale.md`](./deployment/tailscale.md) (B), [`cloudflare.md`](./deployment/cloudflare.md) (C), [`railway.md`](./deployment/railway.md) (E1), [`fly.md`](./deployment/fly.md) (E2), [`render.md`](./deployment/render.md) (E3), [`edge-limits.md`](./deployment/edge-limits.md) (rate limiting, DDoS, WAF), [`backups.md`](./deployment/backups.md) (Postgres backup strategies), and [`edge-deployment.md`](./edge-deployment.md) (the stateless mantis-edge Cloudflare Worker variant). -- [Overview & chooser](./deployment/README.md) — picking between local, tunnelled, and PaaS options -- [Local Docker](./deployment/docker-local.md) (option A) -- [Docker + Tailscale](./deployment/tailscale.md) (option B) -- [Docker + Cloudflare Tunnel](./deployment/cloudflare.md) (option C) -- [Railway](./deployment/railway.md) (option E1) -- [Fly.io](./deployment/fly.md) (option E2) -- [Render](./deployment/render.md) (option E3) -- [Edge limits](./deployment/edge-limits.md) — rate limiting / DDoS / WAF guidance -- [Backups](./deployment/backups.md) — Postgres backup strategies -- [mantis-edge worker](./edge-deployment.md) — Cloudflare Worker (stateless) variant +**Reference** — [`api.md`](./api.md) (endpoints, response kinds, webhook payload shape), [`configuration.md`](./configuration.md) (required and optional environment variables), [`cli.md`](./cli.md) (every command and flag), [`cli-backup.md`](./cli-backup.md), [`updating.md`](./updating.md) (update commands per component), [`changelog.mdx`](./changelog.mdx). -## Reference +**Features** — [`file-keys.md`](./file-keys.md) (Office/PDF/SVG/HTML/Markdown/email/calendar/contact artifacts, honey-directory ZIP, NFC label PDF, Apple Wallet `.pkpass`), [`honey-directory.md`](./honey-directory.md) (the nine-file `.zip` bundle for shared drives), [`host-events.md`](./host-events.md) (shell / login / boot / wake / network installers, web embeds, NFC, smart home, and the `X-Mantis-*` header reference), [`uptime-kuma.md`](./uptime-kuma.md) (fan-out via Kuma's notification channels), [`reliability.md`](./reliability.md) (hit dedup, retry queue, UA and bot parsing). -- [HTTP API](./api.md) — endpoints, response kinds, webhook payload shape -- [Configuration](./configuration.md) — required and optional env vars -- [Updating](./updating.md) — update commands per component (server, CLI, edge worker, IoT helper) +**Operating** — [`single-user.md`](./single-user.md) (admin / non-admin behaviour), [`operational-notes.md`](./operational-notes.md) (key hashing, disabled-key responses, worker model), [`dev-inbox.md`](./dev-inbox.md) (built-in webhook capture for local dev). -## Features +**Recipes** — [`self-hosted-apps.md`](./self-hosted-apps.md), per-app recipes for Immich, Paperless, Joplin, Vaultwarden, dashboards and code hosts. -- [File keys](./file-keys.md) — Office/PDF/SVG/HTML/Markdown/email/calendar/contact artifacts, honey-directory ZIP, NFC label PDF, and Apple Wallet `.pkpass` -- [Honey directory](./honey-directory.md) — 9-file `.zip` bundle for shared-drive deployment -- [Host-event keys](./host-events.md) — shell / login / boot / wake / network installers, web embeds, NFC, smart-home, and the `X-Mantis-*` header reference -- [Uptime Kuma integration](./uptime-kuma.md) — fan-out via Kuma's 80+ notification channels -- [Reliability](./reliability.md) — hit dedup, retry queue, UA / bot parsing +**Architecture** — [`architecture.md`](./architecture.md), a directory map of the product source tree. -## Operating +## Adding a page -- [Single-user model](./single-user.md) — admin / non-admin behaviour -- [Operational notes](./operational-notes.md) — key hashing, disabled-key responses, worker model -- [Dev inbox](./dev-inbox.md) — built-in webhook capture for local dev +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 `.mintignore`d README files, which are read on GitHub. +5. Run `npm run check` and `npm run validate`. -## Recipes +## How it deploys -- [Self-hosted apps](./self-hosted-apps.md) — per-app recipes (Immich, Paperless, Joplin, Vaultwarden, dashboards, code hosts) +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. -## Architecture +Three workflows do run here: -- [Project layout](./architecture.md) — directory map of the source tree +- **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.