diff --git a/docs.json b/docs.json index e368f6a4f..f2907e068 100644 --- a/docs.json +++ b/docs.json @@ -195,6 +195,8 @@ { "group": "SDKs", "pages": [ + "integrations/sdks/fern", + "integrations/sdks/liblab", "integrations/sdks/speakeasy", "integrations/sdks/stainless" ] @@ -211,6 +213,8 @@ "group": "Privacy", "pages": [ "integrations/privacy/overview", + "integrations/privacy/cookiebot", + "integrations/privacy/onetrust", "integrations/privacy/osano" ] } @@ -236,10 +240,14 @@ ] }, { - "group": "API docs", + "group": "Migrations", "icon": "file-json", "pages": [ - "guides/migrating-from-mdx" + "guides/getting-started-tutorial", + "guides/migrating-from-mdx", + "guides/migrating-from-readme", + "guides/migrating-from-gitbook", + "guides/migrating-from-docusaurus" ] }, { @@ -248,12 +256,13 @@ "pages": [ "guides/accessibility", "guides/content-types", + "guides/glossary", "guides/improving-docs", "guides/maintenance", "guides/media", "guides/navigation", - "guides/seo", "guides/style-and-tone", + "guides/troubleshooting", "guides/understand-your-audience" ] }, @@ -343,7 +352,8 @@ "fr/organize/settings", "fr/organize/navigation", "fr/organize/pages", - "fr/organize/hidden-pages" + "fr/organize/hidden-pages", + "fr/organize/mintignore" ] }, { @@ -384,6 +394,7 @@ "fr/components/callouts", "fr/components/cards", "fr/components/code-groups", + "fr/components/color", "fr/components/columns", "fr/components/examples", "fr/components/expandables", @@ -553,7 +564,6 @@ "fr/guides/maintenance", "fr/guides/media", "fr/guides/navigation", - "fr/guides/seo", "fr/guides/style-and-tone", "fr/guides/understand-your-audience" ] @@ -644,7 +654,8 @@ "es/organize/settings", "es/organize/navigation", "es/organize/pages", - "es/organize/hidden-pages" + "es/organize/hidden-pages", + "es/organize/mintignore" ] }, { @@ -685,6 +696,7 @@ "es/components/callouts", "es/components/cards", "es/components/code-groups", + "es/components/color", "es/components/columns", "es/components/examples", "es/components/expandables", @@ -854,7 +866,6 @@ "es/guides/maintenance", "es/guides/media", "es/guides/navigation", - "es/guides/seo", "es/guides/style-and-tone", "es/guides/understand-your-audience" ] @@ -945,7 +956,8 @@ "zh/organize/settings", "zh/organize/navigation", "zh/organize/pages", - "zh/organize/hidden-pages" + "zh/organize/hidden-pages", + "zh/organize/mintignore" ] }, { @@ -986,6 +998,7 @@ "zh/components/callouts", "zh/components/cards", "zh/components/code-groups", + "zh/components/color", "zh/components/columns", "zh/components/examples", "zh/components/expandables", @@ -1155,7 +1168,6 @@ "zh/guides/maintenance", "zh/guides/media", "zh/guides/navigation", - "zh/guides/seo", "zh/guides/style-and-tone", "zh/guides/understand-your-audience" ] 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. + 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 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) | 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. + 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 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) | 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. + + 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. + diff --git a/guides/migrating-from-docusaurus.mdx b/guides/migrating-from-docusaurus.mdx new file mode 100644 index 000000000..37431d2ab --- /dev/null +++ b/guides/migrating-from-docusaurus.mdx @@ -0,0 +1,275 @@ +--- +title: "Migrating from Docusaurus" +description: "Move your documentation from Docusaurus to Mintlify." +keywords: ["migration", "Docusaurus", "import", "switch", "React"] +--- + +This guide walks you through migrating your documentation from Docusaurus to Mintlify. + +## Before you start + + + **Estimated time**: 2-4 hours depending on customization level. + + +Gather the following from your Docusaurus project: +- All MDX/Markdown files from `/docs` +- Static assets from `/static` +- Sidebar configuration from `sidebars.js` +- Theme customizations from `docusaurus.config.js` + +## Step 1: Create your Mintlify project + +```bash +npm i -g mint +mint new my-docs +cd my-docs +``` + +## Step 2: Copy content files + +Copy your Docusaurus docs to your Mintlify project: + +```bash +cp -r ../docusaurus-project/docs/* . +cp -r ../docusaurus-project/static/img ./images +``` + +## Step 3: Convert frontmatter + +Docusaurus frontmatter: +```markdown +--- +id: intro +title: Introduction +sidebar_label: Intro +sidebar_position: 1 +slug: / +--- +``` + +Mintlify frontmatter: +```mdx +--- +title: "Introduction" +description: "Welcome to our documentation." +--- +``` + +Remove Docusaurus-specific fields like `id`, `sidebar_label`, `sidebar_position`, and `slug`. + +## Step 4: Convert components + +### Admonitions + +Docusaurus admonitions: +```markdown +:::note +This is a note. +::: + +:::tip +This is a tip. +::: + +:::warning +This is a warning. +::: + +:::danger +This is dangerous. +::: +``` + +Mintlify callouts: +```mdx + + This is a note. + + + + This is a tip. + + + + This is a warning. + + + + This is dangerous. + +``` + +### Tabs + +Docusaurus tabs: +```jsx +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + + + + ```js + const x = 1; + ``` + + + ```python + x = 1 + ``` + + +``` + +Mintlify tabs: +```mdx + + + ```js + const x = 1; + ``` + + + ```python + x = 1 + ``` + + +``` + +### Code blocks + +Docusaurus code block with title: +```markdown +```js title="example.js" +const x = 1; +``` +``` + +Mintlify code block: +```markdown +```js example.js +const x = 1; +``` +``` + +### Details/Accordion + +Docusaurus details: +```jsx +
+ Click to expand + Hidden content. +
+``` + +Mintlify accordion: +```mdx + + Hidden content. + +``` + +## Step 5: Convert sidebar to navigation + +Docusaurus `sidebars.js`: +```javascript +module.exports = { + docs: [ + 'intro', + { + type: 'category', + label: 'Getting Started', + items: ['installation', 'configuration'], + }, + ], +}; +``` + +Mintlify `docs.json`: +```json +{ + "navigation": { + "groups": [ + { + "group": "Overview", + "pages": ["intro"] + }, + { + "group": "Getting started", + "pages": ["installation", "configuration"] + } + ] + } +} +``` + +## Step 6: Update image paths + +Docusaurus image paths: +```markdown +![Alt text](/img/screenshot.png) +``` + +Mintlify image paths: +```mdx +![Alt text](/images/screenshot.png) +``` + +Or with Frame component: +```mdx + + Alt text + +``` + +## Step 7: Handle custom React components + +If you have custom React components, you have two options: + +1. **Convert to MDX components**: Use Mintlify's built-in components where possible. +2. **Use custom React components**: Mintlify supports [custom React components](/customize/react-components) for advanced use cases. + +## Step 8: Configure theme + +Map your Docusaurus theme to Mintlify: + +```json docs.json +{ + "name": "Your Docs", + "colors": { + "primary": "#3578e5", + "light": "#6ba1ff", + "dark": "#1a4b8c" + }, + "logo": { + "light": "/images/logo-light.svg", + "dark": "/images/logo-dark.svg" + } +} +``` + +## Feature mapping + +| Docusaurus feature | Mintlify equivalent | +| ------------------ | ------------------- | +| Sidebar categories | Groups | +| Admonitions | Callout components | +| Tabs | `` component | +| Code blocks | Code blocks (same syntax) | +| MDX | MDX (same format) | +| Versioning | Versions in navigation | +| i18n | Languages in navigation | +| Search | Built-in search | +| Blog | Changelog | + +## Next steps + + + + Add custom React components. + + + Generate API documentation. + + 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 +