From bf12c1c17c5952929985a0c0107d0acdb9b115db Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Tue, 6 Jan 2026 22:31:48 +0000 Subject: [PATCH 01/12] Update docs.json Co-Authored-By: mintlify[bot] <109931778+mintlify[bot]@users.noreply.github.com> --- docs.json | 90 +++++++++++++++++++++++++++---------------------------- 1 file changed, 45 insertions(+), 45 deletions(-) diff --git a/docs.json b/docs.json index 89b194877..a7a354b82 100644 --- a/docs.json +++ b/docs.json @@ -63,56 +63,26 @@ ] }, { - "group": "Create content", + "group": "Web editor", "icon": "pen-line", "pages": [ - { - "group": "Web editor", - "pages": [ - "editor/index", - "editor/pages", - "editor/media", - "editor/navigation", - "editor/configurations", - "editor/collaborate", - "editor/publish", - "editor/keyboard-shortcuts" - ] - }, + "editor/index", + "editor/pages", + "editor/media", + "editor/navigation", + "editor/configurations", + "editor/collaborate", + "editor/publish", + "editor/keyboard-shortcuts" + ] + }, + { + "group": "Create content", + "icon": "file-text", + "pages": [ "installation", "create/text", "create/code", - "ai/agent", - "ai/suggestions", - { - "group": "Components", - "pages": [ - "components/index", - "components/accordions", - "components/badge", - "components/banner", - "components/callouts", - "components/cards", - "components/code-groups", - "components/color", - "components/columns", - "components/examples", - "components/expandables", - "components/fields", - "components/frames", - "components/icons", - "components/mermaid-diagrams", - "components/panel", - "components/responses", - "components/steps", - "components/tabs", - "components/tiles", - "components/tooltips", - "components/tree", - "components/update", - "components/view" - ] - }, "create/image-embeds", "create/files", "create/list-table", @@ -121,6 +91,36 @@ "create/changelogs" ] }, + { + "group": "Components", + "icon": "blocks", + "pages": [ + "components/index", + "components/accordions", + "components/badge", + "components/banner", + "components/callouts", + "components/cards", + "components/code-groups", + "components/color", + "components/columns", + "components/examples", + "components/expandables", + "components/fields", + "components/frames", + "components/icons", + "components/mermaid-diagrams", + "components/panel", + "components/responses", + "components/steps", + "components/tabs", + "components/tiles", + "components/tooltips", + "components/tree", + "components/update", + "components/view" + ] + }, { "group": "Document APIs", "icon": "file-json", From 9922cf3f49a75e61c480dfa636f5acc0cfbe4904 Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Tue, 6 Jan 2026 22:32:09 +0000 Subject: [PATCH 02/12] Update docs.json Co-Authored-By: mintlify[bot] <109931778+mintlify[bot]@users.noreply.github.com> --- docs.json | 44 +++++++++++++++++++++++++++++--------------- 1 file changed, 29 insertions(+), 15 deletions(-) diff --git a/docs.json b/docs.json index a7a354b82..d7e447809 100644 --- a/docs.json +++ b/docs.json @@ -137,11 +137,37 @@ ] }, { - "group": "Deploy", - "icon": "boxes", + "group": "AI features", + "icon": "bot", + "pages": [ + "ai/agent", + "ai/suggestions", + "ai/assistant", + "ai/discord", + "ai/slack-bot", + "ai/contextual-menu", + "ai/llmstxt", + "ai/model-context-protocol", + "ai/markdown-export" + ] + }, + { + "group": "Deployment", + "icon": "rocket", "pages": [ "deploy/deployments", "deploy/preview-deployments", + "deploy/ci", + "deploy/github", + "deploy/ghes", + "deploy/gitlab", + "deploy/monorepo" + ] + }, + { + "group": "Hosting", + "icon": "server", + "pages": [ { "group": "/docs subpath", "pages": [ @@ -155,22 +181,13 @@ }, "deploy/authentication-setup", "deploy/personalization-setup", - "deploy/monorepo", - "deploy/vercel-external-proxies", - "deploy/ci", - "deploy/github", - "deploy/ghes", - "deploy/gitlab" + "deploy/vercel-external-proxies" ] }, { "group": "Optimize", "icon": "wrench", "pages": [ - "ai/assistant", - "ai/discord", - "ai/slack-bot", - "ai/contextual-menu", { "group": "Insights", "pages": [ @@ -178,10 +195,7 @@ "insights/feedback" ] }, - "ai/llmstxt", - "ai/model-context-protocol", "optimize/seo", - "ai/markdown-export", "optimize/pdf-exports", { "group": "Integrations", From 632994706282f9289f7efba9d047cd5d214515a7 Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Tue, 6 Jan 2026 22:33:13 +0000 Subject: [PATCH 03/12] Update troubleshooting.mdx Co-Authored-By: mintlify[bot] <109931778+mintlify[bot]@users.noreply.github.com> --- troubleshooting.mdx | 224 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 224 insertions(+) create mode 100644 troubleshooting.mdx diff --git a/troubleshooting.mdx b/troubleshooting.mdx new file mode 100644 index 000000000..f30f5040e --- /dev/null +++ b/troubleshooting.mdx @@ -0,0 +1,224 @@ +--- +title: Troubleshooting +description: Common issues and solutions for Mintlify documentation +--- + +This guide covers common issues you might encounter when working with Mintlify and how to resolve them. + +## Build errors + +### Syntax errors in MDX files + +**Problem**: Build fails with parsing errors. + +**Solution**: Check your MDX files for: +- Unclosed JSX tags +- Missing closing braces in component props +- Invalid frontmatter YAML syntax +- Special characters that need escaping + +Run `mintlify dev` locally to identify the specific file and line causing the error. + +### Missing or invalid frontmatter + +**Problem**: Pages don't display correctly or build fails. + +**Solution**: Ensure every MDX file has valid frontmatter: + +```yaml +--- +title: Your page title +description: A brief description +--- +``` + +Both `title` and `description` are required fields. + +### Navigation configuration errors + +**Problem**: Build fails with navigation-related errors. + +**Solution**: Verify your `docs.json` navigation structure: +- All page paths reference existing MDX files +- No duplicate page entries +- Proper JSON syntax (commas, brackets, quotes) +- Valid icon names from the Lucide library + +## Preview issues + +### Local preview not updating + +**Problem**: Changes don't appear in `mintlify dev`. + +**Solution**: +1. Stop the dev server (Ctrl+C) +2. Clear your browser cache +3. Restart with `mintlify dev` +4. Hard refresh your browser (Ctrl+Shift+R or Cmd+Shift+R) + +### Images not loading + +**Problem**: Images show broken or don't display. + +**Solution**: +- Verify image paths are relative to the MDX file +- Check that images exist in your repository +- Ensure image files are committed to Git +- Use supported formats (PNG, JPG, SVG, GIF, WebP) +- Check file names don't contain spaces or special characters + +### Components not rendering + +**Problem**: Mintlify components display as plain text or don't work. + +**Solution**: +- Verify component syntax matches documentation +- Check for typos in component names (case-sensitive) +- Ensure props are properly formatted +- Close all component tags properly + +## Deployment issues + +### Build succeeds locally but fails in production + +**Problem**: `mintlify dev` works but deployment fails. + +**Solution**: +- Check for environment-specific file paths +- Verify all files are committed and pushed to Git +- Review deployment logs for specific error messages +- Ensure `docs.json` is valid JSON (use a JSON validator) + +### Changes not appearing after deployment + +**Problem**: Deployed site doesn't reflect recent changes. + +**Solution**: +1. Verify changes are pushed to the correct branch +2. Check deployment status in your Mintlify dashboard +3. Clear CDN cache if using custom domain +4. Wait 2-3 minutes for propagation +5. Hard refresh your browser + +### Custom domain not working + +**Problem**: Custom domain shows errors or doesn't connect. + +**Solution**: +- Verify DNS records are correctly configured +- Allow 24-48 hours for DNS propagation +- Check that CNAME points to your Mintlify subdomain +- Ensure SSL certificate has been issued (can take up to 24 hours) + +## Search issues + +### Search not finding pages + +**Problem**: Search doesn't return expected results. + +**Solution**: +- Ensure pages are included in navigation (hidden pages aren't indexed) +- Add descriptive `title` and `description` in frontmatter +- Include relevant keywords in page content +- Wait for search index to rebuild after deployment (5-10 minutes) + +### Search showing outdated content + +**Problem**: Search results show old content. + +**Solution**: +- Redeploy your documentation to trigger reindexing +- Clear browser cache +- Wait 10-15 minutes for search index to update + +## API documentation issues + +### OpenAPI spec not loading + +**Problem**: API reference pages don't generate or show errors. + +**Solution**: +- Validate your OpenAPI spec using [Swagger Editor](https://editor.swagger.io/) +- Ensure the spec file path in `docs.json` is correct +- Check that the spec is valid JSON or YAML +- Verify the spec version is supported (OpenAPI 3.0+) + +### API playground not working + +**Problem**: Try it out feature doesn't work. + +**Solution**: +- Check CORS configuration on your API server +- Verify authentication setup in `docs.json` +- Ensure API endpoints are accessible +- Check browser console for error messages + +## Authentication issues + +### Users can't access protected docs + +**Problem**: Authentication fails or loops. + +**Solution**: +- Verify JWT configuration in `docs.json` +- Check token expiration settings +- Ensure authentication endpoint is accessible +- Review authentication logs in dashboard +- Test with a fresh browser session (incognito mode) + +## Performance issues + +### Slow page loads + +**Problem**: Documentation loads slowly. + +**Solution**: +- Optimize image sizes (use WebP format, compress images) +- Reduce number of custom scripts +- Minimize use of large embedded content +- Consider lazy loading for heavy components + +### Build takes too long + +**Problem**: Deployment builds are slow. + +**Solution**: +- Reduce number of pages if possible +- Optimize image assets +- Remove unused files from repository +- Check for circular dependencies in snippets + +## Git integration issues + +### GitHub/GitLab connection fails + +**Problem**: Can't connect repository or deployments don't trigger. + +**Solution**: +- Verify repository permissions (Mintlify needs read access) +- Check that webhook is properly configured +- Ensure branch name matches configuration +- Re-authenticate Git integration in dashboard + +### Merge conflicts in docs.json + +**Problem**: Navigation changes cause merge conflicts. + +**Solution**: +- Pull latest changes before editing navigation +- Use web editor for navigation changes when possible +- Coordinate with team on navigation updates +- Keep navigation changes in separate commits + +## Getting help + +If you're still experiencing issues: + +1. Check the [status page](https://www.mintlify.com/docs/status) for known incidents +2. Search [GitHub discussions](https://github.com/orgs/mintlify/discussions) for similar issues +3. Review deployment logs in your dashboard +4. [Contact support](https://www.mintlify.com/docs/contact-support) with: + - Detailed description of the issue + - Steps to reproduce + - Error messages or screenshots + - Your repository URL (if public) From 587accedfb39af656d9ea4db88aefc6c43e6b6ec Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Tue, 6 Jan 2026 22:33:20 +0000 Subject: [PATCH 04/12] Update docs.json Co-Authored-By: mintlify[bot] <109931778+mintlify[bot]@users.noreply.github.com> --- docs.json | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs.json b/docs.json index d7e447809..cf8867c72 100644 --- a/docs.json +++ b/docs.json @@ -28,7 +28,8 @@ "index", "quickstart", "ai-native", - "migration" + "migration", + "troubleshooting" ] }, { From 58e1df86a8b7ed2684bc16d627dba75f946ccf0c Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Tue, 6 Jan 2026 22:34:08 +0000 Subject: [PATCH 05/12] Update guides/migrate-from-gitbook.mdx Co-Authored-By: mintlify[bot] <109931778+mintlify[bot]@users.noreply.github.com> --- guides/migrate-from-gitbook.mdx | 341 ++++++++++++++++++++++++++++++++ 1 file changed, 341 insertions(+) create mode 100644 guides/migrate-from-gitbook.mdx diff --git a/guides/migrate-from-gitbook.mdx b/guides/migrate-from-gitbook.mdx new file mode 100644 index 000000000..21f034b97 --- /dev/null +++ b/guides/migrate-from-gitbook.mdx @@ -0,0 +1,341 @@ +--- +title: Migrate from GitBook +description: Step-by-step guide to migrate your documentation from GitBook to Mintlify +--- + +This guide walks you through migrating your documentation from GitBook to Mintlify. + +## Before you start + + + + GitBook stores content in Markdown format. Export your content: + + 1. Go to your GitBook space settings + 2. Navigate to **Advanced** → **Export** + 3. Choose **Markdown & Images** format + 4. Download the ZIP file + + + + If you haven't already, create a new Mintlify project: + + ```bash + npm i -g mintlify + mintlify init + ``` + + + +## Migration process + +### 1. Extract and organize content + +Extract your GitBook export and review the structure: + +``` +gitbook-export/ +├── README.md +├── SUMMARY.md +├── page-1.md +├── page-2.md +└── .gitbook/ + └── assets/ +``` + +GitBook uses `SUMMARY.md` for navigation. You'll convert this to Mintlify's `docs.json` format. + +### 2. Convert navigation structure + +GitBook's `SUMMARY.md` looks like this: + +```markdown +# Table of contents + +* [Introduction](README.md) +* [Getting Started](getting-started.md) + * [Installation](getting-started/installation.md) + * [Configuration](getting-started/configuration.md) +* [API Reference](api-reference/README.md) + * [Authentication](api-reference/authentication.md) +``` + +Convert this to Mintlify's `docs.json` navigation: + +```json +{ + "navigation": { + "pages": [ + "introduction", + { + "group": "Getting started", + "pages": [ + "getting-started/installation", + "getting-started/configuration" + ] + }, + { + "group": "API reference", + "pages": [ + "api-reference/overview", + "api-reference/authentication" + ] + } + ] + } +} +``` + +### 3. Update frontmatter + +GitBook files may have minimal or no frontmatter. Add Mintlify frontmatter to each file: + +**Before (GitBook):** +```markdown +# Page Title + +Content here... +``` + +**After (Mintlify):** +```mdx +--- +title: Page Title +description: Brief description of this page +--- + +Content here... +``` + +### 4. Convert GitBook-specific syntax + +#### Hints and callouts + +**GitBook syntax:** +```markdown +{% hint style="info" %} +This is an info hint +{% endhint %} + +{% hint style="warning" %} +This is a warning +{% endhint %} +``` + +**Mintlify syntax:** +```mdx + +This is an info hint + + + +This is a warning + +``` + +#### Tabs + +**GitBook syntax:** +```markdown +{% tabs %} +{% tab title="JavaScript" %} +```javascript +console.log('Hello'); +``` +{% endtab %} + +{% tab title="Python" %} +```python +print('Hello') +``` +{% endtab %} +{% endtabs %} +``` + +**Mintlify syntax:** +```mdx + +```javascript JavaScript +console.log('Hello'); +``` + +```python Python +print('Hello') +``` + +``` + +#### Page links + +**GitBook syntax:** +```markdown +[Link text](../other-page.md) +[Link with anchor](page.md#section) +``` + +**Mintlify syntax:** +```mdx +[Link text](/other-page) +[Link with anchor](/page#section) +``` + +Remove `.md` extensions and use absolute paths from the root. + +#### Embedded content + +**GitBook syntax:** +```markdown +{% embed url="https://www.youtube.com/watch?v=VIDEO_ID" %} +``` + +**Mintlify syntax:** +```mdx + + ", + "url": "https://example.com", + "title": "Example" +} +[/block] +``` + +**Mintlify syntax:** +```mdx + +