diff --git a/docs.json b/docs.json index 774209b12..2072f693a 100644 --- a/docs.json +++ b/docs.json @@ -91,7 +91,8 @@ "editor/pages", "editor/navigation", "editor/keyboard-shortcuts", - "editor/configurations" + "editor/configurations", + "editor/settings" ] }, "editor-classic", diff --git a/editor/settings.mdx b/editor/settings.mdx new file mode 100644 index 000000000..2ca7e515d --- /dev/null +++ b/editor/settings.mdx @@ -0,0 +1,126 @@ +--- +title: "Editor settings for AI and publishing" +description: "Configure AI instructions, commit and pull request guidance, draft pull requests, and the default merge method for the Mintlify web editor." +keywords: ["editor", "settings", "ai", "instructions", "publishing", "pull request", "commit", "draft", "merge"] +--- + +The web editor has two layers of settings: + +- **Your settings** apply only to you and control how the editor's AI assists with your edits. +- **Publishing settings** apply to everyone on a deployment and shape what happens when changes are committed and turned into pull requests. + +You can configure both from the **Settings** menu in the editor. + +## AI instructions + +AI instructions are persistent guidance that the editor sends to the AI alongside your request. Use them to capture style and tone rules you don't want to repeat every time, like voice, terminology, or formatting conventions. + +Your instructions apply to: + +- **Edit with AI** actions on a selection, such as rewrite, expand, or fix. +- **Agent sessions** started from the editor. + +Instructions are scoped to your user account, so each teammate maintains their own. + +### When to use AI instructions + +Add AI instructions when you find yourself repeating the same guidance in prompts, for example: + +- Enforcing second-person voice or sentence case headings. +- Preferring specific product names or terminology. +- Banning marketing language or filler phrases. +- Requiring certain components, like always using `` for callouts. + +Keep instructions short and specific. The AI follows them on every request, so vague or contradictory rules degrade results. + +### Configure AI instructions + +1. Open the editor and click your avatar in the toolbar. +2. Select **Settings**. +3. In the **AI instructions** field, enter the guidance you want the AI to follow. +4. Save your changes. + +Example: + +```text +- Use second person ("you") and active voice. +- Use sentence case for all headings. +- Refer to the product as "Acme" — never "Acme Inc." or "the platform". +- Wrap notes and warnings in or components. +- Do not add introductory filler like "In this guide" or "Let's explore". +``` + +Leave the field empty to remove your instructions. + +## Publishing settings + +Publishing settings are configured per deployment and apply to everyone who publishes from the editor. They control how pull requests and commits are generated, opened, and merged. + +You need admin access to your Mintlify deployment to change publishing settings. + +### Commit message instructions + +Commit message instructions guide the AI when it generates a commit message for a publish. The editor uses them whenever you publish without typing your own message. + +Use commit message instructions to match an existing convention in your repository, for example: + +- Conventional Commits (`docs(editor): ...`). +- A required ticket or issue prefix. +- A maximum subject length stricter than the 72-character default. + +Example: + +```text +Follow Conventional Commits. Use the "docs" type and an "editor" scope +for content changes (for example, "docs(editor): clarify quickstart steps"). +Keep the subject under 60 characters. +``` + +If your repository enforces a commit message regex, the editor still validates against it after generation. + +### Pull request instructions + +Pull request instructions guide the AI when it generates a pull request title and description. They apply whenever the editor opens a pull request on your behalf, including from **Create pull request** and **Merge and publish** flows. + +Use pull request instructions to standardize what reviewers see, for example: + +- Required sections like **Summary** and **Changes**. +- A description template that links to a tracking system. +- Tone or length requirements for titles. + +Example: + +```text +Title: imperative mood, under 70 characters, no trailing period. +Description: include a "## Summary" section (one sentence) and a +"## Changes" section as a bulleted list. Link any referenced page +using its relative path. +``` + +### Create pull requests as drafts by default + +Turn this on to have the editor open every new pull request in draft state. You can't merge a draft pull request until you mark it ready for review. This is useful when: + +- Your team requires a manual review pass before a pull request is open for approval. +- You want to share preview URLs without signaling that the change is ready to merge. + +You can still mark a pull request as ready for review from your Git provider. + +### Default merge method + +Choose how the editor merges pull requests when you click **Merge and publish**: + +- **Merge**: Creates a merge commit that preserves the full branch history. +- **Squash**: Combines all commits in the branch into a single commit on your deployment branch. +- **Rebase**: Replays each commit from the branch onto your deployment branch without a merge commit. + +The selected method is used by default. If you pass an explicit merge method through the API or your Git provider's UI, that choice takes precedence. + + + Match your default merge method to your Git provider's branch protection settings. If your deployment branch only allows squash merges, set the default to **Squash** to avoid failed merges from the editor. + + +## Related + +- [Branching and publishing](/editor/branching-and-publishing) +- [Configurations](/editor/configurations) diff --git a/es.json b/es.json index 00a899d88..d25811960 100644 --- a/es.json +++ b/es.json @@ -72,7 +72,8 @@ "es/editor/live-preview", "es/editor/collaborate", "es/editor/publish", - "es/editor/keyboard-shortcuts" + "es/editor/keyboard-shortcuts", + "es/editor/settings" ] }, "es/create/text", diff --git a/es/editor/settings.mdx b/es/editor/settings.mdx new file mode 100644 index 000000000..bfc0a2c42 --- /dev/null +++ b/es/editor/settings.mdx @@ -0,0 +1,144 @@ +--- +title: "Configuración del editor para IA y publicación" +description: "Configura las instrucciones de IA, las pautas para commits y pull requests, los pull requests en borrador y el método de fusión predeterminado del editor web de Mintlify." +keywords: ["editor", "configuración", "ai", "instrucciones", "publicación", "pull request", "commit", "borrador", "fusión"] +--- + +El editor web tiene dos capas de configuración: + +- **Tu configuración** se aplica solo a ti y controla cómo la IA del editor te ayuda con tus ediciones. +- **La configuración de publicación** se aplica a todos los miembros de un deployment y determina qué sucede cuando los cambios se confirman y se convierten en pull requests. + +Puedes configurar ambas desde el menú **Settings** en el editor. + +
+ ## Instrucciones de IA +
+ +Las instrucciones de IA son pautas persistentes que el editor envía a la IA junto con tu solicitud. Úsalas para capturar reglas de estilo y tono que no quieres repetir cada vez, como la voz, la terminología o las convenciones de formato. + +Tus instrucciones se aplican a: + +- Acciones **Edit with AI** sobre una selección, como reescribir, ampliar o corregir. +- **Sesiones del agente** iniciadas desde el editor. + +Las instrucciones están asociadas a tu cuenta de usuario, por lo que cada compañero de equipo mantiene las suyas. + +
+ ### Cuándo usar las instrucciones de IA +
+ +Agrega instrucciones de IA cuando notes que repites las mismas pautas en los prompts, por ejemplo: + +- Obligar el uso de la segunda persona o encabezados en mayúscula inicial. +- Preferir nombres de producto o terminología específicos. +- Prohibir lenguaje de marketing o frases de relleno. +- Exigir ciertos componentes, como usar siempre `` para los avisos. + +Mantén las instrucciones cortas y específicas. La IA las sigue en cada solicitud, así que las reglas vagas o contradictorias degradan los resultados. + +
+ ### Configurar las instrucciones de IA +
+ +1. Abre el editor y haz clic en tu avatar en la barra de herramientas. +2. Selecciona **Settings**. +3. En el campo **AI instructions**, introduce las pautas que quieres que siga la IA. +4. Guarda los cambios. + +Ejemplo: + +```text +- Use second person ("you") and active voice. +- Use sentence case for all headings. +- Refer to the product as "Acme" — never "Acme Inc." or "the platform". +- Wrap notes and warnings in or components. +- Do not add introductory filler like "In this guide" or "Let's explore". +``` + +Deja el campo vacío para eliminar tus instrucciones. + +
+ ## Configuración de publicación +
+ +La configuración de publicación se establece por deployment y se aplica a todas las personas que publican desde el editor. Controla cómo se generan, se abren y se fusionan los pull requests y los commits. + +Necesitas acceso de administrador a tu deployment de Mintlify para cambiar la configuración de publicación. + +
+ ### Instrucciones para el mensaje de commit +
+ +Las instrucciones para el mensaje de commit guían a la IA cuando genera un mensaje de commit para una publicación. El editor las usa siempre que publicas sin escribir tu propio mensaje. + +Usa las instrucciones para el mensaje de commit para que coincidan con una convención existente en tu repositorio, por ejemplo: + +- Conventional Commits (`docs(editor): ...`). +- Un prefijo obligatorio de ticket o de issue. +- Una longitud máxima del asunto más estricta que el valor predeterminado de 72 caracteres. + +Ejemplo: + +```text +Follow Conventional Commits. Use the "docs" type and an "editor" scope +for content changes (for example, "docs(editor): clarify quickstart steps"). +Keep the subject under 60 characters. +``` + +Si tu repositorio aplica una expresión regular al mensaje de commit, el editor sigue validándola después de la generación. + +
+ ### Instrucciones para el pull request +
+ +Las instrucciones para el pull request guían a la IA cuando genera el título y la descripción de un pull request. Se aplican siempre que el editor abre un pull request en tu nombre, incluyendo los flujos **Create pull request** y **Merge and publish**. + +Usa las instrucciones para el pull request para estandarizar lo que ven los revisores, por ejemplo: + +- Secciones obligatorias como **Summary** y **Changes**. +- Una plantilla de descripción que enlace con un sistema de seguimiento. +- Requisitos de tono o de longitud para los títulos. + +Ejemplo: + +```text +Title: imperative mood, under 70 characters, no trailing period. +Description: include a "## Summary" section (one sentence) and a +"## Changes" section as a bulleted list. Link any referenced page +using its relative path. +``` + +
+ ### Crear pull requests como borradores por defecto +
+ +Activa esta opción para que el editor abra todos los pull requests nuevos en estado de borrador. No puedes fusionar un pull request en borrador hasta que lo marques como listo para revisión. Esto es útil cuando: + +- Tu equipo requiere una revisión manual antes de abrir el pull request para aprobación. +- Quieres compartir URLs de vista previa sin indicar que el cambio está listo para fusionarse. + +Todavía puedes marcar un pull request como listo para revisión desde tu proveedor de Git. + +
+ ### Método de fusión predeterminado +
+ +Elige cómo fusiona el editor los pull requests cuando haces clic en **Merge and publish**: + +- **Merge**: Crea un commit de fusión que preserva el historial completo de la rama. +- **Squash**: Combina todos los commits de la rama en un único commit en tu rama de deployment. +- **Rebase**: Reproduce cada commit de la rama sobre tu rama de deployment sin crear un commit de fusión. + +El método seleccionado se usa por defecto. Si pasas un método de fusión explícito a través de la API o de la interfaz de tu proveedor de Git, esa elección tiene prioridad. + + + Ajusta tu método de fusión predeterminado a las reglas de protección de ramas de tu proveedor de Git. Si tu rama de deployment solo permite fusiones tipo squash, configura el valor predeterminado en **Squash** para evitar fusiones fallidas desde el editor. + + + + +- [Publicación](/es/editor/publish) +- [Configuraciones](/es/editor/configurations) diff --git a/fr.json b/fr.json index 7d1a174b9..9156ba872 100644 --- a/fr.json +++ b/fr.json @@ -72,7 +72,8 @@ "fr/editor/live-preview", "fr/editor/collaborate", "fr/editor/publish", - "fr/editor/keyboard-shortcuts" + "fr/editor/keyboard-shortcuts", + "fr/editor/settings" ] }, "fr/create/text", diff --git a/fr/editor/settings.mdx b/fr/editor/settings.mdx new file mode 100644 index 000000000..3de26848b --- /dev/null +++ b/fr/editor/settings.mdx @@ -0,0 +1,144 @@ +--- +title: "Paramètres de l'éditeur pour l'IA et la publication" +description: "Configurez les instructions d'IA, les consignes pour les commits et les pull requests, les pull requests en brouillon et la méthode de fusion par défaut de l'éditeur web Mintlify." +keywords: ["éditeur", "paramètres", "ai", "instructions", "publication", "pull request", "commit", "brouillon", "fusion"] +--- + +L'éditeur web comporte deux niveaux de paramètres : + +- **Vos paramètres** ne s'appliquent qu'à vous et contrôlent la façon dont l'IA de l'éditeur vous assiste pendant vos modifications. +- **Les paramètres de publication** s'appliquent à toutes les personnes d'un déploiement et déterminent ce qui se passe lorsque les modifications sont committées puis transformées en pull requests. + +Vous pouvez configurer les deux depuis le menu **Settings** de l'éditeur. + +
+ ## Instructions d'IA +
+ +Les instructions d'IA sont des consignes persistantes que l'éditeur envoie à l'IA avec votre requête. Utilisez-les pour fixer des règles de style et de ton que vous ne voulez pas répéter à chaque fois, comme la voix, la terminologie ou les conventions de mise en forme. + +Vos instructions s'appliquent à : + +- Les actions **Edit with AI** sur une sélection, comme réécrire, développer ou corriger. +- Les **sessions de l'agent** lancées depuis l'éditeur. + +Les instructions sont liées à votre compte utilisateur, donc chaque membre de l'équipe gère les siennes. + +
+ ### Quand utiliser les instructions d'IA +
+ +Ajoutez des instructions d'IA lorsque vous vous surprenez à répéter les mêmes consignes dans vos prompts, par exemple : + +- Imposer la deuxième personne ou des titres en majuscule initiale uniquement. +- Privilégier des noms de produit ou une terminologie spécifiques. +- Bannir le langage marketing ou les phrases de remplissage. +- Exiger certains composants, comme toujours utiliser `` pour les encarts. + +Gardez les instructions courtes et précises. L'IA les suit à chaque requête, donc des règles vagues ou contradictoires dégradent les résultats. + +
+ ### Configurer les instructions d'IA +
+ +1. Ouvrez l'éditeur et cliquez sur votre avatar dans la barre d'outils. +2. Sélectionnez **Settings**. +3. Dans le champ **AI instructions**, saisissez les consignes que l'IA doit suivre. +4. Enregistrez vos modifications. + +Exemple : + +```text +- Use second person ("you") and active voice. +- Use sentence case for all headings. +- Refer to the product as "Acme" — never "Acme Inc." or "the platform". +- Wrap notes and warnings in or components. +- Do not add introductory filler like "In this guide" or "Let's explore". +``` + +Laissez le champ vide pour supprimer vos instructions. + +
+ ## Paramètres de publication +
+ +Les paramètres de publication se configurent par déploiement et s'appliquent à toutes les personnes qui publient depuis l'éditeur. Ils contrôlent la façon dont les pull requests et les commits sont générés, ouverts et fusionnés. + +Vous devez disposer d'un accès administrateur à votre déploiement Mintlify pour modifier les paramètres de publication. + +
+ ### Instructions pour le message de commit +
+ +Les instructions pour le message de commit guident l'IA lorsqu'elle génère un message de commit pour une publication. L'éditeur les utilise dès que vous publiez sans saisir votre propre message. + +Utilisez les instructions pour le message de commit afin de respecter une convention existante dans votre dépôt, par exemple : + +- Conventional Commits (`docs(editor): ...`). +- Un préfixe de ticket ou d'issue obligatoire. +- Une longueur maximale d'objet plus stricte que les 72 caractères par défaut. + +Exemple : + +```text +Follow Conventional Commits. Use the "docs" type and an "editor" scope +for content changes (for example, "docs(editor): clarify quickstart steps"). +Keep the subject under 60 characters. +``` + +Si votre dépôt impose une expression régulière sur le message de commit, l'éditeur la valide quand même après la génération. + +
+ ### Instructions pour la pull request +
+ +Les instructions pour la pull request guident l'IA lorsqu'elle génère le titre et la description d'une pull request. Elles s'appliquent dès que l'éditeur ouvre une pull request en votre nom, y compris dans les flux **Create pull request** et **Merge and publish**. + +Utilisez les instructions pour la pull request afin de standardiser ce que voient les relecteurs, par exemple : + +- Des sections obligatoires comme **Summary** et **Changes**. +- Un modèle de description qui renvoie vers un système de suivi. +- Des exigences de ton ou de longueur pour les titres. + +Exemple : + +```text +Title: imperative mood, under 70 characters, no trailing period. +Description: include a "## Summary" section (one sentence) and a +"## Changes" section as a bulleted list. Link any referenced page +using its relative path. +``` + +
+ ### Créer les pull requests en brouillon par défaut +
+ +Activez cette option pour que l'éditeur ouvre chaque nouvelle pull request à l'état de brouillon. Vous ne pouvez pas fusionner une pull request en brouillon avant de la marquer comme prête pour la relecture. C'est utile quand : + +- Votre équipe exige une relecture manuelle avant d'ouvrir la pull request pour approbation. +- Vous voulez partager les URLs de prévisualisation sans signaler que la modification est prête à être fusionnée. + +Vous pouvez toujours marquer une pull request comme prête pour la relecture depuis votre fournisseur Git. + +
+ ### Méthode de fusion par défaut +
+ +Choisissez la manière dont l'éditeur fusionne les pull requests lorsque vous cliquez sur **Merge and publish** : + +- **Merge** : Crée un commit de fusion qui conserve l'historique complet de la branche. +- **Squash** : Combine tous les commits de la branche en un seul commit sur votre branche de déploiement. +- **Rebase** : Rejoue chaque commit de la branche sur votre branche de déploiement, sans commit de fusion. + +La méthode sélectionnée est utilisée par défaut. Si vous passez une méthode de fusion explicite via l'API ou l'interface de votre fournisseur Git, ce choix prévaut. + + + Alignez votre méthode de fusion par défaut sur les règles de protection de branche de votre fournisseur Git. Si votre branche de déploiement n'autorise que les fusions squash, définissez la valeur par défaut sur **Squash** pour éviter les échecs de fusion depuis l'éditeur. + + + + +- [Publication](/fr/editor/publish) +- [Configurations](/fr/editor/configurations)