Skip to main content
Last curated: set by the encore-mintlify-curator skill Single source of truth for the Mintlify docs site at docs/. Everything in this document is binding; if you change the conventions, update this file in the same PR.
If documents conflict, constitution.md wins.

​
1. Local development

Hot-reload triggers on *.md, *.mdx, and docs.json edits. The Mintlify CLI is bundled — no separate npm install mintlify is needed. To debug a single page without booting the full site, copy the page into docs/_drafts/<name>.mdx (gitignored via .mintignore) and navigate to http://localhost:3000/_drafts/<name>. If mint dev fails with a node-version error, check .nvmrc (currently 24).

​
2. docs.json shape

The docs.json schema is https://mintlify.com/docs.json (line 1 of the file). Top-level keys we use: Each tab has a groups array. Each group has a group label, an optional icon, and a pages array. Pages can be either:
  • A bare string referencing a .md or .mdx file (without extension): "cl/note-templates"
  • A nested group object: { "group": "Charting & Documentation", "icon": "notes-medical", "pages": [...] }
expanded: false is the default for nested groups (the user clicks to expand). Set expanded: true only for the user’s primary landing-page group inside a tab. Icons come from Font Awesome free names. The full mapping policy lives in scripts/docs/icon-rules.yaml.

​
3. Frontmatter contract

Every published page MUST have:
Strongly recommended:
Validated by npm run docs:check-frontmatter. The curator skill (encore-mintlify-curator) runs this on every sweep. The description is rendered in search results and below the title — keep it under ~120 chars and avoid duplicating the title. No spec IDs in human-visible text: title, sidebarTitle, description, and the first H1 of Product/Guides/Trust-tab pages must not contain spec IDs (CL-15, HR-09-P5-4, …) — that’s what the spec: field is for. Engineering/Reference tabs are exempt. See docs/DOCUMENTATION_STANDARDS.md § Editorial Rules for Published Pages. Enforced by docs:check-frontmatter (blocking) and healed by the denumber curator sweep. Redirects are born permanent: when a cleanup/restructure retires a path, add its docs.json redirect with "permanent": true (301). Only genuinely transitional redirects (an A/B move you expect to revert) stay temporary.

​
4. Naming conventions

Files use kebab-case with the exception of the all-caps *-API-REFERENCE.md and *-MODULE-SETTINGS.md suffixes. The Phase 1 coverage scorecard (/docs-coverage) checks A1 against these exact patterns. Renaming them requires updating both this doc and scripts/docs/check-spec-doc-trio.ts.

​
5. MDX components — when to use which

Mintlify ships a set of MDX components. Pick semantic > plain markdown wherever the page would otherwise reach for ASCII workarounds. Lint enforces three of these (<Steps>, <Note>/<Warning>/<Tip>/<Info>, <Frame>). Run npm run docs:lint-mdx -- docs/<core> to surface opportunities.

​
6. .mintignore policy

.mintignore (at docs/.mintignore) tells Mintlify which paths NOT to publish. Patterns use gitignore syntax, relative to docs/. Leading / anchors to the docs root. Currently excluded: Rule: every new internal-only tree under docs/ MUST be added here AND to the curator’s exclusion list. If a path appears in .mintignore but is referenced from a published page, the link will 404.

​
7. Mintlify MCP — three usage patterns

The plugin:mintlify:Mintlify MCP server provides two tools. Skills use them in three named patterns documented here so they don’t drift.

​
Pattern A — “Does this doc already exist?”

Tool: mcp__plugin_mintlify_Mintlify__search_mintlify Used by: encore-docs-pipeline (Phase 1) before flagging an A1 doc missing. Reason: a doc may exist under a non-conventional name (e.g. docs/cl/encounter.md instead of docs/cl/cl-05-user-guide.md). The pipeline searches before declaring “missing” to avoid false positives. If a search hit returns a page that looks like the missing artifact, flag it as a naming-convention drift, not a hard miss.

​
Pattern B — “Where does this page live in nav?”

Tool: mcp__plugin_mintlify_Mintlify__query_docs_filesystem_mintlify Used by: encore-mintlify-curator (nav placement, audience-track adjacency) and encore-docs-pipeline (verify the trio is reachable from nav). Reason: parsing docs.json ourselves loses context (Mintlify’s own filesystem view knows about its overrides and groupings). Always go through this tool instead of re-implementing nav lookup.

​
Pattern C — “What’s the Mintlify-correct way to do X?”

Tool: mcp__plugin_mintlify_Mintlify__search_mintlify (with query targeting Mintlify’s own docs) Used by: encore-mintlify-curator when proposing MDX component upgrades or docs.json changes. Reason: Mintlify ships new components and config options frequently. Always consult the current Mintlify docs before recommending a structural change.

​
Wiring rule

Every “is X documented?” check goes through Pattern A first. Every nav-shape check goes through Pattern B. No skill re-implements either lookup against raw docs.json or fs.readdir.

​
8. Three audience tracks in nav

Three audiences (per the design spec): end users (clinicians, staff), tenant admins / operators, and internal devs & AI agents. Today’s nav uses topic-grouped tabs (Product, Operations) rather than per-audience tabs. Per-audience differentiation happens via the audience: frontmatter field; the curator skill enforces that user/admin/dev variants of the same feature live in adjacent nav slots within the same group (e.g. cl/note-user-guide, cl/note-admin-guide, cl/note-API-REFERENCE are sorted together). A future Phase 3 may split into per-audience tabs; for Phase 2 we keep the topic structure and rely on the audience tag for ordering.

​
9. Deploy

The Mintlify-hosted production site is connected to this repo. Pushing to the configured branch triggers a redeploy. PR previews are auto-attached as a check. The curator skill’s “last published commit” check compares the local HEAD to the live site’s deployed commit (via the Mintlify dashboard or the mcp__plugin_mintlify_Mintlify__* tools). If they’re more than ~7 days apart, the curator’s PR body flags it.

​
10. Coverage page

docs/operations/docs-health.mdx is regenerated by npm run docs:coverage -- --all and published under the Operations tab. Source of truth for the data is docs/reports/docs-health.json. The page is intentionally simple — it surfaces the same scorecard as the per-date DOCS_HEALTH_<date>.md reports but as a live page that auditors and the on-call dev can bookmark. To change what the page shows, edit renderHealthMdx() in scripts/docs/docs-health-writer.ts — do NOT hand-edit the .mdx file (your changes will be overwritten on the next coverage run).

​
11. Troubleshooting mint dev

Common failures and the fast fix: If you’ve checked the above and it still fails, copy the failing page into docs/_drafts/<name>.mdx (gitignored) and bisect from there.

​
12. Mintlify Cloud dashboard checklist

These settings live in the Mintlify Cloud UI (https://dashboard.mintlify.com) and are not in this repo. Confirm them after each major site change:

​
13. Canonical AI-governance file sync

The repo-root files (/constitution.md, /AGENTS.md, /AI_GUIDE.md) are the single source of truth for AI governance. They’re mirrored into docs/governance/canonical/{constitution,agents,ai-guide}.md so Mintlify can publish them as browsable pages — but the mirrors are generated, not authored.
The script prepends per-file frontmatter (title, description, icon) and a sync-source banner so the published page reads cleanly. The CI workflow docs-coverage.yml runs :check before the Mintlify build, so drift between the repo-root canonical files and the published mirrors is caught before merge. Never hand-edit docs/governance/canonical/*.md — edits made there will be overwritten on the next sync. Edit the canonical source at the repo root.

​
References