mirror of
https://github.com/mintlify/docs.git
synced 2026-09-14 13:35:46 +08:00
mintlify[bot]
85ed7ac0d4
* docs: add editor settings page for AI instructions and publishing * docs: refine editor settings SEO and add fr/es translations --------- Co-authored-by: mintlify[bot] <109931778+mintlify[bot]@users.noreply.github.com>
127 lines
5.2 KiB
Plaintext
127 lines
5.2 KiB
Plaintext
---
|
|
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 `<Note>` 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 <Note> or <Warning> 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.
|
|
|
|
<Tip>
|
|
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.
|
|
</Tip>
|
|
|
|
## Related
|
|
|
|
- [Branching and publishing](/editor/branching-and-publishing)
|
|
- [Configurations](/editor/configurations)
|