Deploy docs on Mintlify

​

Prerequisites

• A GitHub repository for your fork of vibestrap.
• A domain you own (e.g. your-product.com) — the docs will live at docs.your-product.com.
• Access to your DNS provider’s dashboard.

​

What ships in the repo already

• docs/docs.json — Mintlify’s config file. Defines name, theme, colors, navigation, footer, navbar links, and SEO defaults.
• docs/*.mdx and docs/<group>/*.mdx — 36 English pages organized into 9 navigation groups.
• docs/zh/... — Chinese mirror of every English page.
• docs/logo/{light,dark}.svg and docs/favicon.svg — placeholder branding you should replace with your own.

​

Step 1: Sign up for Mintlify

1. Go to mintlify.com/start.
2. Sign up with the GitHub account that owns your fork.
3. Pick the Hobby plan — it’s free and supports custom domains.

​

Step 2: Connect your repository

1. In the Mintlify dashboard, click Connect GitHub.
2. Install the Mintlify GitHub App when prompted. Scope it to just your vibestrap fork (you can add more repos later).
3. Select the repository.

​

Step 3: Configure the source

• Repository: <your-org>/vibestrap
• Branch: main
• Subdirectory: docs ← this is the critical one. Mintlify reads docs/docs.json as the config and treats every page slug as relative to that subdirectory.

​

Step 4: Verify the preview build

1. Watch the Overview → Deployments page in the dashboard. The first build typically takes 1–2 minutes.
2. When it finishes, click the preview URL — something like your-org.mintlify.app.
3. Open it. You should see the full vibestrap docs site with the navigation sidebar, language switcher, and search bar.

• A page listed in docs/docs.json → navigation doesn’t exist on disk.
• An MDX file uses <https://example.com> autolink syntax (Mintlify rejects it — use [example.com](https://example.com) instead).
• Frontmatter is missing title or description.

​

Step 5: Custom domain

1. In Mintlify dashboard → Settings → Custom domain.
2. Enter docs.your-product.com.
3. Mintlify shows the DNS record you need to add. It looks like:
   Type   Host   Value
   CNAME  docs   cname.mintlify-dns.com.
   
4. Add that CNAME record at your DNS provider (Cloudflare, Vercel DNS, Namecheap, Route53, etc.).
5. Wait. Propagation usually takes 1–24 hours. Mintlify auto-provisions an SSL certificate via Let’s Encrypt once DNS resolves.

​

Step 6: Update vibestrap’s links

links: {
  // ...
  docs: 'https://docs.your-product.com',
}

​

Editing flow afterwards

• Every push to main that touches docs/ or docs/docs.json triggers a Mintlify re-deploy automatically. There’s no extra CI step.
• Local preview: pnpm dlx mintlify dev from the repo root. The CLI reads docs/docs.json and serves at localhost:3000 — same port as pnpm dev, so don’t run both at once.
• Bilingual content: any new page must be created in both docs/<path>.mdx and docs/zh/<path>.mdx. Add the slug to both language groups in docs/docs.json. Mintlify won’t auto-link them.

​

Branding checklist

1. Logo: edit docs/logo/light.svg and docs/logo/dark.svg. Keep the 220×48 viewBox so the navbar height stays consistent.
2. Favicon: replace docs/favicon.svg.
3. Theme color: edit docs/docs.json → colors.primary (hex).
4. Site name: edit docs/docs.json → name.
5. Navbar links + primary CTA: edit docs/docs.json → navbar.
6. Footer: edit docs/docs.json → footer.socials and footer.links.
7. SEO: edit docs/docs.json → seo.metatags.

​

Common pitfalls

1. Wrong source directory: if the dashboard shows “no pages found”, double-check the Source directory setting is docs, not / or content/docs.
2. Page in docs/ but not in docs/docs.json: the page renders but is orphaned (no sidebar entry, no search hit). Add it to the matching language group in docs/docs.json → navigation.languages.
3. Page in docs/docs.json but not in docs/: the build fails. Either create the file or remove the slug from the navigation.
4. Custom-domain TLS pending: after adding the CNAME, Mintlify shows a “TLS provisioning” badge for up to 24 hours. If still pending after that, re-check the CNAME record matches exactly (no extra dot, no trailing slash, target is cname.mintlify-dns.com.).
5. Mixing English and Chinese pages in one group: Mintlify treats navigation.languages[i].groups strictly — only put en/* pages under the en language entry, only zh/* under the zh entry. Cross-language links should be plain markdown links, not navigation entries.

​

Official docs

• mintlify.com/docs — full Mintlify reference
• docs.json schema reference — every configuration option
• Navigation — group, tab, anchor, dropdown, language structures
• Internationalization — multilingual setup
• Custom domain — DNS records and SSL provisioning
• Components — built-in MDX components (Tabs, Steps, Callouts, Cards, etc.)