Skip to main content

​
Documentation

This page covers where the docs live, the style guide every page follows, how Mintlify is set up and synced, and how to disconnect it if you need to.

​
Where docs live

All documentation lives under apps/documentation/. The directory maps 1:1 to the Mintlify site structure — folder names become URL path segments, file names become page URLs. 
apps/documentation/
├── docs.json               ← Mintlify site config (nav, theme, colors)
├── getting-started/
├── architecture/
├── tooling/
├── deployment/
├── quality/                ← you are here
└── support.md
Write everything in Markdown (.md). The sync workflow converts them to .mdx automatically before pushing to Mintlify. You never need to touch .mdx files directly.

​
Style guide

Every page in Refract’s docs follows the same shape. Here’s the short version: Tone — Warm and direct, like a knowledgeable teammate explaining things over coffee. No filler, no committee-speak. First-person is fine. Short sentences. Structure — Every page should have:
  1. A one-sentence frontmatter description
  2. An 🤖 Agent context block right after the H1 (see format below)
  3. Clear sections with code examples
  4. A What's next? section at the bottom
Code blocks — Always include a language tag (```ts, ```bash, etc.). When in doubt, show the code. Callouts — Use Mintlify’s native callout syntax: 
<Note>Standard note for human readers.</Note>
<Warning>Something that will break if ignored.</Warning>
<Tip>A shortcut or best practice.</Tip>
Agent context blocks — Every section describing a system needs one of these: 
<details>
<summary>🤖 Agent context</summary>

Business logic belongs in `apps/backend/src/utilities/`.
❌ Never put business logic in a GraphQL resolver.
Verify with: `make test module=backend`

</details>
These blocks serve two audiences: human developers who want clear boundaries, and AI coding agents that use the docs as context when generating code. Links between docs — Use root-absolute, extensionless paths. Mintlify resolves these directly whether the file was pushed as .md or converted to .mdx: 
[Configuration system](/architecture/configuration-system)
⚠️ Watch out: Don’t use relative .md paths like ../architecture/configuration-system.md — those only work after the sync script rewrites them. Root-absolute paths work immediately on every push.

​
Mintlify setup

Refract’s documentation is hosted on Mintlify. The connection lives entirely in GitHub — there’s no separate build step you need to run. How to connect a new Mintlify project:
  1. Sign up at mintlify.com and create a new project.
  2. In the Mintlify dashboard, install the Mintlify GitHub App on your repo and set the docs root to apps/documentation.
  3. Mintlify will look for apps/documentation/docs.json as the site config. It’s already there.
  4. That’s it — no secrets or API keys needed. The integration runs through the GitHub App.
How the sync works: When a PR merges into main, the mintlify-docs-sync workflow automatically runs .github/scripts/mintlify_sync.mjs. That script:
  1. Snapshots every file under apps/documentation/ into memory.
  2. Converts .md files to .mdx.
  3. Rewrites internal links to extensionless, root-absolute Mintlify routes.
  4. Validates all .mdx files for parse errors and broken links.
  5. Commits the converted files back to the repo (Mintlify watches the repo and picks up the commit).
You can also trigger the sync manually from the GitHub Actions tab using workflow_dispatch.

​
How to disconnect Mintlify

If you decide to move away from Mintlify, here’s how to cleanly disconnect:
  1. In the Mintlify dashboard — go to Settings → Danger Zone and disconnect the GitHub integration.
  2. Remove the workflow — delete .github/workflows/mintlify-docs-sync.yml and .github/scripts/mintlify_sync.mjs.
  3. Keep the source docs — apps/documentation/ stays as-is. The .md files are plain Markdown and work with any static site generator (Docusaurus, VitePress, etc.).
  4. Remove docs.json — this is Mintlify-specific. If you’re moving to another platform, replace it with that platform’s config file.
The source documentation is yours and is completely portable. The only Mintlify-specific pieces are docs.json and the sync workflow.

​
What’s next?