From a091f102ddb2a7767b22b5267bb60017883a3cc4 Mon Sep 17 00:00:00 2001
From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com>
Date: Mon, 1 Dec 2025 22:39:56 +0000
Subject: [PATCH 01/13] Update optimize/seo.mdx
---
optimize/seo.mdx | 6 +++++-
1 file changed, 5 insertions(+), 1 deletion(-)
diff --git a/optimize/seo.mdx b/optimize/seo.mdx
index ca24f9cbd..aa2ca0eac 100644
--- a/optimize/seo.mdx
+++ b/optimize/seo.mdx
@@ -1,9 +1,13 @@
---
title: "SEO"
description: "Optimize SEO with meta tag configuration for better search visibility."
-keywords: ["meta tags", "sitemap", "robots.txt", "SEO", "search engine optimization"]
+keywords: ["meta tags", "sitemap", "robots.txt", "SEO", "search engine optimization", "keyword research"]
---
+
+This page covers both technical SEO configuration and content optimization strategies.
+
+
Mintlify automatically handles many SEO best practices, including:
- Meta tag generation
From 01a256cdc16e2459c1c84f9f7319d24914621096 Mon Sep 17 00:00:00 2001
From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com>
Date: Mon, 1 Dec 2025 22:40:15 +0000
Subject: [PATCH 02/13] Update optimize/seo.mdx
---
optimize/seo.mdx | 16 ++++++++++++++++
1 file changed, 16 insertions(+)
diff --git a/optimize/seo.mdx b/optimize/seo.mdx
index aa2ca0eac..3f28a075b 100644
--- a/optimize/seo.mdx
+++ b/optimize/seo.mdx
@@ -251,3 +251,19 @@ You can also specify `noindex` for all pages in your docs by setting the `metata
- Use relevant images that support your content
+
+## Page performance
+
+Use tools like [Google PageSpeed Insights](https://pagespeed.web.dev) to identify areas for technical SEO improvement.
+
+Examples of more advanced optimizations:
+
+- **Optimize media for speed:** Compress images using formats like WebP or AVIF and ensure your pages load quickly (ideally under 3 seconds).
+- **Structured data (schema markup):** Add schema markup (like HowTo, FAQ) to your pages to help search engines better understand and rank your content.
+
+## Keyword research
+
+To increase organic traffic, invest time into understanding which keywords help users land on your documentation.
+
+- **Keyword research:** Use free tools like [Google Keyword Planner](https://ads.google.com/intl/en_us/home/tools/keyword-planner/) or [Keywords Everywhere](https://keywordseverywhere.com) to identify common phrases or long-tail keywords.
+- **Integrate keywords naturally:** Add keywords naturally into headings, subheadings, and throughout the body text. Don't overstuff keywords. Your documentation should be written for your users, not search engines.
From 3a7569351b79ef5552b3c8d43a1eeafc6a30c9d3 Mon Sep 17 00:00:00 2001
From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com>
Date: Mon, 1 Dec 2025 22:40:23 +0000
Subject: [PATCH 03/13] Update docs.json
---
docs.json | 1 -
1 file changed, 1 deletion(-)
diff --git a/docs.json b/docs.json
index 18fc06f02..32f82a6d7 100644
--- a/docs.json
+++ b/docs.json
@@ -259,7 +259,6 @@
"guides/maintenance",
"guides/media",
"guides/navigation",
- "guides/seo",
"guides/style-and-tone",
"guides/understand-your-audience"
]
From f5e981bd3811e4d3f698890a6a3fd0aba6909ff1 Mon Sep 17 00:00:00 2001
From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com>
Date: Mon, 1 Dec 2025 22:40:29 +0000
Subject: [PATCH 04/13] Update docs.json
---
docs.json | 1 -
1 file changed, 1 deletion(-)
diff --git a/docs.json b/docs.json
index 32f82a6d7..9d3fddf1a 100644
--- a/docs.json
+++ b/docs.json
@@ -568,7 +568,6 @@
"fr/guides/maintenance",
"fr/guides/media",
"fr/guides/navigation",
- "fr/guides/seo",
"fr/guides/style-and-tone",
"fr/guides/understand-your-audience"
]
From 7a682227461231070e01fb31e5b6670394427bef Mon Sep 17 00:00:00 2001
From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com>
Date: Mon, 1 Dec 2025 22:40:35 +0000
Subject: [PATCH 05/13] Update docs.json
---
docs.json | 1 -
1 file changed, 1 deletion(-)
diff --git a/docs.json b/docs.json
index 9d3fddf1a..e8db6bb25 100644
--- a/docs.json
+++ b/docs.json
@@ -877,7 +877,6 @@
"es/guides/maintenance",
"es/guides/media",
"es/guides/navigation",
- "es/guides/seo",
"es/guides/style-and-tone",
"es/guides/understand-your-audience"
]
From 4c480ab9eb61767e33c9107679bd98c93bd807bd Mon Sep 17 00:00:00 2001
From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com>
Date: Mon, 1 Dec 2025 22:40:41 +0000
Subject: [PATCH 06/13] Update docs.json
---
docs.json | 1 -
1 file changed, 1 deletion(-)
diff --git a/docs.json b/docs.json
index e8db6bb25..2de9e3e06 100644
--- a/docs.json
+++ b/docs.json
@@ -1186,7 +1186,6 @@
"zh/guides/maintenance",
"zh/guides/media",
"zh/guides/navigation",
- "zh/guides/seo",
"zh/guides/style-and-tone",
"zh/guides/understand-your-audience"
]
From c9803f666116fd3052ece53fa1f93b6855995c09 Mon Sep 17 00:00:00 2001
From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com>
Date: Mon, 1 Dec 2025 22:40:47 +0000
Subject: [PATCH 07/13] Update docs.json
---
docs.json | 4 ++++
1 file changed, 4 insertions(+)
diff --git a/docs.json b/docs.json
index 2de9e3e06..2df14eff9 100644
--- a/docs.json
+++ b/docs.json
@@ -1738,6 +1738,10 @@
{
"source": "/create/broken-links",
"destination": "/create/redirects"
+ },
+ {
+ "source": "/guides/seo",
+ "destination": "/optimize/seo"
}
],
"integrations": {
From 20f986734edb320a21715555c82e9a276e37755d Mon Sep 17 00:00:00 2001
From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com>
Date: Mon, 1 Dec 2025 22:40:51 +0000
Subject: [PATCH 08/13] Delete guides/seo.mdx
---
guides/seo.mdx | 43 -------------------------------------------
1 file changed, 43 deletions(-)
delete mode 100644 guides/seo.mdx
diff --git a/guides/seo.mdx b/guides/seo.mdx
deleted file mode 100644
index 888a231c8..000000000
--- a/guides/seo.mdx
+++ /dev/null
@@ -1,43 +0,0 @@
----
-title: "SEO"
-description: "Improve SEO to increase documentation discoverability."
-keywords: ["search engine optimization", "meta tags", "keyword research"]
----
-
-
-This page explains fundamental strategies to optimize your documentation SEO.
-
-
-## Content basics
-
-Make your writing and structure easy for search engines to scan.
-
-- **Headings and subheadings:** Use sequential, meaningful headers to structure your content. Each page has an H1 created from the `title:` property in the frontmatter.
-- **Short paragraphs and bullet points:** Break down large chunks of text into easily readable sections. Use bullet points and numbered lists where appropriate.
-- **Internal linking:** Link to related content using descriptive anchor text. For example, "Learn more about rate limiting" instead of "Click here."
-
-## Technical SEO basics
-
-Once your content is optimized, ensure your documentation performs well from a technical standpoint.
-
-These basic technical SEO practices help make your docs more discoverable:
-
-- **Meta tags and descriptions:** Craft SEO-friendly titles (50-60 characters) and descriptions (150-160 characters) for each page. Most [meta tags](/optimize/seo) are automatically generated.
-- **Alt text for images:** Provide descriptive alt text for images with relevant keywords. For example, "OAuth 2.0 API authentication flow" instead of just "diagram". This enhances SEO and accessibility.
-- **Sitemaps:** Ensure your sitemap is up-to-date. Mintlify automatically generates a sitemap. However, you can manually create a sitemap if you prefer a custom format. Once created, search engines index site maps over time, but you can submit your sitemap directly to Google Search Console to speed up the process.
-
-## Page performance
-
-Use tools like [Google PageSpeed Insights](https://pagespeed.web.dev) to identify areas for technical SEO improvement.
-
-Examples of more advanced optimizations:
-
-- **Optimize media for speed:** Compress images using formats like WebP or AVIF and ensure your pages load quickly (ideally under 3 seconds).
-- **Structured data (schema markup):** Add schema markup (like HowTo, FAQ) to your pages to help search engines better understand and rank your content.
-
-## Keyword research
-
-To increase organic traffic, invest time into understanding which keywords help users land on your documentation.
-
-- **Keyword research:** Use free tools like [Google Keyword Planner](https://ads.google.com/intl/en_us/home/tools/keyword-planner/) or [Keywords Everywhere](https://keywordseverywhere.com) to identify common phrases or long-tail keywords.
-- **Integrate keywords naturally:** Add keywords naturally into headings, subheadings, and throughout the body text. Don't overstuff keywords. Your documentation should be written for your users, not search engines.
From 6d1e0828b2fda0fa99d2ebb0e1797a7842b95d2e Mon Sep 17 00:00:00 2001
From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com>
Date: Mon, 1 Dec 2025 22:40:56 +0000
Subject: [PATCH 09/13] Delete es/guides/seo.mdx
---
es/guides/seo.mdx | 51 -----------------------------------------------
1 file changed, 51 deletions(-)
delete mode 100644 es/guides/seo.mdx
diff --git a/es/guides/seo.mdx b/es/guides/seo.mdx
deleted file mode 100644
index 7ea89555c..000000000
--- a/es/guides/seo.mdx
+++ /dev/null
@@ -1,51 +0,0 @@
----
-title: "SEO"
-description: "Mejora el SEO para aumentar la visibilidad de tu documentación."
-keywords: ["search engine optimization", "meta tags", "keyword research"]
----
-
-
-Esta página explica estrategias fundamentales para optimizar el SEO de tu documentación.
-
-
-
- ## Conceptos básicos de contenido
-
-
-Facilita que los motores de búsqueda exploren tu redacción y estructura.
-
-* **Encabezados y subtítulos:** Usa encabezados secuenciales y con sentido para estructurar tu contenido. Cada página tiene un H1 generado a partir de la propiedad `title:` en el frontmatter.
-* **Párrafos breves y viñetas:** Divide bloques grandes de texto en secciones fáciles de leer. Usa viñetas y listas numeradas cuando corresponda.
-* **Enlaces internos:** Enlaza contenido relacionado usando texto de anclaje descriptivo. Por ejemplo, "Más información sobre limitación de tasa" en lugar de "Haz clic aquí".
-
-
- ## Conceptos básicos de SEO técnico
-
-
-Una vez que tu contenido esté optimizado, asegúrate de que tu documentación rinda bien desde el punto de vista técnico.
-
-Estas prácticas básicas de SEO técnico ayudan a que tu documentación sea más fácil de encontrar:
-
-* **Metatags y descripciones:** Redacta títulos optimizados para SEO (50–60 caracteres) y descripciones (150–160 caracteres) para cada página. La mayoría de los [metatags](/es/optimize/seo) se generan automáticamente.
-* **Texto alternativo para imágenes:** Incluye texto alternativo descriptivo en las imágenes con palabras clave relevantes. Por ejemplo, “flujo de autenticación de API con OAuth 2.0” en lugar de solo “diagrama”. Esto mejora el SEO y la accesibilidad.
-* **Sitemaps:** Asegúrate de que tu sitemap esté actualizado. Mintlify genera automáticamente un sitemap. No obstante, puedes crear uno manualmente si prefieres un formato personalizado. Una vez creado, los motores de búsqueda lo indexan con el tiempo, pero puedes enviar tu sitemap directamente a Google Search Console para acelerar el proceso.
-
-
- ## Rendimiento de la página
-
-
-Usa herramientas como [Google PageSpeed Insights](https://pagespeed.web.dev) para identificar oportunidades de mejora técnica de SEO.
-
-Ejemplos de optimizaciones más avanzadas:
-
-* **Optimiza los recursos para mayor velocidad:** Comprime imágenes con formatos como WebP o AVIF y asegúrate de que tus páginas carguen rápido (idealmente en menos de 3 segundos).
-* **Datos estructurados (schema markup):** Añade marcado de esquema (p. ej., HowTo, FAQ) a tus páginas para ayudar a los motores de búsqueda a comprender y posicionar mejor tu contenido.
-
-
- ## Investigación de palabras clave
-
-
-Para aumentar el tráfico orgánico, dedica tiempo a comprender qué palabras clave ayudan a los usuarios a llegar a tu documentación.
-
-* **Investigación de palabras clave:** Utiliza herramientas gratuitas como [Google Keyword Planner](https://ads.google.com/intl/en_us/home/tools/keyword-planner/) o [Keywords Everywhere](https://keywordseverywhere.com) para identificar frases habituales o palabras clave de cola larga.
-* **Integra las palabras clave de forma natural:** Incorpora las palabras clave de manera natural en títulos, subtítulos y a lo largo del cuerpo del texto. No las sobrecargues. Tu documentación debe estar escrita para tus usuarios, no para los motores de búsqueda.
\ No newline at end of file
From 06c23b29656263a3276f7a5ebffeedfbdd8921df Mon Sep 17 00:00:00 2001
From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com>
Date: Mon, 1 Dec 2025 22:41:05 +0000
Subject: [PATCH 10/13] Delete fr/guides/seo.mdx
---
fr/guides/seo.mdx | 51 -----------------------------------------------
1 file changed, 51 deletions(-)
delete mode 100644 fr/guides/seo.mdx
diff --git a/fr/guides/seo.mdx b/fr/guides/seo.mdx
deleted file mode 100644
index 554b4b2ae..000000000
--- a/fr/guides/seo.mdx
+++ /dev/null
@@ -1,51 +0,0 @@
----
-title: "SEO"
-description: "Améliorez le SEO pour accroître la visibilité de votre documentation."
-keywords: ["search engine optimization", "meta tags", "keyword research"]
----
-
-
-Cette page explique des stratégies essentielles pour optimiser le SEO de votre documentation.
-
-
-
- ## Principes de base du contenu
-
-
-Facilitez l’exploration de votre contenu et de sa structure par les moteurs de recherche.
-
-* **Titres et sous-titres :** Utilisez des en-têtes séquentiels et explicites pour structurer votre contenu. Chaque page comporte un H1 généré à partir de la propriété `title:` dans le frontmatter.
-* **Paragraphes courts et listes :** Divisez les blocs de texte volumineux en sections faciles à lire. Utilisez des listes à puces et des listes numérotées lorsque c’est pertinent.
-* **Liens internes :** Créez des liens vers du contenu connexe en utilisant un texte d’ancrage descriptif. Par exemple, « En savoir plus sur la limitation de débit » plutôt que « Cliquez ici ».
-
-
- ## Principes de base du SEO technique
-
-
-Une fois votre contenu optimisé, assurez-vous que votre documentation fonctionne bien sur le plan technique.
-
-Ces pratiques fondamentales en SEO technique rendent votre documentation plus facilement découvrable :
-
-* **Balises meta et descriptions :** Rédigez des titres optimisés pour le SEO (50–60 caractères) et des descriptions (150–160 caractères) pour chaque page. La plupart des [balises meta](/fr/optimize/seo) sont générées automatiquement.
-* **Texte alternatif pour les images :** Fournissez un texte alternatif descriptif pour les images, intégrant des mots-clés pertinents. Par exemple, « Flux d’authentification OAuth 2.0 d’une API » plutôt que simplement « diagramme ». Cela améliore le SEO et l’accessibilité.
-* **Sitemaps :** Assurez-vous que votre sitemap est à jour. Mintlify génère automatiquement un sitemap. Vous pouvez toutefois créer manuellement un sitemap si vous préférez un format personnalisé. Une fois créé, les moteurs de recherche l’indexent au fil du temps, mais vous pouvez soumettre votre sitemap directement dans la Google Search Console pour accélérer le processus.
-
-
- ## Performance des pages
-
-
-Utilisez des outils comme [Google PageSpeed Insights](https://pagespeed.web.dev) pour identifier les axes d’amélioration technique en SEO (Search Engine Optimization).
-
-Exemples d’optimisations plus avancées :
-
-* **Optimiser les médias pour la vitesse :** Compressez les images avec des formats comme WebP ou AVIF et veillez à ce que vos pages se chargent rapidement (idéalement en moins de 3 secondes).
-* **Données structurées (balisage de schéma) :** Ajoutez du balisage de schéma (comme HowTo, FAQ) à vos pages pour aider les moteurs de recherche à mieux comprendre et classer votre contenu.
-
-
- ## Recherche de mots-clés
-
-
-Pour augmenter le trafic organique, prenez le temps de comprendre quels mots-clés aident les utilisateurs à trouver votre documentation.
-
-* **Recherche de mots-clés :** Utilisez des outils gratuits comme [Google Keyword Planner](https://ads.google.com/intl/en_us/home/tools/keyword-planner/) ou [Keywords Everywhere](https://keywordseverywhere.com) pour identifier des expressions courantes ou des mots-clés de longue traîne.
-* **Intégrez les mots-clés naturellement :** Ajoutez des mots-clés de manière naturelle dans les titres, sous-titres et dans le corps du texte. N’abusez pas des mots-clés. Votre documentation doit être rédigée pour vos utilisateurs, pas pour les moteurs de recherche.
\ No newline at end of file
From 225bb33045b0f6f24b72a15531cc65c04754647f Mon Sep 17 00:00:00 2001
From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com>
Date: Mon, 1 Dec 2025 22:41:09 +0000
Subject: [PATCH 11/13] Delete zh/guides/seo.mdx
---
zh/guides/seo.mdx | 51 -----------------------------------------------
1 file changed, 51 deletions(-)
delete mode 100644 zh/guides/seo.mdx
diff --git a/zh/guides/seo.mdx b/zh/guides/seo.mdx
deleted file mode 100644
index 6b1384d62..000000000
--- a/zh/guides/seo.mdx
+++ /dev/null
@@ -1,51 +0,0 @@
----
-title: "SEO（搜索引擎优化）"
-description: "优化 SEO，提升文档的可发现性。"
-keywords: ["search engine optimization", "meta tags", "keyword research"]
----
-
-
-本页介绍优化文档 SEO 的基础策略。
-
-
-
- ## 内容基础
-
-
-让你的写作与结构便于搜索引擎快速扫描。
-
-* **标题与副标题：** 使用循序且有意义的标题来组织内容。每个页面都有一个由 frontmatter 中的 `title:` 属性生成的 H1。
-* **短段落与项目列表：** 将大段文本拆分为易读的部分。在合适的场景使用项目符号和编号列表。
-* **内部链接：** 使用具描述性的锚文本链接到相关内容。例如，使用“了解更多关于速率限制”的表述，而不是“点击这里”。
-
-
- ## 技术 SEO 基础
-
-
-在优化好内容后，也要确保文档在技术层面表现良好。
-
-这些基础的技术 SEO（搜索引擎优化）做法有助于提升文档的可发现性：
-
-* **Meta 标签与描述：** 为每个页面撰写有利于 SEO 的标题（50–60 个字符）和描述（150–160 个字符）。大多数[meta 标签](/zh/optimize/seo)会自动生成。
-* **图片 Alt 文本：** 为图片提供包含相关关键词的描述性 alt 文本。例如，用 “OAuth 2.0 API 认证流程” 而不是仅写 “diagram”。这有助于提升 SEO 和可访问性。
-* **站点地图（Sitemaps）：** 确保站点地图为最新。Mintlify 会自动生成站点地图；如需自定义格式，也可手动创建。创建后，搜索引擎会随着时间索引站点地图，但你也可以将其直接提交到 Google Search Console 以加快收录。
-
-
- ## 页面性能
-
-
-使用 [Google PageSpeed Insights](https://pagespeed.web.dev) 等工具识别可改进的技术层面 SEO（搜索引擎优化）机会。
-
-更高级的优化示例：
-
-* **为速度优化媒体：** 使用 WebP 或 AVIF 等格式压缩图片，并确保页面加载迅速（理想情况下不超过 3 秒）。
-* **结构化数据（schema 标注）：** 在页面中添加 schema 标注（如 HowTo、FAQ），帮助搜索引擎更好地理解并提升内容的排名。
-
-
- ## 关键词研究
-
-
-为提升自然流量，花时间了解哪些关键词能帮助用户找到你的文档。
-
-* **关键词研究：** 使用免费的工具，例如 [Google Keyword Planner](https://ads.google.com/intl/en_us/home/tools/keyword-planner/) 或 [Keywords Everywhere](https://keywordseverywhere.com)，来识别常见词组或长尾关键词。
-* **自然融入关键词：** 将关键词自然地融入标题、副标题以及正文各处。不要刻意堆砌关键词。你的文档应以用户为中心，而非搜索引擎。
\ No newline at end of file
From b731a88130502ac83296673a41cb4ce7ae84c24a Mon Sep 17 00:00:00 2001
From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com>
Date: Mon, 1 Dec 2025 22:41:58 +0000
Subject: [PATCH 12/13] Update troubleshooting.mdx
---
troubleshooting.mdx | 171 ++++++++++++++++++++++++++++++++++++++++++++
1 file changed, 171 insertions(+)
create mode 100644 troubleshooting.mdx
diff --git a/troubleshooting.mdx b/troubleshooting.mdx
new file mode 100644
index 000000000..6efcb4d68
--- /dev/null
+++ b/troubleshooting.mdx
@@ -0,0 +1,171 @@
+---
+title: "Troubleshooting"
+description: "Resolve common issues with your Mintlify documentation."
+keywords: ["troubleshooting", "errors", "issues", "debugging", "help"]
+---
+
+This page covers common issues you may encounter when setting up or maintaining your Mintlify documentation.
+
+## Build and deployment issues
+
+
+
+ 1. **Check deployment status**: Visit the [Mintlify dashboard](https://dashboard.mintlify.com) to verify your deployment completed successfully.
+ 2. **Clear browser cache**: Hard refresh your browser (Cmd+Shift+R on Mac, Ctrl+Shift+R on Windows) or try incognito mode.
+ 3. **Verify file is in navigation**: Pages must be listed in `docs.json` navigation to be accessible.
+ 4. **Check for build errors**: Run `mintlify dev` locally to catch syntax or configuration errors before deploying.
+
+
+
+ Common causes:
+ - **Invalid JSON in docs.json**: Use a JSON validator to check for syntax errors like trailing commas or missing quotes.
+ - **Missing required frontmatter**: Every MDX file needs at minimum a `title` field.
+ - **Broken internal links**: Links to pages that don't exist will cause build warnings. Use relative paths without file extensions.
+
+ Run `mintlify dev` locally to see detailed error messages.
+
+
+
+ 1. Ensure preview deployments are enabled in your [dashboard settings](https://dashboard.mintlify.com).
+ 2. Check that your GitHub/GitLab integration has the correct permissions.
+ 3. Verify the PR is targeting the correct branch configured in your dashboard.
+
+
+
+## Content and formatting issues
+
+
+
+ - **Check component syntax**: Components are case-sensitive. Use `` not ``.
+ - **Close all tags**: Self-closing tags need a slash: `
` not `
`.
+ - **Escape special characters**: Use `\{` to display literal curly braces in text.
+ - **Check for JSX conflicts**: Angle brackets in code examples may need to be wrapped in backticks.
+
+
+
+ Ensure you specify the language after the opening backticks:
+
+ ````md
+ ```javascript
+ const example = "highlighted";
+ ```
+ ````
+
+ Supported languages include: `javascript`, `typescript`, `python`, `bash`, `json`, `yaml`, `mdx`, and [many more](https://prismjs.com/#supported-languages).
+
+
+
+ 1. **Check the path**: Use paths relative to your docs root, starting with `/`.
+ 2. **Verify file exists**: Ensure the image file is committed to your repository.
+ 3. **Check file format**: Supported formats include PNG, JPG, GIF, SVG, and WebP.
+ 4. **File size**: Very large images may fail to load. Optimize images under 1MB.
+
+ ```mdx
+ 
+ ```
+
+
+
+ Ensure proper Markdown table syntax:
+ - Header row must be followed by a separator row with dashes
+ - Each row must have the same number of columns
+ - Pipes must align (though this is optional)
+
+ ```md
+ | Header 1 | Header 2 |
+ | -------- | -------- |
+ | Cell 1 | Cell 2 |
+ ```
+
+
+
+## Navigation issues
+
+
+
+ 1. **Add to navigation**: Pages must be listed in `docs.json` under `navigation`.
+ 2. **Check the path**: The path in navigation should match the file path without the `.mdx` extension.
+ 3. **Verify file location**: The MDX file must exist at the specified path.
+
+ ```json
+ "pages": ["folder/my-page"] // matches folder/my-page.mdx
+ ```
+
+
+
+ Pages appear in the order listed in `docs.json`. Reorder the entries in your navigation array to change the display order.
+
+
+
+ 1. **Use relative paths**: Link to `/page-name` not `https://yourdocs.com/page-name`.
+ 2. **Omit file extensions**: Use `/guides/quickstart` not `/guides/quickstart.mdx`.
+ 3. **Check case sensitivity**: Paths are case-sensitive on most systems.
+ 4. **Add redirects**: If you've moved a page, add a redirect in `docs.json`:
+
+ ```json
+ "redirects": [
+ { "source": "/old-path", "destination": "/new-path" }
+ ]
+ ```
+
+
+
+## Custom domain issues
+
+
+
+ 1. **Verify DNS settings**: Check that your CNAME record points to `cname.mintlify.com`.
+ 2. **Wait for propagation**: DNS changes can take up to 48 hours to propagate.
+ 3. **Check SSL certificate**: Mintlify automatically provisions SSL, but this can take a few minutes after DNS propagation.
+ 4. **Verify in dashboard**: Ensure the custom domain is correctly configured in your Mintlify dashboard.
+
+
+
+ SSL certificates are automatically provisioned. If you see certificate errors:
+ 1. Wait 10-15 minutes after DNS propagation for certificate provisioning.
+ 2. Clear your browser's SSL cache or try a different browser.
+ 3. Verify your DNS is correctly pointing to Mintlify's servers.
+
+
+
+## Local development issues
+
+
+
+ Install the Mintlify CLI globally:
+
+ ```bash
+ npm install -g mintlify
+ ```
+
+ Or use npx to run without installing:
+
+ ```bash
+ npx mintlify dev
+ ```
+
+
+
+ 1. Stop the dev server (Ctrl+C)
+ 2. Clear the `.mintlify` cache folder in your project
+ 3. Restart with `mintlify dev`
+
+
+
+ The default port is 3000. If it's in use, specify a different port:
+
+ ```bash
+ mintlify dev --port 3001
+ ```
+
+
+
+## Getting more help
+
+If you're still experiencing issues:
+
+1. **Check the [status page](https://status.mintlify.com)** for any ongoing incidents.
+2. **Search the [GitHub discussions](https://github.com/mintlify/mint/discussions)** for similar issues.
+3. **Contact support** through the Mintlify dashboard or at [hi@mintlify.com](mailto:hi@mintlify.com).
+
+For API-specific issues, see the [API playground troubleshooting guide](/api-playground/troubleshooting).
From 75216da96f5f5322a588e09735bd829c44a33682 Mon Sep 17 00:00:00 2001
From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com>
Date: Mon, 1 Dec 2025 22:42:04 +0000
Subject: [PATCH 13/13] Update docs.json
---
docs.json | 3 ++-
1 file changed, 2 insertions(+), 1 deletion(-)
diff --git a/docs.json b/docs.json
index 2df14eff9..2203abe42 100644
--- a/docs.json
+++ b/docs.json
@@ -30,7 +30,8 @@
"installation",
"editor",
"ai-native",
- "migration"
+ "migration",
+ "troubleshooting"
]
},
{