From 86b17e3c5908bfd579c896871947a5c6f5902919 Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Mon, 1 Dec 2025 21:40:38 +0000 Subject: [PATCH 01/34] Update fr/organize/mintignore.mdx --- fr/organize/mintignore.mdx | 43 +++++++++++++++++--------------------- 1 file changed, 19 insertions(+), 24 deletions(-) diff --git a/fr/organize/mintignore.mdx b/fr/organize/mintignore.mdx index 837ca43f4..55a97844b 100644 --- a/fr/organize/mintignore.mdx +++ b/fr/organize/mintignore.mdx @@ -1,16 +1,14 @@ --- title: "Mintignore" -description: "Exclure des fichiers et des répertoires spécifiques de votre documentation publiée." +description: "Exclure des fichiers et répertoires spécifiques de votre documentation publiée." keywords: ["exclure", "ignorer", "gitignore", "brouillons", "privé"] --- -Le fichier `.mintignore` vous permet d'exclure des fichiers et des répertoires spécifiques d'être traités et publiés sur votre site de documentation. +Le fichier `.mintignore` vous permet d'exclure des fichiers et répertoires spécifiques du traitement et de la publication sur votre site de documentation. -Utilisez `.mintignore` pour conserver les brouillons, les notes internes et les fichiers source en dehors de votre documentation publique tout en les gardant dans votre référentiel. +Utilisez `.mintignore` pour garder les brouillons, notes internes et fichiers sources hors de votre documentation publique tout en les conservant dans votre dépôt. -
- ## Créer un fichier .mintignore -
+## Créer un fichier .mintignore Créez un fichier `.mintignore` à la racine de votre répertoire de documentation. Ce fichier utilise la même syntaxe de motifs que `.gitignore`. @@ -26,28 +24,25 @@ internal/ private-notes.md ``` -Lorsque Mintlify génère votre documentation, il lit le fichier `.mintignore` et exclut de la génération tous les fichiers ou répertoires correspondants. +Lorsque Mintlify construit votre documentation, il lit le fichier `.mintignore` et exclut tous les fichiers ou répertoires correspondants du traitement. -Fichiers exclus : - -* n’apparaissent pas dans votre documentation publiée ; -* ne sont pas indexés pour la recherche ; -* ne sont pas accessibles aux visiteurs. +Fichiers exclus : +- N'apparaissent pas dans votre documentation publiée. +- Ne sont pas indexés pour la recherche. +- Ne sont pas accessibles aux visiteurs. - Contrairement aux [pages masquées](/fr/organize/hidden-pages), les fichiers exclus par `.mintignore` sont entièrement retirés de votre site et ne sont pas accessibles via leur URL. + Contrairement aux [pages cachées](/fr/organize/hidden-pages), les fichiers exclus par `.mintignore` sont complètement supprimés de votre site et ne peuvent pas être accédés par URL. -
- ## Syntaxe des motifs -
+## Syntaxe des motifs -Le fichier `.mintignore` utilise la même syntaxe que `.gitignore`. Voici quelques motifs courants : +Le fichier `.mintignore` suit la syntaxe `.gitignore`. Voici quelques motifs courants : -| Motif | Description | -| ------------------ | ------------------------------------------------------ | -| `drafts/` | Exclut l’intégralité du répertoire `drafts` | -| `*.draft.mdx` | Exclut tous les fichiers se terminant par `.draft.mdx` | -| `private-notes.md` | Exclut un fichier spécifique | -| `**/internal/**` | Exclut tout répertoire `internal`, quel que soit son niveau | -| `!important.mdx` | Annule un motif précédent (inclut le fichier) | \ No newline at end of file +| Motif | Description | +| ------------------ | ----------------------------------------------------- | +| `drafts/` | Exclut tout le répertoire `drafts` | +| `*.draft.mdx` | Exclut tous les fichiers se terminant par `.draft.mdx`| +| `private-notes.md` | Exclut un fichier spécifique | +| `**/internal/**` | Exclut tout répertoire `internal` à n'importe quel niveau | +| `!important.mdx` | Annule un motif précédent (inclut le fichier) | From 33d85c9193a9030fdd70cce8379cd5bec9131c84 Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Mon, 1 Dec 2025 21:40:46 +0000 Subject: [PATCH 02/34] Update es/organize/mintignore.mdx --- es/organize/mintignore.mdx | 45 +++++++++++++++++--------------------- 1 file changed, 20 insertions(+), 25 deletions(-) diff --git a/es/organize/mintignore.mdx b/es/organize/mintignore.mdx index 40415215c..caa20a28a 100644 --- a/es/organize/mintignore.mdx +++ b/es/organize/mintignore.mdx @@ -1,21 +1,19 @@ --- title: "Mintignore" -description: "Excluye archivos y directorios específicos de tu documentación publicada." -keywords: ["excluir", "ignorar", "gitignore", "borradores", "privados"] +description: "Excluir archivos y directorios específicos de tu documentación publicada." +keywords: ["excluir", "ignorar", "gitignore", "borradores", "privado"] --- -El archivo `.mintignore` te permite excluir archivos y directorios específicos para que no se procesen ni se publiquen en tu sitio de documentación. +El archivo `.mintignore` te permite excluir archivos y directorios específicos del procesamiento y publicación en tu sitio de documentación. -Usa `.mintignore` para mantener borradores, notas internas y archivos fuente fuera de tu documentación pública mientras los sigues conservando en tu repositorio. +Usa `.mintignore` para mantener borradores, notas internas y archivos fuente fuera de tu documentación pública mientras los conservas en tu repositorio. -
- ## Crear un archivo .mintignore -
+## Crear un archivo .mintignore -Crea un archivo `.mintignore` en la raíz de tu directorio de documentación. Este archivo utiliza la misma sintaxis de patrones que `.gitignore`. +Crea un archivo `.mintignore` en la raíz de tu directorio de documentación. Este archivo usa la misma sintaxis de patrones que `.gitignore`. ```plaintext .mintignore -# Excluir borradores de documentos +# Excluir documentos borrador drafts/ *.draft.mdx @@ -26,28 +24,25 @@ internal/ private-notes.md ``` -Cuando Mintlify construye tu documentación, lee el archivo `.mintignore` y excluye del procesamiento cualquier archivo o directorio que coincida. +Cuando Mintlify construye tu documentación, lee el archivo `.mintignore` y excluye cualquier archivo o directorio coincidente del procesamiento. Archivos excluidos: - -* No aparecen en tu documentación publicada. -* No se indexan en la búsqueda. -* No son accesibles para los visitantes. +- No aparecen en tu documentación publicada. +- No se indexan para búsqueda. +- No son accesibles para los visitantes. - A diferencia de las [páginas ocultas](/es/organize/hidden-pages), los archivos excluidos por `.mintignore` se eliminan completamente de tu sitio y no se puede acceder a ellos mediante una URL. + A diferencia de las [páginas ocultas](/es/organize/hidden-pages), los archivos excluidos por `.mintignore` se eliminan completamente de tu sitio y no se pueden acceder por URL. -
- ## Sintaxis de patrones -
+## Sintaxis de patrones -El archivo `.mintignore` sigue la sintaxis de `.gitignore`. Algunos patrones comunes son: +El archivo `.mintignore` sigue la sintaxis de `.gitignore`. Algunos patrones comunes incluyen: -| Pattern | Descripción | -| ------------------ | ---------------------------------------------------- | -| `drafts/` | Excluye todo el directorio `drafts` | -| `*.draft.mdx` | Excluye todos los archivos que terminan en `.draft.mdx` | -| `private-notes.md` | Excluye un archivo específico | +| Patrón | Descripción | +| ------------------ | -------------------------------------------------------- | +| `drafts/` | Excluye todo el directorio `drafts` | +| `*.draft.mdx` | Excluye todos los archivos que terminan en `.draft.mdx` | +| `private-notes.md` | Excluye un archivo específico | | `**/internal/**` | Excluye cualquier directorio `internal` en cualquier nivel | -| `!important.mdx` | Anula un patrón anterior (incluye el archivo) | \ No newline at end of file +| `!important.mdx` | Niega un patrón anterior (incluye el archivo) | From 6a29dc8d580e1531a2a1e27c1748796fe7bc9655 Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Mon, 1 Dec 2025 21:40:54 +0000 Subject: [PATCH 03/34] Update zh/organize/mintignore.mdx --- zh/organize/mintignore.mdx | 43 +++++++++++++++++--------------------- 1 file changed, 19 insertions(+), 24 deletions(-) diff --git a/zh/organize/mintignore.mdx b/zh/organize/mintignore.mdx index f10fc721d..faaaae2f5 100644 --- a/zh/organize/mintignore.mdx +++ b/zh/organize/mintignore.mdx @@ -1,18 +1,16 @@ --- title: "Mintignore" -description: "将特定文件和目录排除在已发布文档之外。" +description: "从已发布的文档中排除特定文件和目录。" keywords: ["排除", "忽略", "gitignore", "草稿", "私有"] --- -`.mintignore` 文件允许你将特定文件和目录从处理和发布到文档站点的流程中排除。 +`.mintignore` 文件允许您排除特定文件和目录，使其不被处理和发布到您的文档站点。 -使用 `.mintignore`，你可以在存储库中保留草稿、内部笔记和源文件的同时，将它们排除在公开文档之外。 +使用 `.mintignore` 将草稿、内部笔记和源文件保留在公共文档之外，同时在您的仓库中维护它们。 -
- ## 创建 .mintignore 文件 -
+## 创建 .mintignore 文件 -在文档根目录下创建一个 `.mintignore` 文件。该文件使用与 `.gitignore` 相同的匹配模式语法。 +在文档目录的根目录创建一个 `.mintignore` 文件。此文件使用与 `.gitignore` 相同的模式语法。 ```plaintext .mintignore # 排除草稿文档 @@ -26,28 +24,25 @@ internal/ private-notes.md ``` -当 Mintlify 构建你的文档时，它会读取 `.mintignore` 文件，并在处理时排除所有匹配的文件或目录。 +当 Mintlify 构建您的文档时，它会读取 `.mintignore` 文件并从处理中排除任何匹配的文件或目录。 被排除的文件： - -* 不会出现在你发布的文档中。 -* 不会被收录进搜索索引。 -* 访问者无法访问。 +- 不会出现在您发布的文档中。 +- 不会被索引用于搜索。 +- 访问者无法访问。 - 与[隐藏页面](/zh/organize/hidden-pages)不同，由 `.mintignore` 排除的文件会从你的站点中完全移除，无法通过 URL 访问。 + 与[隐藏页面](/zh/organize/hidden-pages)不同，被 `.mintignore` 排除的文件会从您的站点完全移除，无法通过 URL 访问。 -
- ## 模式语法 -
+## 模式语法 -`.mintignore` 文件遵循 `.gitignore` 的语法。常见的匹配模式包括： +`.mintignore` 文件遵循 `.gitignore` 语法。一些常见模式包括： -| 模式 | 说明 | -| ------------------ | ---------------------------------------------- | -| `drafts/` | 排除整个 `drafts` 目录 | -| `*.draft.mdx` | 排除所有以 `.draft.mdx` 结尾的文件 | -| `private-notes.md` | 排除特定文件 | -| `**/internal/**` | 排除位于任意层级的任何 `internal` 目录 | -| `!important.mdx` | 否定前面的模式（改为包含该文件） | \ No newline at end of file +| 模式 | 描述 | +| ------------------ | --------------------------------------- | +| `drafts/` | 排除整个 `drafts` 目录 | +| `*.draft.mdx` | 排除所有以 `.draft.mdx` 结尾的文件 | +| `private-notes.md` | 排除特定文件 | +| `**/internal/**` | 排除任何层级的 `internal` 目录 | +| `!important.mdx` | 否定之前的模式（包含该文件） | From 46040020614310239a04f76731f1766a2066d864 Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Mon, 1 Dec 2025 21:41:18 +0000 Subject: [PATCH 04/34] Update fr/components/color.mdx --- fr/components/color.mdx | 83 +++++++++++++---------------------------- 1 file changed, 25 insertions(+), 58 deletions(-) diff --git a/fr/components/color.mdx b/fr/components/color.mdx index 11d3cea83..0a3eec4b8 100644 --- a/fr/components/color.mdx +++ b/fr/components/color.mdx @@ -1,28 +1,23 @@ --- title: "Couleur" -description: "Affichez des palettes de couleurs avec une fonction de copie par simple clic." -keywords: ["color", "palette", "colors", "design system", "hex", "rgb", "rgba", "hsl", "oklch"] +description: "Afficher des palettes de couleurs avec fonctionnalité de copie au clic." +keywords: ["couleur", "palette", "couleurs", "système de design", "hex", "rgb", "rgba", "hsl", "oklch"] --- -Utilisez le composant Color pour présenter des palettes de couleurs dans votre documentation. Les couleurs peuvent être affichées dans une grille compacte ou organisées dans un tableau avec des lignes nommées. +Utilisez le composant Color pour présenter des palettes de couleurs dans votre documentation. Les couleurs peuvent être affichées dans une grille compacte ou organisées dans un tableau avec des lignes étiquetées. -
- ## Variante compacte -
+## Variante compacte -Affichez les couleurs dans une grille simple, avec leurs noms et leurs valeurs. +Affichez les couleurs dans une disposition en grille simple avec les noms et valeurs des couleurs. - - - -```mdx Compact example +```mdx Exemple compact @@ -31,30 +26,23 @@ Affichez les couleurs dans une grille simple, avec leurs noms et leurs valeurs. ``` +## Variante tableau -
- ## Variante en tableau -
- -Organisez les couleurs en lignes avec des libellés pour la documentation de votre système de design. +Organisez les couleurs en lignes étiquetées pour la documentation du système de design. - - - - -```mdx Table example +```mdx Exemple tableau @@ -68,26 +56,19 @@ Organisez les couleurs en lignes avec des libellés pour la documentation de vot ``` - -
- ## Formats de couleur -
+## Formats de couleur Le composant prend en charge tous les formats de couleur CSS, y compris hex, rgb, rgba, hsl et oklch. - - - - -```mdx Color formats example +```mdx Exemple formats de couleur @@ -97,22 +78,17 @@ Le composant prend en charge tous les formats de couleur CSS, y compris hex, rgb ``` +## Couleurs adaptées au thème -
- ## Couleurs adaptées au thème -
- -Définissez des couleurs distinctes pour les modes clair et sombre à l'aide d'un objet avec les propriétés `light` et `dark`. +Définissez différentes couleurs pour les modes clair et sombre en utilisant un objet avec les propriétés `light` et `dark`. - - -```mdx Theme-aware example +```mdx Exemple adapté au thème @@ -120,43 +96,34 @@ Définissez des couleurs distinctes pour les modes clair et sombre à l'aide ``` +## Propriétés -
- ## Propriétés -
- -
- ### Couleur -
+### Color - Style d’affichage de la palette de couleurs. Options : `compact` ou `table`. + Style d'affichage pour la palette de couleurs. Options : `compact` ou `table`. - Éléments ou lignes de couleur à afficher. + Éléments de couleur ou lignes à afficher. -
- ### Color.Row -
+### Color.Row - Libellé de la ligne de couleurs. + Étiquette pour la ligne de couleurs. - Éléments de couleur à afficher dans cette ligne. + Éléments de couleur à afficher dans la ligne. -
- ### Color.Item -
+### Color.Item - Nom ou label de la couleur. + Nom ou étiquette pour la couleur. - Valeur de la couleur dans n'importe quel format CSS, ou bien un objet contenant des valeurs distinctes pour les modes light et dark. - \ No newline at end of file + Valeur de couleur dans n'importe quel format CSS, ou un objet avec des valeurs pour les modes clair et sombre. + From 1cbb458b82c9b318a9ea76d507c779139dbfc9a7 Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Mon, 1 Dec 2025 21:41:37 +0000 Subject: [PATCH 05/34] Update es/components/color.mdx --- es/components/color.mdx | 85 +++++++++++++---------------------------- 1 file changed, 26 insertions(+), 59 deletions(-) diff --git a/es/components/color.mdx b/es/components/color.mdx index 5e749e003..61b4382f7 100644 --- a/es/components/color.mdx +++ b/es/components/color.mdx @@ -1,28 +1,23 @@ --- title: "Color" -description: "Muestra paletas de colores con funcionalidad de copiar al hacer clic." -keywords: ["color", "palette", "colors", "design system", "hex", "rgb", "rgba", "hsl", "oklch"] +description: "Mostrar paletas de colores con funcionalidad de copiar al hacer clic." +keywords: ["color", "paleta", "colores", "sistema de diseño", "hex", "rgb", "rgba", "hsl", "oklch"] --- -Usa el componente Color para mostrar paletas de colores en tu documentación. Los colores pueden mostrarse en una cuadrícula compacta u organizarse en una tabla con filas etiquetadas. +Usa el componente Color para mostrar paletas de colores en tu documentación. Los colores se pueden mostrar en una cuadrícula compacta u organizados en una tabla con filas etiquetadas. -
- ## Variante compacta -
+## Variante compacta -Muestra colores en una cuadrícula simple con nombres y valores de color. +Muestra colores en un diseño de cuadrícula simple con nombres y valores de colores. - - - -```mdx Compact example +```mdx Ejemplo compacto @@ -31,30 +26,23 @@ Muestra colores en una cuadrícula simple con nombres y valores de color. ``` +## Variante tabla -
- ## Variante de tabla -
- -Organiza los colores en filas etiquetadas para la documentación del sistema de diseño. +Organiza colores en filas etiquetadas para documentación de sistemas de diseño. - - - - -```mdx Table example +```mdx Ejemplo tabla @@ -68,26 +56,19 @@ Organiza los colores en filas etiquetadas para la documentación del sistema de ``` +## Formatos de color -
- ## Formatos de color -
- -El componente admite todos los formatos de color CSS, incluyendo hex, rgb, rgba, hsl y oklch. +El componente soporta todos los formatos de color CSS incluyendo hex, rgb, rgba, hsl y oklch. - - - - -```mdx Color formats example +```mdx Ejemplo formatos de color @@ -97,22 +78,17 @@ El componente admite todos los formatos de color CSS, incluyendo hex, rgb, rgba, ``` +## Colores adaptados al tema -
- ## Colores según el tema -
- -Define distintos colores para los modos claro y oscuro usando un objeto con las propiedades `light` y `dark`. +Define diferentes colores para los modos claro y oscuro usando un objeto con propiedades `light` y `dark`. - - -```mdx Theme-aware example +```mdx Ejemplo adaptado al tema @@ -120,43 +96,34 @@ Define distintos colores para los modos claro y oscuro usando un objeto con las ``` +## Propiedades -
- ## Propiedades -
- -
- ### Color -
+### Color - Estilo de presentación de la paleta de colores. Opciones: `compact` o `table`. + Estilo de visualización para la paleta de colores. Opciones: `compact` o `table`. - Elementos o filas de color que se mostrarán. + Elementos de color o filas a mostrar. -
- ### Color.Row -
+### Color.Row - Etiqueta de la fila de colores. + Etiqueta para la fila de colores. - Elementos de color que se muestran en la fila. + Elementos de color a mostrar en la fila. -
- ### Color.Item -
+### Color.Item - Nombre o etiqueta del color. + Nombre o etiqueta para el color. - Valor del color en cualquier formato CSS, o un objeto con valores para los modos claro y oscuro. - \ No newline at end of file + Valor de color en cualquier formato CSS, o un objeto con valores para modos claro y oscuro. + From 3e63f5d675798349fac55df4cd11db4a22f1710c Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Mon, 1 Dec 2025 21:41:54 +0000 Subject: [PATCH 06/34] Update zh/components/color.mdx --- zh/components/color.mdx | 77 ++++++++++++----------------------------- 1 file changed, 22 insertions(+), 55 deletions(-) diff --git a/zh/components/color.mdx b/zh/components/color.mdx index 3cb2dabae..6d1d4697a 100644 --- a/zh/components/color.mdx +++ b/zh/components/color.mdx @@ -1,28 +1,23 @@ --- title: "颜色" -description: "通过支持点击复制的方式展示颜色调色板。" -keywords: ["color", "palette", "colors", "design system", "hex", "rgb", "rgba", "hsl", "oklch"] +description: "显示带有点击复制功能的颜色调色板。" +keywords: ["颜色", "调色板", "色彩", "设计系统", "hex", "rgb", "rgba", "hsl", "oklch"] --- -在文档中使用 Color 组件来展示颜色调色板。颜色既可以以紧凑的网格形式显示，也可以在带有标签行的表格中进行分组展示。 +使用 Color 组件在文档中展示颜色调色板。颜色可以以紧凑网格形式显示，也可以在带有标签行的表格中组织。 -
- ## 紧凑样式 -
+## 紧凑变体 -以简单的网格布局显示颜色及其名称和值。 +以简单的网格布局显示颜色，包含颜色名称和值。 - - - -```mdx Compact example +```mdx 紧凑示例 @@ -31,30 +26,23 @@ keywords: ["color", "palette", "colors", "design system", "hex", "rgb", "rgba", ``` +## 表格变体 -
- ## 表格样式 -
- -将颜色按标签行进行整理，用于设计系统文档。 +将颜色组织成带标签的行，用于设计系统文档。 - - - - -```mdx Table example +```mdx 表格示例 @@ -68,26 +56,19 @@ keywords: ["color", "palette", "colors", "design system", "hex", "rgb", "rgba", ``` - -
- ## 颜色格式 -
+## 颜色格式 该组件支持所有 CSS 颜色格式，包括 hex、rgb、rgba、hsl 和 oklch。 - - - - -```mdx Color formats example +```mdx 颜色格式示例 @@ -97,22 +78,17 @@ keywords: ["color", "palette", "colors", "design system", "hex", "rgb", "rgba", ``` +## 主题感知颜色 -
- ## 随主题变化的颜色 -
- -使用包含 `light` 和 `dark` 属性的对象，为浅色和深色模式分别定义不同的颜色。 +使用带有 `light` 和 `dark` 属性的对象为浅色和深色模式定义不同的颜色。 - - -```mdx Theme-aware example +```mdx 主题感知示例 @@ -120,43 +96,34 @@ keywords: ["color", "palette", "colors", "design system", "hex", "rgb", "rgba", ``` +## 属性 -
- ## 属性 -
- -
- ### 颜色 -
+### Color - 颜色调色板的显示样式。可选值：`compact` 或 `table`。 + 颜色调色板的显示样式。选项：`compact` 或 `table`。 要显示的颜色项或行。 -
- ### Color.Row -
+### Color.Row 颜色行的标签。 - 该行中要显示的颜色项。 + 要在行中显示的颜色项。 -
- ### Color.Item -
+### Color.Item 颜色的名称或标签。 - 使用任意 CSS 格式表示的颜色值，或包含 light 和 dark 两种模式值的对象。 - \ No newline at end of file + 任何 CSS 格式的颜色值，或带有浅色和深色模式值的对象。 + From 5861bd119867690a9c9405fe1689b33aa4ba613e Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Mon, 1 Dec 2025 21:42:40 +0000 Subject: [PATCH 07/34] Update guides/troubleshooting.mdx --- guides/troubleshooting.mdx | 198 +++++++++++++++++++++++++++++++++++++ 1 file changed, 198 insertions(+) create mode 100644 guides/troubleshooting.mdx diff --git a/guides/troubleshooting.mdx b/guides/troubleshooting.mdx new file mode 100644 index 000000000..1e05359f5 --- /dev/null +++ b/guides/troubleshooting.mdx @@ -0,0 +1,198 @@ +--- +title: "Troubleshooting" +description: "Resolve common issues with your Mintlify documentation site." +keywords: ["troubleshooting", "errors", "issues", "debugging", "help"] +--- + +This guide covers common issues you may encounter when setting up and maintaining your Mintlify documentation site. + +## Build and deployment issues + + + + Ensure your `docs.json` file is in the root of your documentation repository. The file name must be exactly `docs.json` (lowercase). + + ``` + your-docs-repo/ + ├── docs.json + ├── index.mdx + └── ... + ``` + + + + 1. Check your deployment status in the [Mintlify dashboard](https://dashboard.mintlify.com). + 2. Verify the GitHub App has access to your repository. + 3. Clear your browser cache or try incognito mode. + 4. Wait a few minutes—deployments can take up to 5 minutes. + + + + Preview deployments require: + - The GitHub App installed with access to your repository + - A pull request (not just a branch push) + - No build errors in your documentation + + Check the PR comments for deployment status or errors. + + + + Run `mint dev` locally to see detailed error messages. Common causes: + - Invalid JSON in `docs.json` + - Missing required frontmatter fields + - Broken internal links + - Invalid MDX syntax + + + +## Local development issues + + + + Install the CLI globally: + + ```bash + npm i -g mint + ``` + + If you still get errors, ensure Node.js v20.17.0+ is installed and your PATH includes npm global binaries. + + + + 1. Check the terminal for error messages. + 2. Ensure you're running `mint dev` from the directory containing `docs.json`. + 3. Try clearing the `.mintlify` cache folder and restarting. + 4. Verify your `docs.json` is valid JSON. + + + + Hot reload may not work for: + - Changes to `docs.json` (restart required) + - New files (may need refresh) + - Syntax errors in MDX files + + Try stopping and restarting `mint dev`. + + + + Either stop the other process using port 3000, or specify a different port: + + ```bash + mint dev --port 3001 + ``` + + + +## Content and navigation issues + + + + 1. Verify the page is listed in `docs.json` navigation. + 2. Check the file path matches exactly (case-sensitive). + 3. Ensure the file has valid frontmatter with `title`. + 4. Check the file isn't excluded by `.mintignore`. + + + + Internal links should: + - Use relative paths without file extensions: `/guides/quickstart` + - Match the exact path in your navigation + - Not include the language prefix for same-language links + + Run `mint dev` to see broken link warnings. + + + + 1. Place images in a `/images` folder at your docs root. + 2. Reference with absolute paths: `/images/screenshot.png` + 3. Ensure file names don't contain spaces or special characters. + 4. Check the image file actually exists at that path. + + + + Add a language identifier after the opening backticks: + + ````mdx + ```javascript + const example = "highlighted"; + ``` + ```` + + Supported languages include: javascript, typescript, python, bash, json, yaml, and many more. + + + +## Custom domain issues + + + + 1. Verify DNS records are configured correctly: + - CNAME record pointing to `cname.vercel-dns.com` + 2. Allow up to 48 hours for DNS propagation. + 3. Use [DNSChecker](https://dnschecker.org) to verify your records. + 4. Ensure no conflicting A records exist. + + + + SSL certificates are automatically provisioned. If you see errors: + 1. Wait 24 hours after DNS configuration. + 2. Verify the domain is correctly configured in your dashboard. + 3. Contact support if issues persist after 48 hours. + + + + If using a reverse proxy or CDN: + 1. Ensure SSL/TLS is set to "Full" or "Full (Strict)". + 2. Disable any automatic HTTPS redirects on your proxy. + 3. Check for conflicting redirect rules. + + + +## Authentication issues + + + + 1. Verify authentication is properly configured in your dashboard. + 2. Check that the user's session hasn't expired. + 3. Ensure the authentication provider is returning the correct claims. + 4. Test with a fresh browser session. + + + + 1. Verify the callback URL is correctly configured in your OAuth provider. + 2. Check that client ID and secret are correct. + 3. Ensure the OAuth provider allows the redirect URI. + + + +## Performance issues + + + + 1. Optimize images—use WebP format and compress large files. + 2. Reduce the number of external scripts. + 3. Check for large code blocks or embedded content. + 4. Use the browser's Network tab to identify slow resources. + + + + 1. Ensure pages have descriptive titles and content. + 2. Check that pages aren't marked with `noindex`. + 3. Wait for the search index to update after changes (up to 24 hours). + 4. Verify the page isn't excluded by `.mintignore`. + + + +## Getting more help + +If you can't resolve your issue: + +1. **Check the [status page](https://status.mintlify.com)** for any ongoing incidents. +2. **Search existing issues** in the [GitHub discussions](https://github.com/mintlify/mint/discussions). +3. **Contact support** through your [Mintlify dashboard](https://dashboard.mintlify.com). + +When reporting issues, include: +- Your `docs.json` configuration (remove sensitive data) +- Error messages from `mint dev` or the dashboard +- Steps to reproduce the problem +- Browser and OS information From 25c765ec96c392fa7f52b3933277f0583345c542 Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Mon, 1 Dec 2025 21:43:19 +0000 Subject: [PATCH 08/34] Update guides/getting-started-tutorial.mdx --- guides/getting-started-tutorial.mdx | 366 ++++++++++++++++++++++++++++ 1 file changed, 366 insertions(+) create mode 100644 guides/getting-started-tutorial.mdx diff --git a/guides/getting-started-tutorial.mdx b/guides/getting-started-tutorial.mdx new file mode 100644 index 000000000..6c3fc60f7 --- /dev/null +++ b/guides/getting-started-tutorial.mdx @@ -0,0 +1,366 @@ +--- +title: "Getting started tutorial" +description: "Build your first documentation site with Mintlify in 15 minutes." +keywords: ["tutorial", "getting started", "first project", "beginner", "walkthrough"] +--- + +This hands-on tutorial walks you through creating a complete documentation site from scratch. By the end, you'll have a live site with custom branding, organized navigation, and interactive components. + + + **Time required**: 15 minutes + + **Prerequisites**: + - A [Mintlify account](https://mintlify.com/start) + - [Node.js](https://nodejs.org) v20.17.0 or higher + - A GitHub account + + +## What you'll build + +A documentation site for a fictional API called "Acme API" with: +- A branded homepage +- Getting started guide +- API reference section +- Interactive code examples + +## Step 1: Create your project + +Open your terminal and run: + +```bash +npm i -g mint +mint new acme-docs +cd acme-docs +``` + +Select the default template when prompted. This creates a project with: + +``` +acme-docs/ +├── docs.json # Site configuration +├── index.mdx # Homepage +├── quickstart.mdx # Getting started page +└── images/ # Image assets +``` + +## Step 2: Configure your site + +Open `docs.json` and update the basic settings: + +```json docs.json +{ + "$schema": "https://mintlify.com/docs.json", + "name": "Acme API", + "colors": { + "primary": "#0066FF", + "light": "#3399FF", + "dark": "#0044CC" + }, + "favicon": "/favicon.ico", + "navigation": { + "tabs": [ + { + "tab": "Documentation", + "groups": [ + { + "group": "Get started", + "pages": ["index", "quickstart"] + } + ] + } + ] + } +} +``` + +## Step 3: Create your homepage + +Replace the content in `index.mdx`: + +```mdx index.mdx +--- +title: "Acme API" +description: "Build powerful integrations with the Acme API." +--- + +Welcome to the Acme API documentation. Our API lets you integrate payment processing, user management, and analytics into your application. + + + + Get up and running in 5 minutes. + + + Explore all available endpoints. + + + +## Features + + + + Process payments securely with our PCI-compliant API. + + + Manage user accounts and authentication. + + + Track usage and generate reports. + + +``` + +## Step 4: Write a quickstart guide + +Update `quickstart.mdx` with a practical getting started guide: + +```mdx quickstart.mdx +--- +title: "Quickstart" +description: "Start using the Acme API in 5 minutes." +--- + +This guide walks you through making your first API request. + +## Get your API key + + + + Create an account at [dashboard.acme.com](https://dashboard.acme.com). + + + Navigate to **Settings > API Keys** and click **Create Key**. + + + Copy the key and store it securely. You won't be able to see it again. + + + +## Make your first request + + +```bash cURL +curl -X GET "https://api.acme.com/v1/users" \ + -H "Authorization: Bearer YOUR_API_KEY" +``` + +```javascript Node.js +const response = await fetch('https://api.acme.com/v1/users', { + headers: { + 'Authorization': 'Bearer YOUR_API_KEY' + } +}); +const users = await response.json(); +``` + +```python Python +import requests + +response = requests.get( + 'https://api.acme.com/v1/users', + headers={'Authorization': 'Bearer YOUR_API_KEY'} +) +users = response.json() +``` + + +## Response + +A successful request returns: + +```json +{ + "users": [ + { + "id": "usr_123", + "email": "user@example.com", + "created_at": "2024-01-15T10:30:00Z" + } + ], + "total": 1 +} +``` + +## Next steps + + + + Learn about API authentication options. + + + Handle errors gracefully in your integration. + + +``` + +## Step 5: Add an API reference section + +Create a new folder and files for your API reference: + +```bash +mkdir api-reference +``` + +Create `api-reference/overview.mdx`: + +```mdx api-reference/overview.mdx +--- +title: "API overview" +description: "Learn the basics of the Acme API." +--- + +The Acme API is a RESTful API that uses JSON for request and response bodies. + +## Base URL + +All API requests should be made to: + +``` +https://api.acme.com/v1 +``` + +## Authentication + +Include your API key in the `Authorization` header: + +``` +Authorization: Bearer YOUR_API_KEY +``` + +## Rate limits + +| Plan | Requests per minute | +| ---------- | ------------------- | +| Free | 60 | +| Pro | 600 | +| Enterprise | Unlimited | + + + Rate limit headers are included in every response. Check `X-RateLimit-Remaining` to see your current usage. + +``` + +Create `api-reference/users.mdx`: + +```mdx api-reference/users.mdx +--- +title: "Users" +description: "Manage user accounts." +--- + +## List users + + + Page number for pagination. + + + + Number of users per page (max 100). + + + +```bash +curl -X GET "https://api.acme.com/v1/users?page=1&limit=20" \ + -H "Authorization: Bearer YOUR_API_KEY" +``` + + + +```json +{ + "users": [ + { + "id": "usr_123", + "email": "user@example.com", + "name": "Jane Doe", + "created_at": "2024-01-15T10:30:00Z" + } + ], + "pagination": { + "page": 1, + "limit": 20, + "total": 1 + } +} +``` + +``` + +## Step 6: Update navigation + +Add the new pages to your `docs.json`: + +```json docs.json {12-19} +{ + "$schema": "https://mintlify.com/docs.json", + "name": "Acme API", + "colors": { + "primary": "#0066FF", + "light": "#3399FF", + "dark": "#0044CC" + }, + "favicon": "/favicon.ico", + "navigation": { + "tabs": [ + { + "tab": "Documentation", + "groups": [ + { + "group": "Get started", + "pages": ["index", "quickstart"] + }, + { + "group": "API reference", + "pages": [ + "api-reference/overview", + "api-reference/users" + ] + } + ] + } + ] + } +} +``` + +## Step 7: Preview locally + +Start the development server: + +```bash +mint dev +``` + +Open [localhost:3000](http://localhost:3000) to see your documentation site. + +## Step 8: Deploy + +Push your code to GitHub and connect it to Mintlify: + +1. Create a new GitHub repository. +2. Push your code: + ```bash + git init + git add . + git commit -m "Initial documentation" + git remote add origin https://github.com/YOUR_USERNAME/acme-docs.git + git push -u origin main + ``` +3. In your [Mintlify dashboard](https://dashboard.mintlify.com), connect the repository. +4. Your site deploys automatically to `your-project.mintlify.app`. + +## What's next + + + + Add your own domain like docs.acme.com. + + + Customize colors, fonts, and styling. + + + Explore interactive components. + + + Generate API docs from OpenAPI specs. + + From 6b4a6e2b53105225035a55207da1b860f47c1d78 Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Mon, 1 Dec 2025 21:43:48 +0000 Subject: [PATCH 09/34] Update optimize/seo.mdx --- optimize/seo.mdx | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) diff --git a/optimize/seo.mdx b/optimize/seo.mdx index ca24f9cbd..a468cdf94 100644 --- a/optimize/seo.mdx +++ b/optimize/seo.mdx @@ -247,3 +247,20 @@ You can also specify `noindex` for all pages in your docs by setting the `metata - Use relevant images that support your content + +## Keyword research + +To increase organic traffic, invest time into understanding which keywords help users land on your documentation. + +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 into headings, subheadings, and body text. Don't overstuff keywords—your documentation should be written for your users, not search engines. + +## Page performance + +Use tools like [Google PageSpeed Insights](https://pagespeed.web.dev) to identify areas for technical SEO improvement. + +Advanced optimizations include: + +- **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. From 95a51949d82437a173676edc1d2a4f4113ad13e9 Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Mon, 1 Dec 2025 21:43:53 +0000 Subject: [PATCH 10/34] 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 e755192923036b0647a816661082ff91adccdf07 Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Mon, 1 Dec 2025 21:44:15 +0000 Subject: [PATCH 11/34] Update guides/glossary.mdx --- guides/glossary.mdx | 111 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 111 insertions(+) create mode 100644 guides/glossary.mdx diff --git a/guides/glossary.mdx b/guides/glossary.mdx new file mode 100644 index 000000000..b6ad19b98 --- /dev/null +++ b/guides/glossary.mdx @@ -0,0 +1,111 @@ +--- +title: "Glossary" +description: "Definitions of key terms used throughout Mintlify documentation." +keywords: ["glossary", "definitions", "terms", "terminology", "reference"] +--- + +A reference guide to common terms and concepts used in Mintlify documentation. + +## A + + + An interactive feature that lets users test API endpoints directly from your documentation. Supports OpenAPI and AsyncAPI specifications. + + + + A specification for defining asynchronous APIs, such as WebSocket or message queue-based APIs. Mintlify can generate documentation from AsyncAPI specs. + + +## C + + + The `mint` command-line tool used for local development, creating new projects, and validating documentation. Install with `npm i -g mint`. + + + + A reusable MDX element like ``, ``, or `` that adds interactivity and structure to your documentation pages. + + +## D + + + The main configuration file for your Mintlify documentation site. Controls navigation, theming, integrations, and site-wide settings. + + + + The process of publishing your documentation to a live URL. Mintlify automatically deploys when you push changes to your connected Git repository. + + +## F + + + YAML metadata at the top of MDX files, enclosed by `---`. Defines page properties like `title`, `description`, and custom meta tags. + + +## G + + + A navigation element that organizes related pages under a collapsible section in the sidebar. Defined in `docs.json`. + + +## H + + + A page that exists and is accessible via URL but doesn't appear in the navigation sidebar. Useful for unlisted content or special landing pages. + + +## M + + + A file format that combines Markdown with JSX, allowing you to use React components within Markdown content. All Mintlify pages use `.mdx` files. + + + + A `.mintignore` file that excludes specific files or directories from being published to your documentation site. Uses `.gitignore` syntax. + + +## N + + + The structure that defines how pages are organized in your documentation. Configured in `docs.json` using tabs, groups, and pages. + + +## O + + + A specification for describing RESTful APIs. Mintlify can automatically generate interactive API documentation from OpenAPI (formerly Swagger) specs. + + +## P + + + A temporary deployment created for pull requests, allowing you to review documentation changes before merging to production. + + +## R + + + A rule that automatically sends visitors from one URL to another. Configured in `docs.json` to handle moved or renamed pages. + + +## S + + + A reusable piece of content stored in the `snippets/` folder that can be imported into multiple pages. Useful for content that appears in several places. + + +## T + + + A top-level navigation element that creates separate sections in your documentation, each with its own groups and pages. + + + + The visual styling of your documentation site, including colors, fonts, and layout options. Configured in `docs.json`. + + +## V + + + A navigation feature that lets you maintain multiple versions of your documentation (e.g., v1, v2) with a version selector dropdown. + From bbe7d34f6c893b1977eec12ea04ef3060f03e6bc Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Mon, 1 Dec 2025 21:44:37 +0000 Subject: [PATCH 12/34] Update integrations/sdks/liblab.mdx --- integrations/sdks/liblab.mdx | 70 ++++++++++++++++++++++++++++++++++++ 1 file changed, 70 insertions(+) create mode 100644 integrations/sdks/liblab.mdx diff --git a/integrations/sdks/liblab.mdx b/integrations/sdks/liblab.mdx new file mode 100644 index 000000000..93ac2b56c --- /dev/null +++ b/integrations/sdks/liblab.mdx @@ -0,0 +1,70 @@ +--- +title: "liblab" +description: "Generate SDKs and sync documentation with liblab." +keywords: ["liblab", "SDK", "code generation", "API client"] +--- + +[liblab](https://liblab.com) generates type-safe SDKs from your OpenAPI specification and can automatically sync SDK documentation with your Mintlify docs. + +## Setup + + + + Sign up at [liblab.com](https://liblab.com) and create a new project. + + + Upload your OpenAPI spec and configure the languages you want to generate SDKs for. + + + liblab generates SDKs with full documentation, code samples, and type definitions. + + + Reference the generated SDK examples in your API documentation using code groups. + + + +## Adding SDK examples + +Once you have generated SDKs, add examples to your API documentation: + +```mdx + +```typescript TypeScript +import { AcmeClient } from 'acme-sdk'; + +const client = new AcmeClient({ apiKey: 'YOUR_API_KEY' }); +const users = await client.users.list(); +``` + +```python Python +from acme import AcmeClient + +client = AcmeClient(api_key="YOUR_API_KEY") +users = client.users.list() +``` + +```go Go +import "github.com/acme/acme-go" + +client := acme.NewClient("YOUR_API_KEY") +users, err := client.Users.List() +``` + +``` + +## Supported languages + +liblab supports generating SDKs for: + +- TypeScript/JavaScript +- Python +- Go +- Java +- C# +- Ruby +- PHP + +## Resources + +- [liblab documentation](https://developers.liblab.com) +- [SDK best practices](https://liblab.com/blog) From 80ee6e843da732893a8052b590c077e57a75c53f Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Mon, 1 Dec 2025 21:44:41 +0000 Subject: [PATCH 13/34] Update integrations/sdks/fern.mdx --- integrations/sdks/fern.mdx | 71 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 71 insertions(+) create mode 100644 integrations/sdks/fern.mdx diff --git a/integrations/sdks/fern.mdx b/integrations/sdks/fern.mdx new file mode 100644 index 000000000..240a6c95d --- /dev/null +++ b/integrations/sdks/fern.mdx @@ -0,0 +1,71 @@ +--- +title: "Fern" +description: "Generate SDKs and API documentation with Fern." +keywords: ["Fern", "SDK", "code generation", "API client"] +--- + +[Fern](https://buildwithfern.com) generates type-safe SDKs from your API definition and provides tools for maintaining consistent API documentation. + +## Setup + + + + ```bash + npm install -g fern-api + ``` + + + ```bash + fern init + ``` + This creates a `fern/` directory with your API definition. + + + Write your API definition in Fern's YAML format or import from OpenAPI. + + + ```bash + fern generate + ``` + + + +## Adding SDK examples to Mintlify + +Include Fern-generated SDK examples in your documentation: + +```mdx + +```typescript TypeScript +import { AcmeClient } from "@acme/sdk"; + +const client = new AcmeClient({ apiKey: "YOUR_API_KEY" }); + +const user = await client.users.get("user_123"); +``` + +```python Python +from acme import AcmeClient + +client = AcmeClient(api_key="YOUR_API_KEY") + +user = client.users.get("user_123") +``` + +``` + +## Supported languages + +Fern generates SDKs for: + +- TypeScript +- Python +- Go +- Java +- Ruby +- C# + +## Resources + +- [Fern documentation](https://buildwithfern.com/docs) +- [Fern GitHub](https://github.com/fern-api/fern) From 21383d0f5a5a2d54cb291cc8d779b6abaf37074d Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Mon, 1 Dec 2025 21:44:53 +0000 Subject: [PATCH 14/34] Update integrations/privacy/onetrust.mdx --- integrations/privacy/onetrust.mdx | 62 +++++++++++++++++++++++++++++++ 1 file changed, 62 insertions(+) create mode 100644 integrations/privacy/onetrust.mdx diff --git a/integrations/privacy/onetrust.mdx b/integrations/privacy/onetrust.mdx new file mode 100644 index 000000000..57915a3c7 --- /dev/null +++ b/integrations/privacy/onetrust.mdx @@ -0,0 +1,62 @@ +--- +title: "OneTrust" +description: "Add OneTrust cookie consent to your documentation." +keywords: ["OneTrust", "privacy", "cookies", "consent", "GDPR", "CCPA"] +--- + +[OneTrust](https://www.onetrust.com) provides cookie consent management to help you comply with GDPR, CCPA, and other privacy regulations. + +## Setup + + + + Log in to your OneTrust account and navigate to **Cookie Compliance > Scripts**. Copy your domain-specific script tag. + + + Add the OneTrust script to your `docs.json` configuration: + + ```json docs.json + { + "head": [ + "", + "" + ] + } + ``` + + Replace `YOUR-DOMAIN-ID` with your OneTrust domain script ID. + + + In your OneTrust dashboard, configure cookie categories and assign your analytics and tracking scripts to the appropriate categories. + + + +## Blocking scripts until consent + +To block analytics scripts until users provide consent, wrap them with OneTrust's consent mechanism: + +```json docs.json +{ + "head": [ + "" + ] +} +``` + +Common category IDs: +- `C0001` - Strictly necessary cookies +- `C0002` - Performance cookies +- `C0003` - Functional cookies +- `C0004` - Targeting cookies + +## Testing + +1. Clear your browser cookies. +2. Visit your documentation site. +3. Verify the consent banner appears. +4. Check that analytics only fire after consent is given. + +## Resources + +- [OneTrust documentation](https://my.onetrust.com/s/topic/0TO1Q000000ItRyWAK/cookie-compliance) +- [OneTrust developer portal](https://developer.onetrust.com) From 1b2f4e5b3e648c4d2ee94a2f3ae28d4da5b51f59 Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Mon, 1 Dec 2025 21:44:59 +0000 Subject: [PATCH 15/34] Update integrations/privacy/cookiebot.mdx --- integrations/privacy/cookiebot.mdx | 74 ++++++++++++++++++++++++++++++ 1 file changed, 74 insertions(+) create mode 100644 integrations/privacy/cookiebot.mdx diff --git a/integrations/privacy/cookiebot.mdx b/integrations/privacy/cookiebot.mdx new file mode 100644 index 000000000..34bd1d251 --- /dev/null +++ b/integrations/privacy/cookiebot.mdx @@ -0,0 +1,74 @@ +--- +title: "Cookiebot" +description: "Add Cookiebot cookie consent to your documentation." +keywords: ["Cookiebot", "privacy", "cookies", "consent", "GDPR", "CCPA"] +--- + +[Cookiebot](https://www.cookiebot.com) provides automated cookie consent management and compliance scanning for GDPR, CCPA, and other privacy regulations. + +## Setup + + + + Sign up at [cookiebot.com](https://www.cookiebot.com) and add your documentation domain. + + + Find your Cookiebot ID (CBID) in your Cookiebot dashboard under **Settings > Your scripts**. + + + Add the Cookiebot script to your `docs.json`: + + ```json docs.json + { + "head": [ + "" + ] + } + ``` + + Replace `YOUR-COOKIEBOT-ID` with your actual Cookiebot ID. + + + +## Blocking mode + +Cookiebot supports different blocking modes: + +| Mode | Description | +| ---- | ----------- | +| `auto` | Automatically blocks cookies until consent (recommended) | +| `manual` | Requires manual tagging of scripts | + +For automatic blocking, use `data-blockingmode="auto"`. + +## Manual script blocking + +For more control, manually tag scripts with consent categories: + +```html + +``` + +Consent categories: +- `necessary` - Always allowed +- `preferences` - Functionality cookies +- `statistics` - Analytics cookies +- `marketing` - Advertising cookies + +## Customizing the banner + +Customize the consent banner appearance in your Cookiebot dashboard under **Dialog > Layout and design**. + +## Testing + +1. Use Cookiebot's preview mode to test without affecting live users. +2. Verify the banner appears on first visit. +3. Check that blocked scripts only run after consent. +4. Test the "withdraw consent" functionality. + +## Resources + +- [Cookiebot documentation](https://www.cookiebot.com/en/help/) +- [Cookiebot developer docs](https://www.cookiebot.com/en/developer/) From 0331b99030674ff7006374a8933827fa0f68b301 Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Mon, 1 Dec 2025 21:45:22 +0000 Subject: [PATCH 16/34] Update guides/migrating-from-readme.mdx --- guides/migrating-from-readme.mdx | 197 +++++++++++++++++++++++++++++++ 1 file changed, 197 insertions(+) create mode 100644 guides/migrating-from-readme.mdx diff --git a/guides/migrating-from-readme.mdx b/guides/migrating-from-readme.mdx new file mode 100644 index 000000000..8a15f35c8 --- /dev/null +++ b/guides/migrating-from-readme.mdx @@ -0,0 +1,197 @@ +--- +title: "Migrating from ReadMe" +description: "Move your documentation from ReadMe to Mintlify." +keywords: ["migration", "ReadMe", "import", "switch"] +--- + +This guide walks you through migrating your documentation from ReadMe to Mintlify. + +## Before you start + + + **Estimated time**: 1-2 hours depending on documentation size. + + +Gather the following from your ReadMe project: +- Exported Markdown files +- Images and media assets +- API specification files (OpenAPI/Swagger) +- Custom CSS or branding assets + +## Step 1: Export from ReadMe + + + + In ReadMe, go to **Project Settings > Project > Export**. Download your documentation as Markdown files. + + + If you have API documentation, export your OpenAPI specification from **API Reference > Export**. + + + Download any images or files hosted on ReadMe that you want to keep. + + + +## Step 2: Create your Mintlify project + +```bash +npm i -g mint +mint new my-docs +cd my-docs +``` + +## Step 3: Convert content + +### Page structure + +ReadMe pages typically have frontmatter like: + +```markdown +--- +title: "Getting Started" +slug: "getting-started" +excerpt: "Learn how to get started" +hidden: false +--- +``` + +Convert to Mintlify format: + +```mdx +--- +title: "Getting started" +description: "Learn how to get started" +--- +``` + +### Callouts + +ReadMe callouts: +```markdown +> 📘 Note +> This is a note. + +> 🚧 Warning +> This is a warning. +``` + +Mintlify callouts: +```mdx + + This is a note. + + + + This is a warning. + +``` + +### Code blocks + +ReadMe code blocks work the same in Mintlify. For tabbed code examples: + +```mdx + +```javascript JavaScript +const example = "code"; +``` + +```python Python +example = "code" +``` + +``` + +### Images + +Move images to the `/images` folder and update paths: + +```mdx +![Alt text](/images/screenshot.png) +``` + +Or use the Frame component for better styling: + +```mdx + + Alt text + +``` + +## Step 4: Set up navigation + +Map your ReadMe categories to Mintlify navigation in `docs.json`: + +```json +{ + "navigation": { + "groups": [ + { + "group": "Getting started", + "pages": ["introduction", "quickstart"] + }, + { + "group": "Guides", + "pages": ["guides/authentication", "guides/errors"] + } + ] + } +} +``` + +## Step 5: Configure API documentation + +If you have OpenAPI documentation: + +1. Place your OpenAPI file in your docs folder (e.g., `openapi.json`) +2. Reference it in `docs.json`: + +```json +{ + "api": { + "openapi": "openapi.json" + } +} +``` + +## Step 6: Set up redirects + +Add redirects for your old ReadMe URLs: + +```json docs.json +{ + "redirects": [ + { + "source": "/docs/getting-started", + "destination": "/quickstart" + }, + { + "source": "/reference/:slug", + "destination": "/api-reference/:slug" + } + ] +} +``` + +## Feature mapping + +| ReadMe feature | Mintlify equivalent | +| -------------- | ------------------- | +| Categories | Groups | +| Pages | MDX files | +| Callouts | ``, ``, ``, `` | +| Code blocks | Code blocks with language tags | +| API Reference | OpenAPI integration | +| Custom CSS | Theme configuration + custom scripts | +| Variables | Snippets | + +## Next steps + + + + Match your brand colors and styling. + + + Point your docs domain to Mintlify. + + From d7e95c5b4289899e47d1bf208ecdc3e58a833c3e Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Mon, 1 Dec 2025 21:45:36 +0000 Subject: [PATCH 17/34] Update guides/migrating-from-gitbook.mdx --- guides/migrating-from-gitbook.mdx | 241 ++++++++++++++++++++++++++++++ 1 file changed, 241 insertions(+) create mode 100644 guides/migrating-from-gitbook.mdx diff --git a/guides/migrating-from-gitbook.mdx b/guides/migrating-from-gitbook.mdx new file mode 100644 index 000000000..9621c7c7b --- /dev/null +++ b/guides/migrating-from-gitbook.mdx @@ -0,0 +1,241 @@ +--- +title: "Migrating from GitBook" +description: "Move your documentation from GitBook to Mintlify." +keywords: ["migration", "GitBook", "import", "switch"] +--- + +This guide walks you through migrating your documentation from GitBook to Mintlify. + +## Before you start + + + **Estimated time**: 1-2 hours depending on documentation size. + + +Gather the following from your GitBook space: +- Exported Markdown files +- Images and media assets +- Any custom integrations or embeds + +## Step 1: Export from GitBook + + + + In GitBook, go to your space settings and find the export option. GitBook allows exporting to Markdown or PDF. + + + Choose Markdown export to get files compatible with Mintlify. + + + Download any images or files that aren't included in the export. + + + +## Step 2: Create your Mintlify project + +```bash +npm i -g mint +mint new my-docs +cd my-docs +``` + +## Step 3: Convert content + +### Page structure + +GitBook pages may have frontmatter like: + +```markdown +--- +description: Page description here +--- + +# Page Title + +Content here... +``` + +Convert to Mintlify format: + +```mdx +--- +title: "Page title" +description: "Page description here" +--- + +Content here... +``` + +### Hints and callouts + +GitBook hints: +```markdown +{% hint style="info" %} +This is an info hint. +{% endhint %} + +{% hint style="warning" %} +This is a warning. +{% endhint %} +``` + +Mintlify callouts: +```mdx + + This is an info hint. + + + + This is a warning. + +``` + +### Tabs + +GitBook tabs: +```markdown +{% tabs %} +{% tab title="JavaScript" %} +```javascript +const example = "code"; +``` +{% endtab %} +{% tab title="Python" %} +```python +example = "code" +``` +{% endtab %} +{% endtabs %} +``` + +Mintlify tabs: +```mdx + + + ```javascript + const example = "code"; + ``` + + + ```python + example = "code" + ``` + + +``` + +### Expandable sections + +GitBook expandable: +```markdown +
+Click to expand +Hidden content here. +
+``` + +Mintlify accordion: +```mdx + + Hidden content here. + +``` + +### Images + +Move images to `/images` and update paths: + +```mdx + + Description + +``` + +## Step 4: Set up navigation + +Map your GitBook structure to Mintlify navigation: + +```json docs.json +{ + "navigation": { + "groups": [ + { + "group": "Overview", + "pages": ["index", "quickstart"] + }, + { + "group": "Guides", + "pages": [ + "guides/getting-started", + "guides/configuration" + ] + } + ] + } +} +``` + +## Step 5: Handle GitBook-specific features + +### Page links + +GitBook internal links: +```markdown +[Link text](../other-page.md) +``` + +Mintlify internal links: +```mdx +[Link text](/other-page) +``` + +### Embeds + +Replace GitBook embeds with Mintlify equivalents or iframe embeds: + +```mdx +