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.
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:
Agent context blocks — Every section describing a system needs one of these:
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:
⚠️ 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. If you are using a custom docs domain, manage the domain and DNS at the provider level (Cloudflare is the recommended setup in this project) and keep that operational guide in deployment docs, not in random page-level notes. 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 (with an optional dry_run flag). Source and target roots are intentionally locked to apps/documentation to prevent accidental writes to other directories.

​
Domain and DNS guidance

Custom docs domains should be documented as part of deployment operations so they are easy to audit and hand off. For Cloudflare-specific domain transfer, DNS records, CDN cache behavior, and SSL/TLS setup, use: When you update domain settings, also verify docs links and canonical URLs still resolve after propagation.

​
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?