mirror of
https://github.com/mintlify/docs.git
synced 2026-09-14 13:35:46 +08:00
Ethan Palm
9a4ec7b557
* Fix editor docs accuracy, split media page, clear translation orphans
Accuracy fixes, each verified against mintlify/mint or mintlify/server:
- pages.mdx: "Editors and managers can restore them" -> "admins".
"Manager" is not a Mintlify role.
- index.mdx: publishing on a feature branch does not automatically open a
pull request; you choose commit-to-branch or PR. Contradicted the
branching page's own table.
- branching-and-publishing.mdx: preview deployments build when you open a
pull request, not on every branch save. Confirmed in gitlabWebhooks
(handleMergeRequestOpenEvent) and cruxWebhooks (keyed on reviewId).
tutorial.mdx was already correct.
- settings.mdx: rewritten against editor-settings-form.tsx. The panel has
four sections, not "two layers", and the entire Appearance section was
undocumented - including "Open live preview in new tab", which
live-preview.mdx already linked readers to. Corrected three setting
labels, noted that draft PRs default to on, added the 20,000-character
instruction limit.
- live-preview.mdx: link now resolves to /editor/settings#appearance.
De-bloat:
- Split the media section out of pages.mdx (172 lines, 15 subtopics) into
editor/media.mdx and added it to the nav.
- Trimmed index.mdx from 11 sidebar-duplicating cards to 4.
Translation orphans and redirects:
- Deleted 7 translated files whose English source was removed in April and
June. The translate automation never cleaned them up, and in PR #6062 it
wrote into es|fr|zh/editor/media.mdx 34 days after the English source was
deleted.
- Dropped /editor/media -> /editor/pages so it stops shadowing the
recreated page.
- Added /{es,fr,zh}/editor/publish, completing an English-only redirect.
- Added /editor/collaborate and its language variants. That page was
deleted in June with no redirect and has been a live 404 since.
mint broken-links clean, mint a11y clean, vale 0/0/0 on changed files.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
* Restructure editor docs: 14 pages to 9, cut UI description
The editor section had grown to 14 pages, about 40% of which described
things a user can see on screen. The ratio was 105 field-enumeration
bullets to 42 procedural steps.
New structure, organized around what is invisible rather than what is
on screen:
Overview absorbs git-essentials (concepts + the Git mapping table)
Tutorial unchanged
Edit content absorbs media and navigation
Publish branch mechanics, conflicts, git sync, commit signing
Review previews, pull requests, approve and merge
Collaborate comments + suggestions + real-time editing
Editor agent trimmed
Settings absorbs configurations as a pointer
Keyboard shortcuts unchanged
Removed: git-essentials, media, navigation, live-preview, comments,
suggestions, configurations, branching-and-publishing. Added: publish,
review, collaborate.
configurations.mdx was the clearest cut. It was a 193-line field-by-field
mirror of the Site configurations panel, which is a third rendering of
information already in the docs.json schema and in organize/settings-*
(2,694 lines). It is now a short section in settings.mdx covering only
what is specific to editing configuration from the editor: real-time
sync, the SVG logo constraint, and the redirects interface.
Also cut: block actions, the minimap, code block options, right-click
menu enumerations, page settings field lists (already delegated to
/organize/pages), and most screenshots of self-evident controls.
1,320 to 848 body lines. Field-enumeration bullets 105 to 29.
English redirects added for all eight removed pages. Language variants
deliberately omitted: es/fr/zh still carry the old structure, so
redirecting those paths now would shadow pages that still exist there.
The translation automation should mirror this restructure; verify
afterward that no orphans remain.
Vale vocabulary widened rather than reworded around: autocommit(s|ed|ing)?,
autosav(e|es|ed|ing), dotfile(s)?.
mint broken-links clean, mint a11y clean, vale 0 errors on editor/.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
* Correct keyboard shortcuts against the editor keymap
Verified every documented shortcut against the bindings in mintlify/mint
rather than inferring them. The app-level set is exhaustive:
mod+backslash, mod+i, mod+k, mod+s, mod+shift+period, mod+z, shift+mod+d,
shift+mod+s. Visual-mode bindings come from the Tiptap extensions.
- Cmd/Ctrl+Shift+F ("Switch between Navigation and Files tree") does not
exist. No such binding is registered anywhere in the dashboard. Replaced
with the real binding at that spot in the UI: Cmd/Ctrl+Shift+. toggles
"Show all files".
- Added Heading 5 and Heading 6. Heading.configure sets levels 1-6 and
preserves the parent Mod-Alt-N shortcuts; the table stopped at 4.
- Added Cmd/Ctrl+G for accordion group, bound in Accordions.tsx.
Confirmed correct and unchanged: Cmd+K search, Cmd+I agent, Cmd+Shift+S
mode toggle, Cmd+Shift+D diff, Cmd+\ sidebar, Cmd+Shift+M comment,
Cmd+Shift+E suggesting mode, Cmd+Shift+X strikethrough, Cmd+K link,
Cmd+Enter line break, Cmd+Shift+8 unordered list, and that source mode
runs Monaco.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
* Document auto publish, drop the deprecated deploy branch lock
Auto publish is available to all deployments, so the settings panel shows
"Auto publish" rather than "Main branch autocommits". It is not just a
rename: when it is on, the editor hides the branch selector and the
Publish button entirely (TopBar returns null for both), so there is no
pending state and no review step. Documented that behavior in
settings.mdx and added a note at the top of publish.mdx, since that page
otherwise assumes a publish step exists.
The deployment branch lock was deprecated and removed, so it stays out of
the docs. It was already dropped from settings.mdx in the restructure.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
* 💅
* copy edit index
* Fix editor docs I verified against dead code
Three claims traced to code that never mounts. Ethan confirmed the diff
shortcut does not work, which exposed the pattern.
- Removed Cmd/Ctrl+Shift+D for diff view. It is registered only at
SubBar/index.tsx:488, inside EditorSubBar, which is exported and
imported by nothing. There is no live diff shortcut; exitDiff exists
only as an onClick in EditorModeContextMenu.
- Source mode runs CodeMirror, not Monaco. SourceEditor resolves through
source-editor/index.tsx to editor-view.tsx, which imports
@codemirror/state and @codemirror/view. Monaco is used only by
EmbedModal. The shortcut rows themselves were correct: CodeMirror's
defaultKeymap and searchKeymap match VS Code for toggle comment, move
line, duplicate line, find, and add cursor above/below, all confirmed
against @codemirror/commands.
- Rewrote the left panel section of pages.mdx. The tabs are Home and
Publishing (EditorNavigationSidebarContents.tsx:62), not Navigation and
Files. The Navigation/Files switcher lives in the same dead SubBar
component. Home renders the workspace file tree including private
pages; Publishing renders the site navigation and site settings.
Confirmed by the e2e helper openPublishingNavigation, which queries the
Publishing tab by role against the running app.
Also corrected in that section: the tree hides docs.json, dotfiles,
extensionless files, all-caps Markdown, and css/js/jsx/mjs/cjs/pdf unless
Show all files is on; "unlisted" was an invented term, replaced with a
link to /organize/hidden-pages; and the folder menu item is "New page",
confirmed by e2e, not "New file".
Added four source-mode bindings that are real and undocumented: Cmd+B and
Cmd+I insert Markdown markers, Cmd+Option+Shift+[ and ] fold and unfold
all.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
* copy edit pages
* copy edit publish
* copy edit review
* copy edit settings
* copy edit collaborate
* Updated mintlify pages
- Updated quickstart.mdx
Mintlify-Source: dashboard-editor
* copy edit keyboard shortcuts
* Updated mintlify pages
- Updated quickstart.mdx
Mintlify-Source: dashboard-editor
* Revert "Updated mintlify pages"
This reverts commit 8d1b50cbfc.
* Updated mintlify pages
- Updated quickstart.mdx
Mintlify-Source: dashboard-editor
* fix editor edits
* Mirror the editor restructure into es, fr, and zh
Brings all three translated sites onto the same nine-page structure as
English instead of waiting for the translate automation, which has a
documented history of leaving orphans behind.
Content:
- Deleted 21 orphans: branching-and-publishing, comments, configurations,
git-essentials, live-preview, navigation, and suggestions in each
language. None had an English source after the restructure.
- Added publish, review, and collaborate in each language.
- Rewrote index, pages, settings, agent, and keyboard-shortcuts to match
the current English content, including Home/Publishing tabs, CodeMirror
source mode, Show all files, and the restored Appearance section.
- Kept the existing conventions: es uses usted, fr uses vous, keywords and
product UI labels stay in English, and every heading is wrapped in a
<div id="english-slug"> so cross-language anchors resolve. Verified that
every English anchor exists in all three languages.
Navigation and redirects:
- es.json, fr.json, and zh.json now list the same nine pages as docs.json.
- Removed six locale redirects that would have shadowed the new publish
and collaborate pages once they existed.
- Added 21 locale redirects for the removed pages and retargeted the
destinations that pointed at them.
- Retargeted four /editor/configurations redirects that pointed at
#site-configurations, an anchor dropped in the settings rewrite.
- Rewrote stale links in changelog, authentication-setup, concepts, and
glossary across all three languages, since broken-links does not follow
redirects.
English fixes needed first, all caused by the settings restructure:
- Restored ## Appearance. Two pages link to #appearance, and its four
preferences were otherwise undocumented.
- Restored ## Create draft pull requests by default, which changelog
links to and which defaults to on.
- Promoted Main branch autocommits from ### to ##; it was nested under PR
instructions, and its warning named a setting no longer on the page.
- Retargeted publish.mdx from the removed #auto-publish anchor.
- Fixed a missing space in the settings page intro.
mint broken-links clean, mint a11y clean (1042 files), vale 0 errors,
all five JSON files valid.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
Co-authored-by: mintlify[bot] <109931778+mintlify[bot]@users.noreply.github.com>
110 lines
6.6 KiB
Plaintext
110 lines
6.6 KiB
Plaintext
---
|
||
title: "核心概念"
|
||
description: "了解 Mintlify 如何连接你的组织、文档存储库、编辑工作流、部署以及 AI 功能。"
|
||
keywords: ["核心概念", "Mintlify 的工作原理", "存储库", "部署", "发布", "AI"]
|
||
---
|
||
|
||
Mintlify 会将 Git 存储库中的内容构建成一个文档站点。你可以在浏览器中的编辑器里工作，在本地开发环境中工作，或者在 Slack 中向 Mintlify agent 发送提示。这三种工作流都会更新同一个存储库。Mintlify 会将存储库中的内容构建为面向人类和 agent 的优化体验。
|
||
|
||
```mermaid
|
||
flowchart LR
|
||
Editors["Browser editors, local editors, and Mintlify agent"] --> Repo[("Documentation repository")]
|
||
Repo --> Build["Build and deployment"]
|
||
Build --> Site["Live documentation site"]
|
||
Site --> Readers["People"]
|
||
Site --> AI["AI agents"]
|
||
```
|
||
|
||
<div id="organizations-deployments-and-sites">
|
||
## 组织、部署和站点
|
||
</div>
|
||
|
||
**组织** (organization) 是你的团队的工作空间。它包含你的成员、组织级别的设置以及一个或多个部署。
|
||
|
||
**部署** (deployment) 是你组织中的一个文档项目。它将一个存储库、内容目录和部署分支连接到一个已发布的站点。一个组织可以为不同的产品或文档资产拥有多个部署。
|
||
|
||
**在线站点** (live site) 是一个部署所发布的产物。Mintlify 默认提供一个 `.mintlify.site` 的 URL。你可以为你的站点连接一个[自定义域名](/zh/customize/custom-domain)。站点包含你的内容、导航、搜索，以及你启用的任何功能，例如 AI 助手或 API playground。
|
||
|
||
<Note>
|
||
本文档有时会用 **project** 作为一个部署及其关联的存储库、配置和站点的通用名称。
|
||
</Note>
|
||
|
||
<div id="the-repository-is-the-source-of-truth">
|
||
## 存储库是权威信息源
|
||
</div>
|
||
|
||
你的文档存储库中包含定义站点的文件。Mintlify 会在每次构建时读取这些文件。
|
||
|
||
- **页面** (pages) 是 `.mdx` 文件。每个页面都包含内容和 frontmatter 元数据。
|
||
- `docs.json` 是必需的配置文件。它控制导航、外观、集成、API 设置以及其他站点级的行为。
|
||
- **资源** (assets) 包括页面中引用的图片、视频、字体和可下载文件。
|
||
- **API 规范** (API specifications) 可以基于 OpenAPI、AsyncAPI 或 GraphQL schema 生成 API 参考页面和交互式 playground。
|
||
- **可复用文件** (reusable files) 包括 snippets 和自定义 React 组件，页面可以导入使用。
|
||
|
||
你的存储库中可以包含未发布的文件。只有当你在 [`docs.json`](/zh/organize/navigation) 的导航中引用某个页面时，该页面才会出现在站点导航中，否则会被隐藏。[隐藏页面](/zh/organize/hidden-pages) 只能通过直接链接访问。
|
||
|
||
<div id="pages-and-navigation-are-separate">
|
||
## 页面和导航是分离的
|
||
</div>
|
||
|
||
**页面** (page) 提供某个 URL 上的内容。其 [frontmatter](/zh/organize/pages) 控制页面级的元数据和行为，包括标题、描述、图标和布局。
|
||
|
||
**导航** (navigation) 决定读者如何在页面之间浏览。你可以在 `docs.json` 文件中使用分组、标签、下拉菜单、产品、版本和语言等元素来配置导航。文件路径决定了页面是哪个，而它在 `docs.json` 中的位置决定了它在导航中的位置。
|
||
|
||
这种分离让你无需移动文件就能重新组织读者的浏览体验。它还允许你将某些工具类页面从导航中排除，同时保留通过 URL 访问的能力。
|
||
|
||
<div id="editing-and-publishing-are-different-stages">
|
||
## 编辑和发布是不同的阶段
|
||
</div>
|
||
|
||
你可以通过两种主要工作流来编辑同一份内容。
|
||
|
||
| 工作流 | 在哪里编辑 | 更改如何进入 Git | 如何预览 |
|
||
| --- | --- | --- | --- |
|
||
| Editor | 浏览器中的 Mintlify 控制台 | 编辑器会创建提交，并且可以打开拉取请求 | 在编辑器中实时预览 |
|
||
| 本地开发 | 你偏好的编辑器 | 你使用 Git 提交并推送 | `mint dev` CLI 命令 |
|
||
|
||
在编辑器中，更改会自动**保存**，但不会立即更新你的存储库或在线站点。当你**发布**时，编辑器会将更改写入 Git。之后发生的事情取决于你当前所在的分支和分支保护设置。
|
||
|
||
- 在**部署分支**上，发布可以直接触发在线站点的构建。
|
||
- 在**功能分支**上，发布可以将更改保存到该分支，或创建一个拉取请求以供审核。
|
||
- **预览部署**会将拉取请求渲染到一个临时 URL，以便审核者在合并前检查结果。
|
||
- 将拉取请求合并到部署分支会触发一次生产部署。
|
||
|
||
有关完整工作流，请参阅[分支与发布](/zh/editor/publish)。
|
||
|
||
<div id="a-build-turns-source-files-into-reader-experiences">
|
||
## 构建会将源文件转换为读者体验
|
||
</div>
|
||
|
||
当内容进入部署分支时，Mintlify 会校验项目、渲染页面并部署站点。相同的源内容支持多种查找和消费信息的方式：
|
||
|
||
- 文档站点会为桌面和移动端用户渲染页面。
|
||
- 搜索会为站点建立索引，让读者能够找到相关页面。
|
||
- AI 助手可以基于文档回答问题，并注明其信息来源。
|
||
- 页面的 Markdown 版本、`llms.txt` 和 `skill.md` 可以帮助 AI 工具理解内容。
|
||
- 一个公开的 MCP 服务器让兼容的 AI 工具能够将文档作为结构化上下文来检索。
|
||
|
||
在发布前运行 [`mint validate`](/zh/cli/commands#mint-validate) 和 [`mint broken-links`](/zh/cli/commands#mint-broken-links)，可以在本地捕获常见问题。
|
||
|
||
<div id="mintlifys-ai-features-have-different-roles">
|
||
## Mintlify 的 AI 功能各有不同的角色
|
||
</div>
|
||
|
||
Mintlify 为阅读、写作、自动化以及外部工具访问分别提供了不同的 AI 功能。
|
||
|
||
| 功能 | 使用者 | 用途 | 是否更改内容 |
|
||
| --- | --- | --- | --- |
|
||
| [Assistant](/zh/assistant) | 文档读者 | 基于你的内容回答问题 | 否 |
|
||
| [Agent](/zh/agent) | 文档维护者 | 研究并提出内容或配置更新建议 | 是 |
|
||
| [Automations](/zh/automations/index) | 文档维护者 | 按计划、存储库更新或集成事件运行 agent | 是 |
|
||
| [Search MCP server](/zh/ai/model-context-protocol) | Agents | 从单个已发布的文档站点检索上下文 | 否 |
|
||
| [Admin MCP server](/zh/ai/mintlify-mcp) | Agents | 通过经过认证的工具读取和更新部署 | 是 |
|
||
| [Mintlify Index](/zh/search-index) | Agents | 检索所有公开的 Mintlify 站点和网络上最新的技术上下文 | 否 |
|
||
|
||
<div id="learn-the-terminology">
|
||
## 了解术语
|
||
</div>
|
||
|
||
请参阅[术语表](/zh/reference/glossary)，其中包含本文档中使用的 Mintlify、Git、发布、导航、API 和 AI 相关术语的定义。
|