From bdb6360b76a485a63d5404400de4cb878524183f Mon Sep 17 00:00:00 2001 From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com> Date: Fri, 3 Oct 2025 13:54:29 -0700 Subject: [PATCH 1/3] remove duplicate zh files --- zh/advanced/dashboard/permissions.mdx | 21 - zh/advanced/dashboard/roles.mdx | 26 - zh/advanced/dashboard/sso.mdx | 135 -- zh/advanced/subpath/cloudflare.mdx | 208 --- zh/advanced/subpath/route53-cloudfront.mdx | 237 --- zh/advanced/subpath/vercel.mdx | 99 - zh/analytics/improving-docs.mdx | 40 - .../customization/adding-sdk-examples.mdx | 48 - .../customization/complex-data-types.mdx | 105 -- .../managing-page-visibility.mdx | 96 - .../customization/multiple-responses.mdx | 31 - zh/api-playground/migrating-from-mdx.mdx | 163 -- .../authentication-setup.mdx | 322 ---- .../personalization-setup.mdx | 392 ---- zh/code.mdx | 419 ----- zh/components/files.mdx | 97 - zh/editor/branches.mdx | 42 - zh/editor/git-concepts.mdx | 66 - zh/guides/assistant.mdx | 156 -- zh/guides/changelogs.mdx | 146 -- zh/guides/csp-configuration.mdx | 157 -- zh/guides/deployments.mdx | 31 - zh/guides/hidden-page-example.mdx | 61 - zh/guides/hidden-pages.mdx | 88 - zh/guides/migration.mdx | 201 -- zh/guides/monorepo.mdx | 51 - zh/guides/reverse-proxy.mdx | 160 -- zh/image-embeds.mdx | 194 -- zh/list-table.mdx | 92 - zh/navigation.mdx | 619 ------- zh/pages.mdx | 189 -- zh/pdf-exports.mdx | 37 - zh/react-components.mdx | 255 --- zh/reusable-snippets.mdx | 129 -- zh/settings.mdx | 1620 ----------------- zh/settings/broken-links.mdx | 47 - zh/settings/ci.mdx | 425 ----- zh/settings/custom-404-page.mdx | 46 - zh/settings/custom-domain.mdx | 55 - zh/settings/custom-scripts.mdx | 195 -- zh/settings/github.mdx | 106 -- zh/settings/gitlab.mdx | 96 - zh/settings/preview-deployments.mdx | 66 - zh/settings/seo.mdx | 224 --- zh/text.mdx | 284 --- zh/themes.mdx | 56 - 46 files changed, 8333 deletions(-) delete mode 100644 zh/advanced/dashboard/permissions.mdx delete mode 100644 zh/advanced/dashboard/roles.mdx delete mode 100644 zh/advanced/dashboard/sso.mdx delete mode 100644 zh/advanced/subpath/cloudflare.mdx delete mode 100644 zh/advanced/subpath/route53-cloudfront.mdx delete mode 100644 zh/advanced/subpath/vercel.mdx delete mode 100644 zh/analytics/improving-docs.mdx delete mode 100644 zh/api-playground/customization/adding-sdk-examples.mdx delete mode 100644 zh/api-playground/customization/complex-data-types.mdx delete mode 100644 zh/api-playground/customization/managing-page-visibility.mdx delete mode 100644 zh/api-playground/customization/multiple-responses.mdx delete mode 100644 zh/api-playground/migrating-from-mdx.mdx delete mode 100644 zh/authentication-personalization/authentication-setup.mdx delete mode 100644 zh/authentication-personalization/personalization-setup.mdx delete mode 100644 zh/code.mdx delete mode 100644 zh/components/files.mdx delete mode 100644 zh/editor/branches.mdx delete mode 100644 zh/editor/git-concepts.mdx delete mode 100644 zh/guides/assistant.mdx delete mode 100644 zh/guides/changelogs.mdx delete mode 100644 zh/guides/csp-configuration.mdx delete mode 100644 zh/guides/deployments.mdx delete mode 100644 zh/guides/hidden-page-example.mdx delete mode 100644 zh/guides/hidden-pages.mdx delete mode 100644 zh/guides/migration.mdx delete mode 100644 zh/guides/monorepo.mdx delete mode 100644 zh/guides/reverse-proxy.mdx delete mode 100644 zh/image-embeds.mdx delete mode 100644 zh/list-table.mdx delete mode 100644 zh/navigation.mdx delete mode 100644 zh/pages.mdx delete mode 100644 zh/pdf-exports.mdx delete mode 100644 zh/react-components.mdx delete mode 100644 zh/reusable-snippets.mdx delete mode 100644 zh/settings.mdx delete mode 100644 zh/settings/broken-links.mdx delete mode 100644 zh/settings/ci.mdx delete mode 100644 zh/settings/custom-404-page.mdx delete mode 100644 zh/settings/custom-domain.mdx delete mode 100644 zh/settings/custom-scripts.mdx delete mode 100644 zh/settings/github.mdx delete mode 100644 zh/settings/gitlab.mdx delete mode 100644 zh/settings/preview-deployments.mdx delete mode 100644 zh/settings/seo.mdx delete mode 100644 zh/text.mdx delete mode 100644 zh/themes.mdx diff --git a/zh/advanced/dashboard/permissions.mdx b/zh/advanced/dashboard/permissions.mdx deleted file mode 100644 index 29115eb9c..000000000 --- a/zh/advanced/dashboard/permissions.mdx +++ /dev/null @@ -1,21 +0,0 @@ ---- -title: '编辑器权限' -description: '让更多团队成员更新你的文档' ---- - -编辑器可以访问你的控制台和 Web 编辑器。 - -任何人都可以在本地参与编写文档并将更改推送到你的存储库,但在更改如何部署方面存在关键差异: - -* **编辑器的更改**:当编辑器通过 Web 编辑器发布,或将拉取请求(PR;亦称“合并请求”/Merge Request)合并到你的文档存储库时,更改会自动部署到你的线上站点。 -* **非编辑器的更改**:当非编辑器将拉取请求(PR;亦称“合并请求”/Merge Request)合并到你的存储库时,你需要在控制台手动触发一次部署,相关更改才会出现在你的线上站点。 - - - -
- ## 添加编辑 -
- -默认情况下,创建你 Mintlify 组织的团队成员拥有编辑权限。可在控制台的 [Members](https://dashboard.mintlify.com/settings/organization/members) 页面添加更多编辑。 - -编辑席位按使用量计费,你可以根据需要添加任意数量的编辑。更多详情请参阅我们的[定价页面](https://mintlify.com/pricing)。 diff --git a/zh/advanced/dashboard/roles.mdx b/zh/advanced/dashboard/roles.mdx deleted file mode 100644 index 5ee280abb..000000000 --- a/zh/advanced/dashboard/roles.mdx +++ /dev/null @@ -1,26 +0,0 @@ ---- -title: "Roles" -description: "使用角色控制对控制台的访问。" ---- - - - RBAC 功能适用于 [Enterprise plan](https://mintlify.com/pricing?ref=rbac)。 - - -Mintlify 提供两种控制台访问级别:Editor 和 Admin。 - -以下为仅限 Admin 角色的操作: - -| | Editor | Admin | -| ----------------------- | :----: | :---: | -| 更新用户角色 | ❌ | ✅ | -| 删除用户 | ❌ | ✅ | -| 邀请管理员 | ❌ | ✅ | -| 管理与更新账单 | ❌ | ✅ | -| 更新自定义 domain | ❌ | ✅ | -| 更新 Git source | ❌ | ✅ | -| 删除组织 | ❌ | ✅ | - -控制台中的其他操作对两种角色均可用。 - -你可以邀请任意数量的管理员,但我们建议仅为确有需要的用户授予管理员访问权限。 diff --git a/zh/advanced/dashboard/sso.mdx b/zh/advanced/dashboard/sso.mdx deleted file mode 100644 index e2d5e431c..000000000 --- a/zh/advanced/dashboard/sso.mdx +++ /dev/null @@ -1,135 +0,0 @@ ---- -title: "Single sign-on (SSO)" -description: "自定义团队登录管理控制台的方式" ---- - - - SSO 功能适用于 [Enterprise 计划](https://mintlify.com/pricing?ref=sso)。 - - -通过 SAML 与 OIDC 使用单点登录访问控制台。若你使用 Okta、Google Workspace 或 Microsoft Entra,我们提供了相应的提供商专用设置文档。若你使用其他提供商,请[联系我们](mailto:support@mintlify.com)。 - -
- ## Okta -
- - - - - - 在 `Applications` 下,点击创建一个基于 SAML 2.0 的新应用集成。 - - - 输入以下内容: - * 单点登录 URL(由 Mintlify 提供) - * 受众 URI(Audience URI,由 Mintlify 提供) - * Name ID Format:`EmailAddress` - * 属性声明(Attribute Statements): - | 名称 | 名称格式 | 值 - | ---- | ----------- | ----- - | `firstName` | Basic | `user.firstName` | - | `lastName` | Basic | `user.lastName` | - - - 应用设置完成后,进入 Sign-On 标签页,并将 metadata URL 发送给我们。 - 我们将据此在我们端启用连接。 - - - - - - - 在 `Applications` 下,点击创建一个基于 OIDC 的新应用集成。 - 请选择 `Web Application` 应用类型。 - - - 选择授权码(authorization code)授权类型,并输入 Mintlify 提供的 Redirect URI。 - - - 应用设置完成后,进入 General 标签页,找到 Client ID 和 Client Secret。 - 请将这些信息连同你的 Okta 实例 URL(例如,`.okta.com`)以安全方式提供给我们。你可以通过 1Password 或 SendSafely 等服务发送。 - - - - - -
- ## Google Workspace -
- - - - - - 在 `Web and mobile apps` 下,从 `Add app` 下拉菜单中选择 `Add custom SAML app`。 - - ![](/images/gsuite-add-custom-saml-app.png) - - - - 复制提供的 SSO URL、Entity ID 和 x509 证书,并发送给 Mintlify 团队。 - - ![](/images/gsuite-saml-metadata.png) - - - - 在 Service provider details 页面,输入以下内容: - * ACS URL(由 Mintlify 提供) - * Entity ID(由 Mintlify 提供) - * Name ID format:`EMAIL` - * Name ID:`Basic Information > Primary email` - - - ![](/images/gsuite-sp-details.png) - - - 在下一页,输入以下属性声明: - | Google Directory Attribute | App Attribute | - | -------------------------- | ------------- | - | `First name` | `firstName` | - | `Last name` | `lastName` | - - 完成此步骤并将用户分配到该应用后,请告知我们的团队,我们将为你的账号启用 SSO! - - - - - -
- ## Microsoft Entra -
- - - - - - 1. 在 “Enterprise applications” 下,选择 **New application**。 - 2. 选择 **Create your own application**,并选择 “Integrate any other application you don't find in the gallery (Non-gallery)”。 - - - 前往 Single Sign-On 设置页面并选择 **SAML**。在 “Basic SAML Configuration” 中输入: - * Identifier (Entity ID):Mintlify 提供的 Audience URI。 - * Reply URL (Assertion Consumer Service URL):Mintlify 提供的 ACS URL。 - - 其余保持为空,然后选择 **Save**。 - - - 编辑 Attributes & Claims 部分: - 1. 在 “Required Claim” 下选择 **Unique User Identifier (Name ID)**。 - 2. 将 Source 属性更改为使用 `user.primaryauthoritativeemail`。 - 3. 在 Additional claims 下,创建以下声明: - | Name | Value | - | ---- | ----- | - | `firstName` | `user.givenname` | - | `lastName` | `user.surname` | - - - 应用设置完成后,前往 “SAML Certificates” 部分,并将 App Federation Metadata URL 发送给我们。 - 我们会根据这些信息在我们这边启用连接。 - - - 在你的 Entra 应用中前往 “Users and groups”,添加应当能够访问你的控制台的用户。 - - - - \ No newline at end of file diff --git a/zh/advanced/subpath/cloudflare.mdx b/zh/advanced/subpath/cloudflare.mdx deleted file mode 100644 index f5bb9a773..000000000 --- a/zh/advanced/subpath/cloudflare.mdx +++ /dev/null @@ -1,208 +0,0 @@ ---- -title: "Cloudflare" -description: "使用 Cloudflare Workers 在自定义子路径托管文档" ---- - -import Propagating from "/snippets/zh/custom-subpath-propagating.mdx"; - -要使用 Cloudflare 将文档托管在自定义子路径(例如 `yoursite.com/docs`),你需要创建并配置一个 Cloudflare Worker。 - - - 开始之前,你需要一个 Cloudflare 账户和一个域名(可在 Cloudflare 内或外进行管理)。 - - - -
- ## 存储库结构 -
- -为匹配所选的子路径结构,必须在存储库中合理组织文档文件。比如,如果希望文档位于 `yoursite.com/docs`,则需创建一个 `docs/` 目录,并将所有文档文件放入其中。 - -
- ## 设置 Cloudflare Worker -
- -如果尚未创建,请按照 [Cloudflare Workers 入门指南](https://developers.cloudflare.com/workers/get-started/dashboard/)创建一个 Cloudflare Worker。 - - - 如果你的 DNS(域名系统)服务商是 Cloudflare,请不要为该 CNAME 记录启用代理。 - - -
- ### 使用 Vercel 部署时的代理 -
- -如果你在 Vercel 部署中使用 Cloudflare 作为代理,必须正确配置,以避免与 Vercel 的 domain 验证和 SSL 证书签发发生冲突。 - -错误的代理配置可能会阻止 Vercel 为 Let's Encrypt 的 SSL 证书进行签发,并导致 domain 验证失败。 - -
- #### 必需的路径允许列表 -
- -你的 Cloudflare Worker 必须允许以下特定路径的流量,不得阻止或重定向: - -- `/.well-known/acme-challenge/*` - 供 Let's Encrypt 证书验证使用 -- `/.well-known/vercel/*` - 供 Vercel domain 验证使用 - -尽管 Cloudflare 会自动处理许多验证规则,额外创建自定义规则可能会无意间阻断这些关键流量。 - -
- #### 标头转发要求 -
- -请确保在你的 Worker 配置中正确转发 `HOST` 标头。若未正确转发该标头,验证请求将会失败。 - -
- ### 配置路由 -
- -在你的 Cloudflare 控制台中,选择 **Edit Code**,将以下脚本添加到你的 Worker 代码中。有关编辑 Worker 的更多信息,请参阅 [Cloudflare 文档](https://developers.cloudflare.com/workers-ai/get-started/dashboard/#development)。 - - - 将 `[SUBDOMAIN]` 替换为你的唯一子域,将 `[YOUR_DOMAIN]` 替换为你网站的基础 URL;若子路径不同,将 `/docs` 替换为你期望的子路径。 - - -```javascript -addEventListener("fetch", (event) => { - event.respondWith(handleRequest(event.request)); -}); - -async function handleRequest(request) { - try { - const urlObject = new URL(request.url); - - // 如果请求是 Vercel 验证路径,允许其通过 - if (urlObject.pathname.startsWith('/.well-known/')) { - return await fetch(request); - } - - // 如果请求是 docs 子目录 - if (/^\/docs/.test(urlObject.pathname)) { - // 代理到 Mintlify - const DOCS_URL = "[SUBDOMAIN].mintlify.dev"; - const CUSTOM_URL = "[YOUR_DOMAIN]"; - - let url = new URL(request.url); - url.hostname = DOCS_URL; - - let proxyRequest = new Request(url, request); - - proxyRequest.headers.set("Host", DOCS_URL); - proxyRequest.headers.set("X-Forwarded-Host", CUSTOM_URL); - proxyRequest.headers.set("X-Forwarded-Proto", "https"); - // 如果部署到 Vercel,保留客户端 IP - proxyRequest.headers.set("CF-Connecting-IP", request.headers.get("CF-Connecting-IP")); - - return await fetch(proxyRequest); - } - } catch (error) { - // 如果未找到匹配操作,执行原始请求 - return await fetch(request); - } -} -``` - -选择 **Deploy**,并等待更改生效。 - - - - -
- ### 测试你的 Worker -
- -在部署代码后,测试你的 Worker,确保它能将流量路由到你的 Mintlify 文档。 - -1. 使用 Worker 的预览 URL 进行测试:`your-worker.your-subdomain.workers.dev/docs` -2. 确认该 Worker 能正确路由到你的 Mintlify 文档和你的网站。 - -
- ### 添加自定义 domain -
- -1. 在你的 [Cloudflare 控制台](https://dash.cloudflare.com/)中,进入你的 Worker。 -2. 前往 **Settings > Domains & Routes > Add > Custom Domain**。 -3. 添加你的 domain。 - - - 我们建议同时添加带有 `www.` 前缀和不带 `www.` 前缀的 domain。 - - -更多信息请参见 Cloudflare 文档:[Add a custom domain](https://developers.cloudflare.com/workers/configuration/routing/custom-domains/#add-a-custom-domain)。 - -
- ### 解决 DNS 冲突 -
- -如果你的 domain 已经指向其他服务,你必须移除现有的 DNS 记录。你的 Cloudflare Worker 必须配置为接管该 domain 的全部流量。 - -1. 删除该 domain 的现有 DNS 记录。更多信息请参阅 Cloudflare 文档中的[Delete DNS records](https://developers.cloudflare.com/dns/manage-dns-records/how-to/create-dns-records/#delete-dns-records)。 -2. 返回你的 Worker 并添加你的自定义 domain。 - -
- ## Webflow 自定义路由 -
- -如果你使用 Webflow 托管主站,并希望在同一 domain 的 `/docs` 路径下提供 Mintlify 文档,则需要通过 Cloudflare Workers 配置自定义路由,将所有非文档流量代理到你的主站。 - - - 在部署此 Worker 之前,请先将你的主站设置在一个着陆页上,否则访问主站的访客会看到错误。 - - -1. 在 Webflow 中,为主站设置一个着陆页,例如 `landing.yoursite.com`。当访客访问你的网站时会看到该页面。 -2. 将主站部署到该着陆页。这样可确保在你配置 Worker 的过程中主站仍然可访问。 -3. 为避免冲突,将主站中的任何绝对 URL 更新为相对路径。 -4. 在 Cloudflare 中选择 **Edit Code**,并将以下脚本添加到你的 Worker 代码中。 - - 将 `[SUBDOMAIN]` 替换为你唯一的子域,`[YOUR_DOMAIN]` 替换为你网站的基础 URL,`[LANDING_DOMAIN]` 替换为你的着陆页 URL;如需更改,将 `/docs` 替换为你想要的子路径。 - -```javascript - addEventListener("fetch", (event) => { - event.respondWith(handleRequest(event.request)); - }); - async function handleRequest(request) { - try { - const urlObject = new URL(request.url); - - // 如果请求指向 Vercel 验证路径,允许其通过 - if (urlObject.pathname.startsWith('/.well-known/')) { - return await fetch(request); - } - - // 如果请求指向 docs 子目录 - if (/^\/docs/.test(urlObject.pathname)) { - // 代理到 Mintlify - const DOCS_URL = "[SUBDOMAIN].mintlify.dev"; - const CUSTOM_URL = "[YOUR_DOMAIN]"; - let url = new URL(request.url); - url.hostname = DOCS_URL; - let proxyRequest = new Request(url, request); - proxyRequest.headers.set("Host", DOCS_URL); - proxyRequest.headers.set("X-Forwarded-Host", CUSTOM_URL); - proxyRequest.headers.set("X-Forwarded-Proto", "https"); - // 如果部署到 Vercel,保留客户端 IP - proxyRequest.headers.set("CF-Connecting-IP", request.headers.get("CF-Connecting-IP")); - return await fetch(proxyRequest); - } - // 将其他所有请求路由到主站点 - const MAIN_SITE_URL = "[LANDING_DOMAIN]"; - if (MAIN_SITE_URL && MAIN_SITE_URL !== "[LANDING_DOMAIN]") { - let mainSiteUrl = new URL(request.url); - mainSiteUrl.hostname = MAIN_SITE_URL; - return await fetch(mainSiteUrl, { - method: request.method, - headers: request.headers, - body: request.body - }); - } - } catch (error) { - // 如果未找到匹配操作,返回原始请求 - return await fetch(request); - } - } -``` - -5. 选择 **Deploy**,并等待更改生效。 - - diff --git a/zh/advanced/subpath/route53-cloudfront.mdx b/zh/advanced/subpath/route53-cloudfront.mdx deleted file mode 100644 index f64285cbf..000000000 --- a/zh/advanced/subpath/route53-cloudfront.mdx +++ /dev/null @@ -1,237 +0,0 @@ ---- -title: "AWS Route 53 与 CloudFront" -sidebarTitle: "AWS" -description: "使用 AWS 服务在自定义子路径下托管文档" ---- - -import Propagating from "/snippets/zh/custom-subpath-propagating.mdx"; - -要使用 AWS Route 53 和 CloudFront 将文档托管在自定义子路径(例如 `yoursite.com/docs`),你需要在 DNS(域名系统)提供商处配置记录指向你的 CloudFront 分配(Distribution)。 - - -
- ## 存储库结构 -
- -为匹配所选的子路径结构,你需要在存储库中组织文档文件。比如,如果你希望文档位于 `yoursite.com/docs`,应创建一个包含所有文档文件的 `docs/` 目录。 - -
- ## 概览(高层) -
- -将流量路由到以下路径,并将缓存策略设置为 **CachingDisabled**: - -- `/.well-known/acme-challenge/*` - 用于 Let's Encrypt 证书验证(必需) -- `/.well-known/vercel/*` - 用于 domain 验证(必需) -- `/docs/*` - 用于子路径路由(必需) -- `/docs/` - 用于子路径路由(必需) - -将流量路由到以下路径,并将缓存策略设置为 **CachingEnabled**: - -- `/mintlify-assets/_next/static/*` -- `Default (*)` - 你的网站着陆页 - -所有 Behaviors 的 **origin request policy** 必须为 `AllViewerExceptHostHeader`。 - -![CloudFront “Behaviors” 页面包含 4 个行为:`/docs/*`、`/docs`、`Default` 和 `/.well-known/*`。](/images/cloudfront/all-behaviors.png) - -
- ## 创建 CloudFront 分配 -
- -1. 在 AWS 控制台中进入 [CloudFront](https://aws.amazon.com/cloudfront)。 -2. 选择 **Create distribution**。 - - - ![CloudFront Distributions 页面,突出显示“Create distribution”按钮。](/images/cloudfront/create-distribution.png) - - -3. 在 Origin domain 中输入 `[SUBDOMAIN].mintlify.dev`,其中 `[SUBDOMAIN]` 是你项目的唯一子域。 - - - ![CloudFront “Create distribution” 页面,显示 “acme.mintlify.dev” 作为 origin domain。](/images/cloudfront/origin-name.png) - - -4. 在 “Web Application Firewall (WAF)” 中,启用安全防护。 - - - ![Web Application Firewall (WAF) 选项,已选择 “Enable security protections”。](/images/cloudfront/enable-security-protections.png) - - -5. 其余设置保持默认。 -6. 选择 **Create distribution**。 - -
- ## 添加默认 Origin -
- -1. 创建分发后,前往 “Origins” 标签页。 - - - ![一个 CloudFront 分发,已高亮显示 “Origins” 标签页。](/images/cloudfront/origins.png) - - -2. 找到与你主域名对应的预发布环境 URL。具体取决于落地页的托管方式,可能差异较大。例如,Mintlify 的预发布 URL 是 [mintlify-landing-page.vercel.app](https://mintlify-landing-page.vercel.app)。 - - - 如果你的落地页托管在 Webflow,请使用 Webflow 的预发布 URL,通常以 `.webflow.io` 结尾。 - - 如果你使用 Vercel,请使用每个项目都会提供的 `.vercel.app` 域名。 - - -3. 新建一个 Origin,并将你的预发布 URL 填入 “Origin domain”。 - - - ![CloudFront 的 “Create origin” 页面,已高亮显示 “Origin domain” 输入框。](/images/cloudfront/default-origin.png) - - -此时,你应当有两个 Origin:一个是 `[SUBDOMAIN].mintlify.app`,另一个是你的预发布 URL。 - - - ![CloudFront 的 “Origins” 页面包含两个 Origin:一个用于 `mintlify`,另一个用于 `mintlify-landing-page`。](/images/cloudfront/final-origins.png) - - -
- ## 设置行为 -
- -CloudFront 的行为用于控制子路径逻辑。总体上,我们希望实现以下逻辑: - -- **如果用户访问你的自定义子路径**,跳转到 `[SUBDOMAIN].mintlify.dev`。 -- **如果用户访问其他任意页面**,跳转到当前着陆页。 - -1. 前往 CloudFront 分配的 "Behaviors" 标签页。 - - - ![CloudFront 的 "Behaviors" 标签页(已高亮)。](/images/cloudfront/behaviors.png) - - -2. 点击 **Create behavior** 按钮,并创建如下行为。 - -
- ### `/.well-known/*` -
- -为 Vercel 域名验证路径创建一个 **Path pattern** 为 `/.well-known/*` 的行为,并将 **Origin and origin groups** 设置为你的文档 URL。 - -在 “Cache policy” 中选择 **CachingDisabled**,以确保这些验证请求不被缓存,能够直接通过。 - - - ![CloudFront「Create behavior」页面,"Path pattern" 为 "/.well-known/*",且 "Origin and origin groups" 指向预发布环境的 URL。](/images/cloudfront/well-known-policy.png) - - - -如果 `.well-known/*` 过于宽泛,至少可以为 Vercel 将其细分为 2 个行为: - - `/.well-known/vercel/*` - Vercel 域名验证所必需 - - `/.well-known/acme-challenge/*` - Let's Encrypt 证书验证所必需 - - -
- ### 自定义子路径 -
- -创建一个行为(Behavior),将你选择的子路径填入 **Path pattern**,例如 `/docs`,并将 **Origin and origin groups** 指向 `.mintlify.dev` 的 URL(此处为 `acme.mintlify.dev`)。 - -- 将 “Cache policy” 设置为 **CachingOptimized**。 -- 将 “Origin request policy” 设置为 **AllViewerExceptHostHeader**。 -- 将 “Viewer Protocol Policy” 设置为 **Redirect HTTP to HTTPS**。 - - - ![CloudFront “Create behavior” 页面,其中 “Path pattern”为 “/docs/*”,且 “Origin and origin groups” 指向 `acme.mintlify.dev` 的 URL。](/images/cloudfront/behavior-1.png) - - -
- ### 你的自定义带通配符的子路径 -
- -创建一个行为,将你选择的子路径加上 `/*` 作为 **Path pattern**(例如 `/docs/*`),并将 **Origin and origin groups** 指向相同的 `.mintlify.dev` URL。 - -除 **Path pattern** 外,这些设置应与基础子路径的行为完全一致。 - -- 将“Cache policy”设置为 **CachingOptimized**。 -- 将“Origin request policy”设置为 **AllViewerExceptHostHeader**。 -- 将“Viewer protocol policy”设置为 **Redirect HTTP to HTTPS** - -
- ### `/mintlify-assets/_next/static/*` -
- -- 将“Cache policy”设置为 **CachingOptimized** - - 将“Origin request policy”设置为 **AllViewerExceptHostHeader** - - 将“Viewer protocol policy”设置为 **Redirect HTTP to HTTPS** - -
- ### `Default (*)` -
- -最后,我们将编辑 `Default (*)` 行为。 - - - ![已选择 “Default (*)” 行为并突出显示 Edit 按钮的 CloudFront 分配。](/images/cloudfront/default-behavior-1.png) - - -1. 将默认行为的 **Origin and origin groups** 更改为预发布环境的 URL(本例为 `mintlify-landing-page.vercel.app`)。 - - - ![CloudFront 的 “Edit behavior” 页面,突出显示 “Origin and origin groups” 输入字段。](/images/cloudfront/default-behavior-2.png) - - -2. 选择 **保存更改**。 - -
- ### 确认已正确配置 Behaviors -
- -如果你按照上述步骤操作,Behaviors 应如下所示: - - - ![CloudFront「Behaviors」页面,包含 4 个行为:`/docs/*`、`/docs`、`Default` 和 `/.well-known/*`。](/images/cloudfront/all-behaviors.png) - - -
- ## 预览分发 -
- -现在可以前往“General”标签页并访问 **Distribution domain name** 的 URL,测试分发是否已正确配置。 - - - ![CloudFront “General” 标签页,已高亮显示 “Distribution domain name” 的 URL。](/images/cloudfront/preview-distribution.png) - - -所有页面应指向你的主登录页;如果在该 URL 后追加你选择的子路径(例如 `/docs`),应会跳转到你的 Mintlify 文档实例。 - -
- ## 连接 Route53 -
- -现在,我们将把 CloudFront 分配(Distribution)的功能接入你的主域名。 - - - 本节你也可以参考 AWS 官方指南:[Configuring - Amazon Route 53 to route traffic to a CloudFront - distribution](https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/routing-to-cloudfront-distribution.html#routing-to-cloudfront-distribution-config) - - -1. 在 AWS 控制台中进入 [Route53](https://aws.amazon.com/route53)。 -2. 进入主域名的 "Hosted zone"。 -3. 选择 **Create record**。 - - - ![Route 53「Records」页面,突出显示「Create record」按钮。](/images/cloudfront/route53-create-record.png) - - -4. 打开 `Alias`,然后在 **Route traffic to** 中选择 `Alias to CloudFront distribution` 选项。 - - - ![Route 53「Create record」页面,突出显示「Alias」开关与「Route traffic to」菜单。](/images/cloudfront/create-record-alias.png) - - -5. 选择 **Create records**。 - - - 如果当前存在 A 记录,可能需要先将其移除。 - - -你的文档现已在主域名的所选子路径上线。 - - \ No newline at end of file diff --git a/zh/advanced/subpath/vercel.mdx b/zh/advanced/subpath/vercel.mdx deleted file mode 100644 index d4d598c46..000000000 --- a/zh/advanced/subpath/vercel.mdx +++ /dev/null @@ -1,99 +0,0 @@ ---- -title: "Vercel" -description: "使用 Vercel 在自定义子路径下托管文档" ---- - -import { VercelJsonGenerator } from "/snippets/zh/vercel-json-generator.mdx"; - - -
- ## vercel.json 文件 -
- -`vercel.json` 文件用于配置项目的构建与部署。它位于项目根目录,控制部署的多个方面,包括路由、重写、重定向、请求头,以及构建设置。 - -我们使用 `rewrites` 配置将来自主域名的请求代理到文档站点。 - -Rewrites 会在不更改浏览器中 URL 的情况下,将传入请求映射到不同的目标。当有人访问 `yoursite.com/docs` 时,Vercel 会在内部从 `your-subdomain.mintlify.dev/docs` 获取内容,但用户在浏览器中仍会看到 `yoursite.com/docs`。这与重定向不同,重定向会将用户带到完全不同的 URL。 - -你可以将子路径自定义为任意你喜欢的值,例如 `/docs`、`/help` 或 `/guides`。此外,你也可以使用更深层级的嵌套子路径,例如 `/product/docs`。 - -
- ## 存储库结构 -
- -必须在存储库中按照所选子路径结构组织文档文件。举例来说,如果希望文档位于 `yoursite.com/docs`,则应创建一个包含所有文档文件的 `docs/` 目录。 - -
- ## 配置 -
- -要在 Vercel 上将文档托管到自定义子路径下,请在 `vercel.json` 文件中添加以下配置。此示例使用 `/docs`,你也可以替换为任意子路径: - -```json -{ - "rewrites": [ - { - "source": "/docs", - "destination": "https://[subdomain].mintlify.dev/docs" - }, - { - "source": "/docs/:match*", - "destination": "https://[subdomain].mintlify.dev/docs/:match*" - } - ] -} -``` - -* **`source`**: 你的 domain 上用于触发重写的路径模式。 -* **`destination`**: 请求应被代理到的目标位置。 -* **`:match*`**: 一个通配符,用于捕获子路径之后的所有路径段。 - -更多信息请参见 Vercel 文档中的[使用 vercel.json 配置项目:Rewrites](https://vercel.com/docs/projects/project-configuration#rewrites)。 - - -
- ### 生成重写规则 -
- -输入你的子域和自定义子目录,为你的 `vercel.json` 文件生成重写规则。 - - - -
- ## 在 Vercel 中使用外部代理 -
- -如果你在 Vercel 部署前面使用外部代理(如 Cloudflare 或 AWS CloudFront),必须正确配置,避免与 Vercel 的 domain 验证和 SSL 证书签发发生冲突。 - -错误的代理配置可能会阻止 Vercel 为你配置 Let's Encrypt SSL 证书,并导致 domain 验证失败。 - -请参阅 Vercel 文档中的[受支持的提供商](https://vercel.com/guides/how-to-setup-verified-proxy#supported-providers-verified-proxy-lite)。 - -
- ### 必需的路径允许列表 -
- -你的外部代理必须允许以下特定路径的流量通过,且不得阻止、重定向或进行强缓存: - -- `/.well-known/acme-challenge/*` - 用于 Let's Encrypt 证书验证 -- `/.well-known/vercel/*` - 用于 Vercel domain 验证 -- `/mintlify-assets/_next/static/*` - 用于静态资源 - -这些路径应原样直接透传到你的 Vercel 部署。 - -
- ### 头部转发要求 -
- -确保你的代理正确转发 `HOST` 头部。若未正确转发该头部,验证请求将会失败。 - -
- ### 测试你的代理设置 -
- -要验证代理是否已正确配置: - -1. 测试 `https://[yourdomain].com/.well-known/vercel/` 是否能返回响应。 -2. 确认在你的 Vercel 控制台中已正确签发 SSL 证书。 -3. 检查 domain 验证是否已成功完成。 \ No newline at end of file diff --git a/zh/analytics/improving-docs.mdx b/zh/analytics/improving-docs.mdx deleted file mode 100644 index 4ea2bc83f..000000000 --- a/zh/analytics/improving-docs.mdx +++ /dev/null @@ -1,40 +0,0 @@ ---- -title: "改进你的文档" -description: "利用 Analytics 数据提升你的文档质量" ---- - -基于 Analytics 控制台中的定量与定性数据优化你的文档。 - -
- ## 跨 Analytics 洞察 -
- -整合多个分析来源的信息,全面洞察你的文档。 - -
- ### 关联流量与满意度 -
- -- **高流量且低反馈评分**:页面很受关注,但用户体验欠佳。优先优化这些页面。 -- **低流量且高反馈评分**:文档表现良好,但可能不易被发现。考虑提升这些页面的曝光。 -- **高流量且高反馈评分**:你文档中的“王牌内容”。审阅这些页面,为改进其余内容获取灵感。 - -
- ### 将搜索意图与内容表现对齐 -
- -- **搜索量高且页面浏览量低**:可发现性问题。考虑调整这些页面的位置或检查其 frontmatter。 -- **热门搜索词且结果置信度低**:存在内容缺口。考虑围绕这些主题补充或新增内容。 -- **热门搜索词且匹配页面收到负面反馈**:用户体验问题。审查这些页面是否真正满足用户的搜索需求。 - -
- ## 将洞察转化为行动 -
- -使用这些跨 Analytics 的模式来优先推进文档改进: - -- **优先修复高影响问题**:热门页面但反馈评分较差,会影响最多的用户。 -- **填补已验证的内容缺口**:高搜索量但低置信度的搜索表明存在未被满足的用户需求。 -- **响应用户反馈**:上下文与代码片段层面的反馈可定位具体改进点。 -- **对齐搜索与内容**:确保搜索量最高的主题拥有全面且结构清晰的页面。 -- **监控尚无对应热门页面的上升搜索趋势**:把握新的内容机会。 \ No newline at end of file diff --git a/zh/api-playground/customization/adding-sdk-examples.mdx b/zh/api-playground/customization/adding-sdk-examples.mdx deleted file mode 100644 index 1a12835bb..000000000 --- a/zh/api-playground/customization/adding-sdk-examples.mdx +++ /dev/null @@ -1,48 +0,0 @@ ---- -title: "添加 SDK 示例" -description: "在 API 端点旁展示特定语言的代码示例,向开发者说明如何使用你的 SDK" ---- - -如果你的用户通过 SDK 而非直接发起网络请求来与 API 交互,你可以使用 `x-codeSamples` 扩展将代码示例添加到 OpenAPI 文档中,并在 OpenAPI 页面上展示。 - -此属性可添加到任意请求方法,并具有以下结构。 - - - 代码示例所用的语言。 - - - - 示例的标签。在为同一端点提供多个示例时很有用。 - - - - 示例的源代码。 - - -下面是一个植物追踪应用的代码示例,包含 Bash 命令行界面(CLI)工具和 JavaScript SDK。 - -```yaml -paths: - /plants: - get: - # ... - x-codeSamples: - - lang: bash - label: 列出所有未浇水的植物 - source: | - planter list -u - - lang: javascript - label: 列出所有未浇水的植物 - source: | - const planter = require('planter'); - planter.list({ unwatered: true }); - - lang: bash - label: 列出所有盆栽植物 - source: | - planter list -p - - lang: javascript - label: 列出所有盆栽植物 - source: | - const planter = require('planter'); - planter.list({ potted: true }); -``` diff --git a/zh/api-playground/customization/complex-data-types.mdx b/zh/api-playground/customization/complex-data-types.mdx deleted file mode 100644 index 4c8ba1927..000000000 --- a/zh/api-playground/customization/complex-data-types.mdx +++ /dev/null @@ -1,105 +0,0 @@ ---- -title: "复杂数据类型" -description: "使用 `oneOf`、`anyOf` 和 `allOf` 关键字,以灵活的 schema、可选属性和多种数据格式来描述 API" ---- - -当你的 API 接受多种数据格式、包含条件字段或采用继承模式时,OpenAPI 的 schema 组合关键字可以帮助你记录这些灵活的结构。通过使用 `oneOf`、`anyOf` 和 `allOf`,你可以描述既能处理不同输入类型、又能将多个 schema 组合成完整数据模型的 API。 - - - -
- ## `oneOf`, `anyOf`, `allOf` 关键字 -
- -对于复杂数据类型,OpenAPI 提供了用于组合 schema 的关键字: - -* `allOf`:将多个 schema 组合在一起(类似合并对象或扩展基础 schema)。作用相当于 `and` 运算符。 -* `anyOf`:接受与提供的任一 schema 匹配的数据。作用相当于 `or` 运算符。 -* `oneOf`:只接受与提供的 schema 中恰好一个匹配的数据。作用相当于 `exclusive-or` 运算符。 - -Mintlify 会将 `oneOf` 和 `anyOf` 以相同方式处理,因为二者在实际使用 API 时的差异很少产生影响。 - -有关这些关键字的详细规范,请参见 [OpenAPI 文档](https://swagger.io/docs/specification/data-models/oneof-anyof-allof-not/)。 - -`not` 关键字目前不受支持。 - -
- ### 使用 `allOf` 组合 schema -
- -当你使用 `allOf` 时,Mintlify 会对你的 OpenAPI 文档进行一些预处理,以便以更易读的方式展示复杂的组合。例如,当你用 `allOf` 组合两个对象 schema 时,Mintlify 会将两者的属性合并为一个对象。当你利用 OpenAPI 的可复用 [components](https://swagger.io/docs/specification/components/) 时,这一点尤其有用。 - -```yaml -org_with_users: - allOf: - - $ref: '#/components/schemas/Org' - - type: object - properties: - users: - type: array - description: 包含组织中所有用户的数组 -# ... -components: - schemas: - Org: - type: object - properties: - id: - type: string - description: 组织的 ID -``` - - - - - 组织的 ID - - - - 包含该组织所有用户的数组 - - - - -
- ### 使用 `oneOf` 和 `anyOf` 提供选项 -
- -当你使用 `oneOf` 或 `anyOf` 时,选项会显示在标签页容器中。请在每个子架构中指定一个 `title` 字段,为各个选项命名。例如,以下演示如何展示两种不同类型的送货地址: - -```yaml -delivery_address: - oneOf: - - title: StreetAddress - type: object - properties: - address_line_1: - type: string - description: 收件人的街道地址 - # ... - - title: POBox - type: object - properties: - box_number: - type: string - description: 邮政信箱的号码 - # ... -``` - - -
- - - - 住址的街道 - - - - - - 邮政信箱号码 - - - -
-
diff --git a/zh/api-playground/customization/managing-page-visibility.mdx b/zh/api-playground/customization/managing-page-visibility.mdx deleted file mode 100644 index 26a9285b0..000000000 --- a/zh/api-playground/customization/managing-page-visibility.mdx +++ /dev/null @@ -1,96 +0,0 @@ ---- -title: "管理页面可见性" -description: "控制 OpenAPI 规范中的哪些端点显示在文档导航中" ---- - -你可以控制哪些 OpenAPI 操作会发布为文档页面,以及它们在导航中的显示方式。这对于仅供内部使用的端点、已废弃的操作、测试版功能,或需要通过直接 URL 访问但不应通过站点导航被发现的端点非常有用。 - -如果你的页面是从 OpenAPI 文档自动生成的,你可以使用 `x-hidden` 和 `x-excluded` 扩展来管理页面可见性。 - - - -
- ## `x-hidden` -
- -`x-hidden` 扩展会为某个端点创建页面,但会在导航中将其隐藏。该页面只能通过直接访问其 URL 打开。 - -`x-hidden` 的常见用例包括: - -- 需要编写文档但不希望在导航中推广的端点。 -- 将从其他内容中链接到的页面。 -- 面向特定用户的端点。 - - - -
- ## `x-excluded` -
- -`x-excluded` 扩展会将某个端点从文档中完全排除。 - -`x-excluded` 的常见用例包括: - -- 仅供内部使用的端点。 -- 已废弃但不希望在文档中保留的端点。 -- 尚未准备好公开发布文档的测试版功能。 - - - -
- ## 实现 -
- -在 OpenAPI 规范中,将 `x-hidden` 或 `x-excluded` 扩展添加到相应的 HTTP 方法下。 - -下面是一些示例,展示如何在 OpenAPI 架构文档中为某个 endpoint 和 webhook 路径使用这些属性。 - -```json {11, 19} -"paths": { - "/plants": { - "get": { - "description": "返回商店中的所有植物", - "parameters": { /*...*/ }, - "responses": { /*...*/ } - } - }, - "/hidden_plants": { - "get": { - "x-hidden": true, - "description": "返回商店中的所有半秘密植物", - "parameters": { /*...*/ }, - "responses": { /*...*/ } - } - }, - "/secret_plants": { - "get": { - "x-excluded": true, - "description": "返回商店中的所有绝密植物(请勿发布此端点!)", - "parameters": { /*...*/ }, - "responses": { /*...*/ } - } - } -}, -``` - -```json {9, 15} -"webhooks": { - "/plants_hook": { - "post": { - "description": "新植物添加到商店时的 Webhook 信息", - } - }, - "/hidden_plants_hook": { - "post": { - "x-hidden": true, - "description": "新植物添加到商店时的机密信息 Webhook" - } - }, - "/secret_plants_hook": { - "post": { - "x-excluded": true, - "description": "新植物添加到商店时的绝密信息 Webhook(请勿发布此端点!)" - } - } -} -``` diff --git a/zh/api-playground/customization/multiple-responses.mdx b/zh/api-playground/customization/multiple-responses.mdx deleted file mode 100644 index 3b995949c..000000000 --- a/zh/api-playground/customization/multiple-responses.mdx +++ /dev/null @@ -1,31 +0,0 @@ ---- -title: "多个响应" -description: "为同一端点展示不同的响应变体" ---- - -如果你的 API 会根据输入参数、用户上下文或请求的其他条件返回不同的响应,你可以使用 `examples` 属性为多个响应示例编写文档。 - -该属性可添加到任意响应中,其模式如下。 - -```yaml -responses: - "200": - description: 成功响应 - content: - application/json: - schema: - $ref: "#/components/schemas/YourResponseSchema" - examples: - us: - summary: 美国的响应 - value: - countryCode: "US" - currencyCode: "USD" - taxRate: 0.0825 - gb: - summary: 英国的响应 - value: - countryCode: "GB" - currencyCode: "GBP" - taxRate: 0.20 -``` diff --git a/zh/api-playground/migrating-from-mdx.mdx b/zh/api-playground/migrating-from-mdx.mdx deleted file mode 100644 index d718206c1..000000000 --- a/zh/api-playground/migrating-from-mdx.mdx +++ /dev/null @@ -1,163 +0,0 @@ ---- -title: "将 MDX API 页面迁移到 OpenAPI 导航" -sidebarTitle: "从 MDX 迁移" -description: "将单个 MDX 端点页面更新为通过灵活导航的 OpenAPI 自动生成" -icon: "arrow-big-right-dash" ---- - -如果你目前为 API 端点使用单独的 `MDX` 页面,可以迁移为基于 OpenAPI 规范自动生成页面,同时保留单页的自定义灵活性。这样可以减少需要维护的文件数量,并提升 API 文档的一致性。 - -你可以在 OpenAPI 规范中为每个端点定义 metadata 和 content,并在导航中将端点组织到所需的位置。 - -
- ## CLI 迁移 -
- -推荐使用 `mint migrate-mdx` 命令,将 MDX 端点页面迁移为自动生成的页面。 - -该命令将: - -* 解析你的 `docs.json` 导航结构。 -* 识别用于生成 OpenAPI 端点页面的 MDX 页面。 -* 从 MDX 文件提取内容,并移动到 OpenAPI 规范中的 `x-mint` 扩展。 -* 更新你的 `docs.json`,使其直接引用 OpenAPI 端点而非 MDX 文件。 -* 删除原有的 MDX 端点文件。 - - - 如果你已为某个端点定义了 `x-mint`,同时还有一个包含该端点内容的 MDX 页面,则该 MDX 内容会覆盖现有的 `x-mint` 设置。 - - 如果你为同一端点准备了多个内容不同的 MDX 页面,脚本将采用在你的 `docs.json` 中出现最靠后的页面内容。 - - 迁移工具不支持在应用更改前预览更改。 - - - - - 确保你的 OpenAPI 规范有效,并包含你要编写文档的所有端点。 - - 需要迁移的任何 MDX 页面都必须在 `openapi:` frontmatter 中引用某个端点。 - - - 使用 [Swagger Editor](https://editor.swagger.io/) 或 [Mint CLI](https://www.npmjs.com/package/mint) 验证你的 OpenAPI 文件。 - - - - - 如有需要,请安装或更新 [Mint CLI](/zh/installation)。 - - - - ```bash - mint migrate-mdx - ``` - - - -
- ## 手动迁移步骤 -
- - - - 确保你的 OpenAPI 规范有效,并包含你希望记录的所有端点。 - - 对于需要自定义 metadata 或 content 的端点,请在该端点添加 `x-mint` 扩展。更多详情参见 [x-mint extension](/zh/api-playground/openapi-setup#x-mint-extension)。 - - 对于需要从文档中排除的端点,请在该端点添加 `x-hidden` 扩展。 - - - 使用 [Swagger Editor](https://editor.swagger.io/) 或 [Mint CLI](https://www.npmjs.com/package/mint) 验证你的 OpenAPI 文件。 - - - - - 在你的 `docs.json` 中,将 `MDX` 页面引用替换为 OpenAPI 端点。 - - ```json - "navigation": { - "groups": [ - { - "group": "API Reference", - "openapi": "/path/to/openapi.json", - "pages": [ - "overview", - "authentication", - "introduction", - "GET /health", - "quickstart", - "POST /users", - "GET /users/{id}", - "advanced-features" - ] - } - ] - } - ``` - - - - 在确认新的导航正常工作后,删除不再需要的 `MDX` 端点文件。 - - - - - -你可以自定义 API 文档在导航中的呈现方式。 - -
- ### 混合内容导航 -
- -将自动生成的 API 页面与其他页面结合使用: - -```json -"navigation": { - "groups": [ - { - "group": "API 参考", - "openapi": "openapi.json", - "pages": [ - "api/overview", - "GET /users", - "POST /users", - "api/authentication" - ] - } - ] -} -``` - -
- ### 多个 API 版本 -
- -使用选项卡或 groups 来组织不同的 API 版本: - -```json -"navigation": { - "tabs": [ - { - "tab": "API v1", - "openapi": "specs/v1.json" - }, - { - "tab": "API v2", - "openapi": "specs/v2.json" - } - ] -} -``` - -
- ## 何时使用单独的 `MDX` 页面 -
- -在以下情况下,建议保留单独的 `MDX` 页面: - -* 每个端点需要大量自定义内容,例如 React 组件或较长的示例。 -* 需要独特的页面布局。 -* 针对特定端点尝试实验性的文档写法。 - -对于大多数用例,OpenAPI 导航能提供更好的可维护性和一致性。 diff --git a/zh/authentication-personalization/authentication-setup.mdx b/zh/authentication-personalization/authentication-setup.mdx deleted file mode 100644 index e37c15977..000000000 --- a/zh/authentication-personalization/authentication-setup.mdx +++ /dev/null @@ -1,322 +0,0 @@ ---- -title: "认证设置" -description: "通过用户认证来控制文档的隐私" -icon: "file-lock" -keywords: ['auth'] ---- - - - [Pro 方案](https://mintlify.com/pricing?ref=authentication) 包含密码认证。 - - [Enterprise 方案](https://mintlify.com/pricing?ref=authentication) 支持所有认证方式。 - - -启用认证后,用户需先登录才能访问你的文档。 - -
- ## 认证模式 -
- -根据你的访问控制需求,在完整认证和部分认证模式之间进行选择。 - -**完整认证**:所有页面均受保护。用户必须先登录才能访问任何内容。 - -**部分认证**:部分页面对公众可见,其他页面需要认证。用户可以自由浏览公开内容,仅在访问受保护页面时需要进行认证。 - -在配置下方任一握手方式时,你需要在控制台设置中选择 **完整认证** 或 **部分认证**。 - -
- ## 配置认证 -
- -选择要配置的握手方式。 - - - - - 密码认证仅提供访问控制,**不**支持内容个性化。 - - - ### 前提条件 - - * 你的安全策略允许在用户之间共享同一密码。 - - ### 实施 - - - - 1. 在你的控制台中,前往 [Authentication](https://dashboard.mintlify.com/settings/deployment/authentication)。 - 2. 选择 **Full Authentication** 或 **Partial Authentication**。 - 3. 选择 **Password**。 - 4. 输入一个强密码。 - 5. 选择 **保存更改**。 - - - - 安全地将密码和文档的 URL 分享给获授权用户。 - - - - ## 示例 - - 你的文档托管在 `docs.foo.com`,你需要基本的访问控制,但不追踪单个用户。你希望阻止公众访问,同时让设置保持简单。 - - 在控制台中**创建一个强密码**,并将**凭据分享**给获授权用户。就是这么简单! - - - - ### 先决条件 - - * 你的文档用户同时也是你的文档编辑者。 - - ### 实施 - - - - 1. 在控制台中前往 [Authentication](https://dashboard.mintlify.com/settings/deployment/authentication)。 - 2. 选择 **Full Authentication** 或 **Partial Authentication**。 - 3. 选择 **Mintlify Auth**。 - 4. 选择 **Enable Mintlify Auth**。 - - - - 1. 在控制台中前往 [Members](https://dashboard.mintlify.com/settings/organization/members)。 - 2. 添加所有需要访问文档的人员。 - 3. 根据其编辑权限分配相应角色。 - - - - ### 示例 - - 你的文档托管在 `docs.foo.com`,团队通过控制台编辑文档。你希望仅限团队成员访问。 - - 在控制台设置中**启用 Mintlify 认证**。 - - 通过检查所有团队成员是否已添加到你的组织来**验证团队访问权限**。 - - - - ### 先决条件 - - * 支持 Authorization Code Flow 的 OAuth 或 OIDC 服务器。 - * 具备创建可由 OAuth 访问令牌访问的 API 端点的能力(可选,用于启用个性化功能)。 - - ### 实施 - - - - 1. 在控制台中前往 [认证](https://dashboard.mintlify.com/settings/deployment/authentication)。 - 2. 选择 **Full Authentication** 或 **Partial Authentication**。 - 3. 选择 **OAuth** 并配置以下字段: - - * **Authorization URL**:你的 OAuth 授权端点。 - * **Client ID**:你的 OAuth 2.0 客户端标识符。 - * **Client Secret**:你的 OAuth 2.0 客户端密钥。 - * **Scopes**:要请求的权限。请复制**完整**的 scope 字符串(例如,对于 `provider.users.docs` 这样的 scope,请复制完整的 `provider.users.docs`)。如需不同的访问级别,可使用多个 scope。 - * **Token URL**:你的 OAuth 令牌交换端点。 - * **Info API URL**(可选):用于获取用户信息以实现个性化的端点。若不填写,OAuth 流程仅用于验证身份,用户信息将为空。 - * **Logout URL**:你的 OAuth 提供方的原生登出 URL。若提供方有 `returnTo` 或类似参数,请将其指回你的文档 URL。 - - 4. 选择 **Save changes**。 - - - - 1. 从[认证设置](https://dashboard.mintlify.com/settings/deployment/authentication)中复制 **Redirect URL**。 - 2. 将该重定向 URL 添加为 OAuth 服务器的授权重定向 URL。 - - - - 为启用个性化功能,请创建一个 API 端点,该端点需: - - * 接受 OAuth 访问令牌进行认证。 - * 以 `User` 格式返回用户数据。详见 [User data format](/zh/authentication-personalization/personalization-setup#user-data-format)。 - - 将此端点的 URL 填入[认证设置](https://dashboard.mintlify.com/settings/deployment/authentication)中的 **Info API URL** 字段。 - - - - ### 示例 - - 你的文档托管在 `foo.com/docs`,并且你在 `auth.foo.com` 上已有一个支持 Authorization Code Flow 的 OAuth 服务器。 - - 在控制台中**配置 OAuth 服务器详情**: - - * **Authorization URL**:`https://auth.foo.com/authorization` - * **Client ID**:`ydybo4SD8PR73vzWWd6S0ObH` - * **Scopes**:`['provider.users.docs']` - * **Token URL**:`https://auth.foo.com/exchange` - * **Info API URL**:`https://api.foo.com/docs/user-info` - * **Logout URL**:`https://auth.foo.com/logout?returnTo=https%3A%2F%2Ffoo.com%2Fdocs` - - **在 `api.foo.com/docs/user-info` 创建用户信息端点**,该端点要求携带具有 `provider.users.docs` scope 的 OAuth 访问令牌,并返回: - - ```json - { - "content": { - "firstName": "Jane", - "lastName": "Doe" - }, - "groups": ["engineering", "admin"] - } - ``` - - **将你的 OAuth 服务器配置为允许重定向**到回调 URL。 - - - - ### 先决条件 - - * 可生成并签署 JWT(JSON Web Token)的认证系统。 - * 可创建重定向 URL 的后端服务。 - - ### 实施 - - - - 1. 在你的控制台前往 [Authentication](https://dashboard.mintlify.com/settings/deployment/authentication)。 - 2. 选择 **Full Authentication** 或 **Partial Authentication**。 - 3. 选择 **JWT**。 - 4. 输入你现有登录流程的 URL,并选择 **Save changes**。 - 5. 选择 **Generate new key**。 - 6. 将你的 key 安全存储在后端可访问的位置。 - - - - 修改你现有的登录流程,在用户完成认证后加入以下步骤: - - * 按 `User` 格式创建一个包含已认证用户信息的 JWT。更多信息参见 [User data format](/zh/authentication-personalization/personalization-setup#user-data-format)。 - * 使用 EdDSA 算法与密钥签署该 JWT。 - * 创建一个重定向 URL,返回到文档的 `/login/jwt-callback` 路径,并将 JWT 作为 hash 附加在其中。 - - - - ### 示例 - - 你的文档托管在 `docs.foo.com`,现有认证系统在 `foo.com`。你希望扩展登录流程,在保持文档与控制台分离的同时,为文档授予访问权限(或你没有控制台)。 - - 在 `https://foo.com/docs-login` 创建一个登录端点,用于扩展你现有的认证。 - - 在验证用户凭据之后: - - * 生成一个按 Mintlify 格式包含用户数据的 JWT。 - * 对 JWT 签名并重定向到 `https://docs.foo.com/login/jwt-callback#{SIGNED_JWT}`。 - - - ```ts TypeScript - import * as jose from 'jose'; - import { Request, Response } from 'express'; - - const TWO_WEEKS_IN_MS = 1000 * 60 * 60 * 24 * 7 * 2; - - const signingKey = await jose.importPKCS8(process.env.MINTLIFY_PRIVATE_KEY, 'EdDSA'); - - export async function handleRequest(req: Request, res: Response) { - const user = { - expiresAt: Math.floor((Date.now() + TWO_WEEKS_IN_MS) / 1000), // 2 week session expiration - groups: res.locals.user.groups, - content: { - firstName: res.locals.user.firstName, - lastName: res.locals.user.lastName, - }, - }; - - const jwt = await new jose.SignJWT(user) - .setProtectedHeader({ alg: 'EdDSA' }) - .setExpirationTime('10 s') // 10 second JWT expiration - .sign(signingKey); - - return res.redirect(`https://docs.foo.com/login/jwt-callback#${jwt}`); - } - ``` - - ```python Python - import jwt # pyjwt - import os - - from datetime import datetime, timedelta - from fastapi.responses import RedirectResponse - - private_key = os.getenv(MINTLIFY_JWT_PEM_SECRET_NAME, '') - - @router.get('/auth') - async def return_mintlify_auth_status(current_user): - jwt_token = jwt.encode( - payload={ - 'exp': int((datetime.now() + timedelta(seconds=10)).timestamp()), # 10 second JWT expiration - 'expiresAt': int((datetime.now() + timedelta(weeks=2)).timestamp()), # 1 week session expiration - 'groups': ['admin'] if current_user.is_admin else [], - 'content': { - 'firstName': current_user.first_name, - 'lastName': current_user.last_name, - }, - }, - key=private_key, - algorithm='EdDSA' - ) - - return RedirectResponse(url=f'https://docs.foo.com/login/jwt-callback#{jwt_token}', status_code=302) - ``` - - - ### 重定向未认证用户 - - 当未认证用户尝试访问受保护页面时,其预期目的地会在重定向到你的登录 URL 时被保留: - - 1. 用户尝试访问受保护页面:`https://docs.foo.com/quickstart`。 - 2. 重定向到你的登录 URL,并带上重定向 query 参数:`https://foo.com/docs-login?redirect=%2Fquickstart`。 - 3. 认证后,重定向到 `https://docs.foo.com/login/jwt-callback?redirect=%2Fquickstart#{SIGNED_JWT}`。 - 4. 用户到达其最初的目标页面。 - - - -
- ## 将页面设为公开 -
- -在使用部分认证时,默认所有页面均受保护。你可以在页面或分组级别通过 `public` 属性将特定页面设置为无需认证即可访问。 - -
- ### 页面级 -
- -要将页面设为公开,请在该页面的 frontmatter 中添加 `public: true`。 - -```mdx Public page example ---- -title: "公开页面" -public: true ---- -``` - -
- ### 组级 -
- -要将某个组内的所有页面设为公开,请在 `docs.json` 的 `navigation` 对象中该组名称下添加 `"public": true`。 - -```json Public group example -{ - "navigation": { - "groups": [ - { - "group": "公共组", - "public": true, - "icon": "play", - "pages": [ - "quickstart", - "installation", - "settings" - ] - }, - { - "group": "私有组", - "icon": "pause", - "pages": [ - "private-information", - "secret-settings" - ] - } - ] - } -} -``` diff --git a/zh/authentication-personalization/personalization-setup.mdx b/zh/authentication-personalization/personalization-setup.mdx deleted file mode 100644 index 181366379..000000000 --- a/zh/authentication-personalization/personalization-setup.mdx +++ /dev/null @@ -1,392 +0,0 @@ ---- -title: "个性化设置" -description: "让用户登录以获得个性化的文档体验" -icon: "user-cog" ---- - -当用户登录后,个性化功能会为每位用户定制你的文档。例如,你可以预填他们的 API key,展示与其套餐或角色相关的内容,或隐藏他们无权访问的部分。 - - - -
- ## 个性化功能 -
- -使用以下个性化能力定制内容。 - -
- ### API key 预填 -
- -通过在用户数据中返回与字段名称一致的项,自动为 API 操作台的字段填入用户特定的值。要使自动预填生效,用户数据中的字段名称必须与 API 操作台中的名称完全一致。 - -
- ### 动态 MDX 内容 -
- -使用 `user` 变量,根据用户信息(如姓名、方案或组织)显示动态内容。 - -```jsx -欢迎回来,{user.firstName}!您的 {user.org?.plan} 套餐包含... -``` - -请参阅下方的[用户数据格式](#user-data-format)部分,获取详细示例和实现指南。 - -
- ### 页面可见性 -
- -通过在页面的 frontmatter 中添加 `groups` 字段来限制哪些页面对您的用户可见。默认情况下,所有用户都能看到所有页面。 - -用户只会看到其所属 `groups` 中的页面。 - -```mdx ---- -title: "管理您的用户" -description: "在您的组织中添加和删除用户" -groups: ["admin"] ---- -``` - - -
- ## 用户数据格式 -
- -在实现个性化时,系统会以特定格式返回用户数据,以便进行内容定制。根据握手方式的不同,这些数据可以作为原始 JSON 对象发送,或封装在已签名的 JWT(JSON Web Token)中。两种方式的数据结构相同。 - -```tsx -type User = { - expiresAt?: number; - groups?: string[]; - content?: Record; - apiPlaygroundInputs?: { - header?: Record; - query?: Record; - cookie?: Record; - server?: Record; - }; -}; -``` - - - 会话过期时间,以自 Unix 纪元起计算的秒数表示。如果用户在该时间之后加载页面,其存储的数据会被自动删除,并且必须重新进行认证。 - 关于 JWT 握手: 这与 JWT 的 `exp` 声明不同,后者决定 JWT 何时被视为无效。出于安全考虑,将 JWT 的 `exp` 声明设置为较短的时长(10 秒或更短)。使用 `expiresAt` 表示实际的会话时长(从数小时到数周)。 - - - - 用户所属的 groups 列表。frontmatter 中具有匹配 `groups` 的页面对该用户可见。 - - **示例**:具有 `groups: ["admin", "engineering"]` 的用户可以访问带有 `admin` 或 `engineering` 组标签的页面。 - - - - 可通过 `user` 变量在你的 `MDX` 内容中访问的自定义数据。将其用于在整个文档中实现动态个性化。 - - **基础示例**: - - ```json - { "firstName": "Ronan", "company": "Acme Corp", "plan": "Enterprise" } - ``` - - **在 `MDX` 中的用法**: - - ```mdx - Welcome back, {user.firstName}! Your {user.plan} plan includes... - ``` - - 使用示例 `user` 数据,这将渲染为:Welcome back, Ronan! Your Enterprise plan includes... - - **高级条件渲染**: - - ```jsx - Authentication is an enterprise feature. { - user.org === undefined - ? <>To access this feature, first create an account at the Mintlify dashboard. - : user.org.plan !== 'enterprise' - ? <>You are currently on the ${user.org.plan ?? 'free'} plan. See our pricing page for information about upgrading. - : <>To request this feature for your enterprise org, contact your admin. - } - ``` - - - `user` 中的信息仅对已登录用户可用。对于未登录用户,`user` 的值为 `{}`。为防止页面在未登录用户情况下崩溃,请始终在你的 `user` 字段上使用可选链。例如,`{user.org?.plan}`。 - - - - - 用于预填 API 操作台字段的用户特定值。在测试 API 时自动填充其数据,为用户节省时间。 - - **示例**: - - ```json - { - "header": { "X-API-Key": "user_api_key_123" }, - "server": { "subdomain": "foo" }, - "query": { "org_id": "12345" } - } - ``` - - 如果用户在特定子域发起请求,你可以将 `{ server: { subdomain: 'foo' } }` 作为 `apiPlaygroundInputs` 字段发送。该值将在任何包含 `subdomain` 值的 API 页面上被预填。 - - `header`、`query` 和 `cookie` 字段只有在属于你的 [OpenAPI 安全方案](https://swagger.io/docs/specification/authentication/)时才会预填。如果字段位于 `Authorization` 或 `Server` 部分,它将被预填。仅创建名为 `Authorization` 的标准 header 参数并不会启用此功能。 - - -
- ### 示例用户数据 -
- -```json -{ - "expiresAt": 1735689600, - "groups": ["admin", "beta-users"], - "content": { - "firstName": "Jane", - "lastName": "Smith", - "company": "TechCorp", - "plan": "Enterprise", - "region": "us-west" - }, - "apiPlaygroundInputs": { - "header": { - "Authorization": "Bearer abc123", - "X-Org-ID": "techcorp" - }, - "server": { - "environment": "production", - "region": "us-west" - } - } -} -``` - - -
- ## 配置个性化 -
- -选择要配置的握手机制。 - - - - - - ### 先决条件 - - * 能生成并签署 JWT 的登录系统 - * 能创建重定向 URL 的后端服务 - - ### 实施 - - - - 1. 在你的控制台,前往 [认证](https://dashboard.mintlify.com/settings/deployment/authentication)。 - 2. 选择 **Personalization**。 - 3. 选择 **JWT**。 - 4. 输入你现有登录流程的 URL,并选择 **保存更改**。 - 5. 选择 **Generate new key**。 - 6. 将你的 key 安全存放在后端可访问的位置。 - - - - 在用户登录后,修改你现有的登录流程以包含以下步骤: - - * 按 `User` 格式创建一个包含已登录用户信息的 JWT。更多信息参见上方的[用户数据格式](#user-data-format)。 - * 使用 ES256 算法和密钥对该 JWT 进行签名。 - * 创建一个返回到你的文档站点的重定向 URL,并将 JWT 作为 hash 包含其中。 - - - - ### 示例 - - 你的文档托管在 `docs.foo.com`。你希望文档与控制台分离(或你没有控制台),并启用个性化。 - - 先生成一个 JWT 密钥。然后在 `https://foo.com/docs-login` 创建一个登录端点,以启动通往文档站点的登录流程。 - - 在验证用户凭证之后: - - * 生成一个符合 Mintlify 格式的、包含用户数据的 JWT。 - * 签名该 JWT 并重定向到 `https://docs.foo.com#{SIGNED_JWT}`。 - - ```ts - import * as jose from 'jose'; - import { Request, Response } from 'express'; - - const TWO_WEEKS_IN_MS = 1000 * 60 * 60 * 24 * 7 * 2; - - const signingKey = await jose.importPKCS8(process.env.MINTLIFY_PRIVATE_KEY, 'ES256'); - - export async function handleRequest(req: Request, res: Response) { - const user = { - expiresAt: Math.floor((Date.now() + TWO_WEEKS_IN_MS) / 1000), - groups: res.locals.user.groups, - content: { - firstName: res.locals.user.firstName, - lastName: res.locals.user.lastName, - }, - }; - - const jwt = await new jose.SignJWT(user) - .setProtectedHeader({ alg: 'ES256' }) - .setExpirationTime('10 s') - .sign(signingKey); - - return res.redirect(`https://docs.foo.com#${jwt}`); - } - ``` - - ### 保留页面锚点 - - 要在登录后将用户重定向到特定部分,请使用以下 URL 格式:`https://docs.foo.com/page#jwt={SIGNED_JWT}&anchor={ANCHOR}`。 - - **示例**: - - * 原始 URL:`https://docs.foo.com/quickstart#step-one` - * 重定向 URL:`https://docs.foo.com/quickstart#jwt={SIGNED_JWT}&anchor=step-one` - - - - ### 先决条件 - - * 一个支持带有 PKCE 流程的授权码(Auth Code)模式的 OAuth 服务器 - * 能创建可由 OAuth 访问令牌访问的 API 端点 - - ### 实施 - - - - 创建一个 API 端点,该端点: - - * 接收 OAuth 访问令牌进行认证。 - * 以 `User` 格式返回用户数据。更多信息参见上面的[用户数据格式](#user-data-format)部分。 - * 定义访问所需的 scope。 - - - - 1. 在你的控制台中,前往[认证](https://dashboard.mintlify.com/settings/deployment/authentication)。 - 2. 选择 **Personalization**。 - 3. 选择 **OAuth** 并配置以下字段: - - * **Authorization URL**:你的 OAuth 授权端点。 - * **Client ID**:你的 OAuth 2.0 客户端标识符。 - * **Scopes**:要请求的权限。复制**完整**的 scope 字符串(例如,对于 `provider.users.docs` 这样的 scope,复制完整的 `provider.users.docs`)。必须与第一步中你配置的端点的 scopes 保持一致。 - * **Token URL**:你的 OAuth 令牌交换端点。 - * **Info API URL**:用于获取个性化所需用户数据的端点。于第一步创建。 - - 4. 选择 **保存更改** - - - - 1. 从你的[认证设置](https://dashboard.mintlify.com/settings/deployment/authentication)中复制 **Redirect URL**。 - 2. 将此 URL 添加为你的 OAuth 服务器配置中的已授权重定向 URL。 - - - - ### 示例 - - 你的文档托管在 `foo.com/docs`,并且你已有一个支持 PKCE 流程的 OAuth 服务器。你希望基于用户数据对文档进行个性化。 - - 在 `api.foo.com/docs/user-info` 上**创建一个用户信息端点**,该端点需要具有 `provider.users.docs` scope 的 OAuth 访问令牌,并返回用户的自定义数据: - - ```json - { - "content": { - "firstName": "Jane", - "lastName": "Doe" - }, - "groups": ["engineering", "admin"] - } - ``` - - **在控制台中配置你的 OAuth 服务器详情**: - - * **Authorization URL**: `https://auth.foo.com/authorization` - * **客户端ID**: `ydybo4SD8PR73vzWWd6S0ObH` - * **Scopes**: `['docs-user-info']` - * **Token URL**: `https://auth.foo.com/exchange` - * **Info API URL**: `https://api.foo.com/docs/user-info` - - **将你的 OAuth 服务器配置为** 允许重定向到你的回调 URL。 - - - - ### 先决条件 - - * 具有基于 Cookie 的会话认证的控制台或用户门户。 - * 能在与控制台相同来源或子域上创建一个 API 端点。 - * 如果你的控制台在 `foo.com`,则 **API URL** 必须以 `foo.com` 或 `*.foo.com` 开头。 - * 如果你的控制台在 `dash.foo.com`,则 **API URL** 必须以 `dash.foo.com` 或 `*.dash.foo.com` 开头。 - * 你的文档与控制台托管在相同的 domain 或子域上。 - * 如果你的控制台在 `foo.com`,你的 **文档** 必须托管在 `foo.com` 或 `*.foo.com`。 - * 如果你的控制台在 `*.foo.com`,你的 **文档** 必须托管在 `foo.com` 或 `*.foo.com`。 - - ### 实施 - - - - 创建一个 API 端点,其要求: - - * 使用你现有的会话认证来识别用户 - * 按 `User` 格式返回用户数据(参见上面的 [User data format](#user-data-format) 部分) - * 如果 API 的 domain 与文档的 domain **不完全匹配**: - - * 将文档的 domain 添加到你的 API 的 `Access-Control-Allow-Origin` 头(不能为 `*`)。 - * 将你的 API 的 `Access-Control-Allow-Credentials` 头设置为 `true`。 - - - 仅在此特定端点上启用 CORS 头,而不是在整个控制台 API 上启用。 - - - - - 1. 在你的控制台中,前往 [Authentication](https://dashboard.mintlify.com/settings/deployment/authentication)。 - 2. 选择 **Personalization**。 - 3. 选择 **Shared Session**。 - 4. 输入你的 **Info API URL**,即第一步中的端点。 - 5. 输入你的 **Login URL**,即用户登录控制台的地址。 - 6. 选择 **保存更改**。 - - - - ### 示例 - - #### 控制台在子域,文档在子域 - - 你的控制台在 `dash.foo.com`,使用基于 Cookie 的会话认证。你的控制台 API 路由托管在 `dash.foo.com/api`。你希望为托管在 `docs.foo.com` 的文档设置个性化。 - - 设置流程: - - 1. 创建端点 `dash.foo.com/api/docs/user-info`,通过会话认证识别用户并返回其用户数据。 - 2. 仅为此路由添加 CORS 头: - * `Access-Control-Allow-Origin`: `https://docs.foo.com` - * `Access-Control-Allow-Credentials`: `true` - 3. 在认证设置中配置 API URL:`https://dash.foo.com/api/docs/user-info`。 - - #### 控制台在子域,文档在根域 - - 你的控制台在 `dash.foo.com`,使用基于 Cookie 的会话认证。你的控制台 API 路由托管在 `dash.foo.com/api`。你希望为托管在 `foo.com/docs` 的文档设置个性化。 - - 设置流程: - - 1. 创建端点 `dash.foo.com/api/docs/user-info`,通过会话认证识别用户并返回其用户数据。 - 2. 仅为此路由添加 CORS 头: - * `Access-Control-Allow-Origin`: `https://foo.com` - * `Access-Control-Allow-Credentials`: `true` - 3. 在认证设置中配置 API URL:`https://dash.foo.com/api/docs/user-info`。 - - #### 控制台在根域,文档在根域 - - 你的控制台在 `foo.com/dashboard`,使用基于 Cookie 的会话认证。你的控制台 API 路由托管在 `foo.com/api`。你希望为托管在 `foo.com/docs` 的文档设置个性化。 - - 设置流程: - - 1. 创建端点 `foo.com/api/docs/user-info`,通过会话认证识别用户并返回其用户数据。 - 2. 在认证设置中配置 API URL:`https://foo.com/api/docs/user-info` - - - 不需要进行 CORS 配置,因为控制台与文档共享相同的 domain。 - - - - - diff --git a/zh/code.mdx b/zh/code.mdx deleted file mode 100644 index 95d113b44..000000000 --- a/zh/code.mdx +++ /dev/null @@ -1,419 +0,0 @@ ---- -title: "代码" -description: "展示内联代码与代码块" -icon: "code" ---- - -
- ## 添加代码示例 -
- -你可以添加行内代码片段或代码块。代码块支持用于语法高亮、title、行高亮、icon 等的元选项,以及更多功能。 - -
- ### 行内代码 -
- -要将 `word` 或 `phrase` 表示为代码,请用反引号(`)包裹。 - -```mdx -要将`单词`或`短语`标记为代码,请用反引号(`)将其包围。 -``` - -
- ### 代码块 -
- -使用[围栏代码块](https://www.markdownguide.org/extended-syntax/#fenced-code-blocks),用三个反引号包裹代码。代码块可复制;如果启用了 AI 助手,用户还可以让 AI 解释代码。 - -为实现语法高亮并启用元选项,请指定编程语言。在语言标识之后添加任意元选项,例如标题或 icon。 - - - ```java HelloWorld.java example lines icon="java" - class HelloWorld { - public static void main(String[] args) { - System.out.println("Hello, World!"); - } - } - ``` - - ````mdx Format - ```java HelloWorld.java lines icon="java" - class HelloWorld { - public static void main(String[] args) { - System.out.println("Hello, World!"); - } - } - ``` - ```` - - -
- ## 代码块选项 -
- -你可以为代码块添加元选项,以自定义其显示效果。 - - - 在添加任何其他元选项之前,必须先为代码块指定编程语言。 - - -
- ### 选项语法 -
- -* **字符串与布尔选项**:可用 `""`、`''`,或不加引号包裹。 -* **表达式选项**:可用 `{}`、`""`,或 `''` 包裹。 - -
- ### 语法高亮 -
- -在代码块的起始反引号后添加编程语言以启用语法高亮。 - -我们使用 [Shiki](https://shiki.style/) 实现语法高亮,并支持其提供的所有语言。完整列表请参见 Shiki 文档中的[语言](https://shiki.style/languages)。 - -在 `docs.json` 文件中通过 `styling.codeblocks` 全局自定义代码块主题。你可以设置 `system` 或 `dark` 等简单主题,或为浅色与深色模式配置自定义的 [Shiki 主题](https://shiki.style/themes)。配置选项见 [Settings](/zh/settings#styling)。 - - - ```java 语法高亮示例 - class HelloWorld { - public static void main(String[] args) { - System.out.println("Hello, World!"); - } - } - ``` - - ````mdx 格式 - ```java - class HelloWorld { - public static void main(String[] args) { - System.out.println("Hello, World!"); - } - } - ``` - ```` - - -
- ### Twoslash -
- -在 JavaScript 和 TypeScript 代码块中,使用 `twoslash` 可启用交互式类型信息。用户可以像在 IDE 中一样,将鼠标悬停在变量、函数和参数上,以查看类型与错误提示。 - - - ```ts twoslash Twoslash example - type Pet = "cat" | "dog" | "hamster"; - - function adoptPet(name: string, type: Pet) { - return `${name} the ${type} is now adopted!`; - } - - // 悬停以查看推断的类型 - const message = adoptPet("Mintie", "cat"); - ``` - - ````mdx Format - ```ts twoslash - type Pet = "cat" | "dog" | "hamster"; - - function adoptPet(name: string, type: Pet) { - return `${name} the ${type} is now adopted!`; - } - - // 悬停以查看推断的类型 - const message = adoptPet("Mintie", "cat"); - ``` - ```` - - -
- ### 标题 -
- -为代码示例添加一个标题。使用 `title="Your title"`,或在单行中添加字符串。 - - - ```javascript 标题示例 - const hello = "world"; - ``` - - ````mdx 格式 - ```javascript 标题示例 - const hello = "world"; - ``` - ```` - - -
- ### 图标 -
- -使用 `icon` 属性为代码块添加图标。请参阅 [图标](/zh/components/icons) 了解所有可用选项。 - - - ```javascript 图标 示例 icon="square-js" - const hello = "world"; - ``` - - ````mdx 格式 - ```javascript icon="square-js" - const hello = "world"; - ``` - ```` - - -
- ### 行高亮 -
- -在代码块中使用 `highlight` 并指定要高亮的行号或范围,以突出显示特定行。 - - - ```javascript Line highlighting example highlight= {1-2,5} - const greeting = "Hello, World!"; - function sayHello() { - console.log(greeting); - } - sayHello(); - ``` - - ````mdx Format - ```javascript highlight={1-2,5} - const greeting = "Hello, World!"; - function sayHello() { - console.log(greeting); - } - sayHello(); - ``` - ```` - - -
- ### 行聚焦 -
- -在代码块中使用带有行号或范围的 `focus` 来突出显示特定行。 - - - ```javascript Line focus example focus= {2,4-5} - const greeting = "Hello, World!"; - function sayHello() { - console.log(greeting); - } - sayHello(); - ``` - - ````mdx Format - ```javascript focus={2,4-5} - const greeting = "Hello, World!"; - function sayHello() { - console.log(greeting); - } - sayHello(); - ``` - ```` - - -
- ### 显示行号 -
- -使用 `lines` 在代码块左侧显示行号。 - - - ```javascript 显示行号示例 lines - const greeting = "Hello, World!"; - function sayHello() { - console.log(greeting); - } - sayHello(); - ``` - - ````mdx 格式 - ```javascript lines - const greeting = "Hello, World!"; - function sayHello() { - console.log(greeting); - } - sayHello(); - ``` - ```` - - -
- ### 可展开 -
- -使用 `expandable` 让用户展开或折叠较长的代码块。 - - - ```python Expandable example expandable - from datetime import datetime, timedelta - from typing import Dict, List, Optional - from dataclasses import dataclass - - @dataclass - class Book: - title: str - author: str - isbn: str - checked_out: bool = False - due_date: Optional[datetime] = None - - class Library: - def __init__(self): - self.books: Dict[str, Book] = {} - self.checkouts: Dict[str, List[str]] = {} # patron -> list of ISBNs - - def add_book(self, book: Book) -> None: - if book.isbn in self.books: - raise ValueError(f"Book with ISBN {book.isbn} already exists") - self.books[book.isbn] = book - - def checkout_book(self, isbn: str, patron: str, days: int = 14) -> None: - if patron not in self.checkouts: - self.checkouts[patron] = [] - - book = self.books.get(isbn) - if not book: - raise ValueError("Book not found") - - if book.checked_out: - raise ValueError("Book is already checked out") - - if len(self.checkouts[patron]) >= 3: - raise ValueError("Patron has reached checkout limit") - - book.checked_out = True - book.due_date = datetime.now() + timedelta(days=days) - self.checkouts[patron].append(isbn) - - def return_book(self, isbn: str) -> float: - book = self.books.get(isbn) - if not book or not book.checked_out: - raise ValueError("Book not found or not checked out") - - late_fee = 0.0 - if datetime.now() > book.due_date: - days_late = (datetime.now() - book.due_date).days - late_fee = days_late * 0.50 - - book.checked_out = False - book.due_date = None - - # Remove from patron's checkouts - for patron, books in self.checkouts.items(): - if isbn in books: - books.remove(isbn) - break - - return late_fee - - def search(self, query: str) -> List[Book]: - query = query.lower() - return [ - book for book in self.books.values() - if query in book.title.lower() or query in book.author.lower() - ] - - def main(): - library = Library() - - # Add some books - books = [ - Book("The Hobbit", "J.R.R. Tolkien", "978-0-261-10295-4"), - Book("1984", "George Orwell", "978-0-452-28423-4"), - ] - - for book in books: - library.add_book(book) - - # Checkout and return example - library.checkout_book("978-0-261-10295-4", "patron123") - late_fee = library.return_book("978-0-261-10295-4") - print(f"Late fee: ${late_fee:.2f}") - - if __name__ == "__main__": - main() - ``` - - ````text 格式 - ```python expandable - from datetime import datetime, timedelta - from typing import Dict, List, Optional - from dataclasses import dataclass - - # ... - - if __name__ == "__main__": - main() - ``` - ```` - - -
- ### 自动换行 -
- -使用 `wrap` 为长行启用自动换行。这样可以避免水平滚动,并使长行更易阅读。 - - - ```javascript Wrap example wrap - const greeting = "Hello, World! I am a long line of text that will wrap to the next line."; - function sayHello() { - console.log(greeting); - } - sayHello(); - ``` - - ````mdx Format - ```javascript wrap - const greeting = "Hello, World! I am a long line of text that will wrap to the next line."; - function sayHello() { - console.log(greeting); - } - sayHello(); - ``` - ```` - - -
- ### Diff -
- -在代码块中以可视化方式展示新增或删除的行。新增行将以绿色高亮,删除行将以红色高亮。 - -要创建差异,请在代码块中目标行的末尾添加以下特殊注释: - -* `// [!code ++]`:将该行标记为新增(绿色高亮)。 -* `// [!code --]`:将该行标记为删除(红色高亮)。 - -对于多行连续的更改,可在冒号后指定行数: - -* `// [!code ++:3]`:将当前行及其后两行标记为新增。 -* `// [!code --:5]`:将当前行及其后四行标记为删除。 - -注释语法须与所用编程语言一致(例如,JavaScript 使用 `//`,Python 使用 `#`)。 - - - ```js Diff example lines - const greeting = "Hello, World!"; // [!code ++] - function sayHello() { - console.log("Hello, World!"); // [!code --] - console.log(greeting); // [!code ++] - } - sayHello(); - ``` - - ````text Format - ```js lines - const greeting = "Hello, World!"; // [!code ++] - function sayHello() { - console.log("Hello, World!"); // [!code --] - console.log(greeting); // [!code ++] - } - sayHello(); - ``` - ```` - \ No newline at end of file diff --git a/zh/components/files.mdx b/zh/components/files.mdx deleted file mode 100644 index e72fb246d..000000000 --- a/zh/components/files.mdx +++ /dev/null @@ -1,97 +0,0 @@ ---- -title: "文件" -description: "从文档中提供静态资源" -icon: "folder" ---- - -Mintlify 会自动从你的文档存储库中,将静态资源在你的 domain 上按相应路径提供访问。比如,如果你的存储库中有 `/images/my-logo.png`,则该图片可通过 `https://docs.your-project.com/images/my-logo.png` 访问。 - -这适用于你希望向用户提供的任何文件类型,包括图片、PDF、视频或架构(schema)。 - -图片文件必须小于 20 MB,其他文件类型必须小于 100 MB。 - -
- ## 支持的文件扩展名 -
- -Mintlify 支持以下静态文件的扩展名。 - -
- ### 图片格式 -
- -- `.jpeg`, `.jpg`, `.jfif`, `.pjpeg`, `.pjp` -- `.png` -- `.svg`, `.svgz` -- `.ico` -- `.webp` -- `.gif`, `.apng` -- `.avif` -- `.bmp` -- `.tiff`, `.tif` - -
- ### 视频格式 -
- -- `.mp4` -- `.webm` -- `.ogg` -- `.avi` -- `.mov` -- `.wmv` -- `.flv` -- `.mkv` -- `.m4v` - -
- ### 音频格式 -
- -- `.mp3` -- `.wav` -- `.flac` -- `.aac` -- `.ogg` -- `.wma` -- `.m4a` - -
- ### 文档格式 -
- -- `.pdf` -- `.txt` -- `.doc`, `.docx` -- `.xls`, `.xlsx` -- `.ppt`, `.pptx` -- `.rtf` -- `.odt`, `.ods`, `.odp` - -
- ### 数据格式 -
- -- `.csv` -- `.tsv` -- `.xml` - -
- ## 文件组织 -
- -使用文件夹来组织文件,使你的存储库更便于浏览: - -```text -/your-project - |- docs.json - |- images/ - |- logo.png - |- screenshots/ - |- dashboard.png - |- assets/ - |- whitepaper.pdf - |- demo-video.mp4 -``` - -文件从你的 domain 根目录提供,因此存储库中的结构会直接映射到 URL 结构。延续前面的示例,`assets/whitepaper.pdf` 可通过 `https://docs.your-project.com/assets/whitepaper.pdf` 访问。 diff --git a/zh/editor/branches.mdx b/zh/editor/branches.mdx deleted file mode 100644 index 60a3a1009..000000000 --- a/zh/editor/branches.mdx +++ /dev/null @@ -1,42 +0,0 @@ ---- -title: "使用 branch 协作" -description: "使用 branch 在不影响线上文档的情况下进行更改与评审" ---- - -branch 是版本控制中的一项功能,用于指向你存储库中的特定提交。你的部署用分支,通常称为 `main`,代表用于构建线上文档的内容。除非你选择将它们合并到部署用分支,否则所有其他 branch 都与线上文档相互独立。 - -使用 branch 可以为文档创建独立环境,以便进行更改、接受评审,并在发布前尝试新方案。你的团队可以在各自的 branch 上并行更新文档的不同部分;在你发布更改之前,不会影响用户在你的线上站点上看到的内容。 - -我们建议在更新文档时始终基于 branch 工作,以保持线上站点稳定并启用评审工作流。 - - - - 清晰命名 branch,便于队友了解你的工作内容。 - - 合并后删除 branch,保持存储库整洁。 - - 当你在进行可能影响他人工作的重大更改时,请提前告知团队。 - - -
- ## 创建分支 -
- -1. 在编辑器工具栏中选择分支名称(通常默认为 `main`)。 -2. 选择 **New Branch**。 -3. 为你的分支输入一个具有描述性的名称,例如 `update-getting-started` 或 `fix-api-examples`。 -4. 选择 **Create Branch**。 - -
- ## 在 branch 上保存更改 -
- -要在 branch 上保存更改,请在编辑器右上角选择 **保存更改** 按钮。此操作会创建一次提交,并将你的工作推送到该 branch。 - -
- ## 切换 branch -
- -1. 在编辑器工具栏中选择 branch 名称。 -2. 从下拉菜单中选择要切换的 branch。 - - - 切换 branch 时,未保存的更改将会丢失。请在切换 branch 之前先保存或发布你的工作。 - \ No newline at end of file diff --git a/zh/editor/git-concepts.mdx b/zh/editor/git-concepts.mdx deleted file mode 100644 index 236316387..000000000 --- a/zh/editor/git-concepts.mdx +++ /dev/null @@ -1,66 +0,0 @@ ---- -title: "Git 概念" -description: "学习适用于 docs-as-code 工作流的 Git 基础知识" ---- - -Git 是一种版本控制系统,可用于跟踪文档变更并与团队成员协作。借助 Git,你可以查看项目中每个文件的变更内容、时间和原因;如有需要,也能轻松回退到文件的早期版本。 - -网页版编辑器在后台会执行部分 Git 操作。理解这些概念将帮助你更高效地使用网页版编辑器,并与在本地开发环境中工作的团队成员更好地协作。 - -
- ## 核心 Git 概念 -
- - - - 你的文档源码所在处,存放所有文件及其变更历史。Web 编辑器会连接到你的存储库以访问并修改内容。 - - - - 在特定时间点保存的更改快照。每次提交都包含描述变更内容的消息,并在项目历史中留下永久记录。 - - - - 一个 branch 指向你存储库中的特定提交。在线文档由部署用分支构建。你可以拥有任意数量的其他分支,其上的更改尚未发布到线上文档。若要将某个分支的更改纳入线上文档,可通过拉取请求将该分支合并到部署用分支。 - - 使用分支可在不影响线上文档的情况下开展更改,安全试验新功能,并在发布前完成评审。 - - - - 项目的主要分支,线上文档内容由此分支构建。对此分支的更改会自动发布到文档站点。通常命名为 `main`,但你可以将任意分支设为部署用分支。 - - - - 将分支上的更改提议合并到线上文档的一种方式。支持在更改上线前进行评审与讨论。通常称为 PR,在 GitLab 中也称为合并请求。 - - - - diff(差异)用于展示文件两个版本之间的更改。在审查拉取请求时,diff 会高亮显示新增、删除或修改的内容,便于识别变化。 - - - -
- ## Web 编辑器如何使用 Git -
- -Web 编辑器通过 [GitHub 应用](/zh/settings/github) 或 [GitLab 集成](/zh/settings/gitlab) 连接到你的 Git 存储库,并自动执行常见的 Git 操作。 - -当你: - -* **打开文件**:编辑器会从你的存储库获取最新版本,确保你始终处理的是最新内容。 -* **进行更改**:编辑器会将你的更改作为草稿进行跟踪,当你准备好保存时,该草稿会成为一次提交。 -* **保存更改**:编辑器会用你的更改创建一次提交,将其保存在项目历史中。 -* **创建一个 branch**:编辑器会在你的存储库中创建一个新的 branch,具有存储库访问权限的任何人都可以使用它来协作和审阅更改。 -* **在你的部署用分支上发布**:编辑器会直接向你的部署用分支提交并推送,从而立即发布你的更改。 -* **在其他分支上发布**:编辑器会创建一个拉取请求(PR;亦称“合并请求”/Merge Request),让你在将更改合并到部署用分支之前先获取他人的反馈。 - -
- ## Git 最佳实践 -
- -每个团队都会形成自己的工作流程和偏好,但以下是一些通用的最佳实践,帮助你上手。 - -* **编写清晰的提交信息**:用主动语态具体说明修改了什么。 -* **使用具描述性的 branch 名称**:branch 名称应能说明所做的工作,并让查看你存储库的人一目了然。 -* **保持 branch 聚焦**:让一个 branch 上的更改专注于某个具体任务或项目。 -* **合并后删除 branch**:不再需要时删除 branch,保持存储库整洁。 \ No newline at end of file diff --git a/zh/guides/assistant.mdx b/zh/guides/assistant.mdx deleted file mode 100644 index 9376e7e91..000000000 --- a/zh/guides/assistant.mdx +++ /dev/null @@ -1,156 +0,0 @@ ---- -title: "AI 助手" -description: "帮助用户更好地使用你的产品,并更快找到答案" -icon: "bot" ---- - - - AI 助手会在 [Pro 和 Custom 方案](https://mintlify.com/pricing?ref=assistant)中自动启用。 - - -
- ## 关于 AI 助手 -
- -AI 助手通过自然语言 query 回答与你的文档相关的问题。它直接嵌入到你的文档站点中,为用户提供即时的上下文帮助。 - -AI 助手采用具备工具调用的 agentic RAG(检索增强生成),由 Claude Sonnet 4 提供支持。当用户提问时,AI 助手会: - -* **搜索并检索** 你的文档中的相关内容,提供准确答案。 -* **引用出处** 并提供可导航的链接,直接带用户前往被引用的页面。 -* **生成可复制的代码示例**,帮助用户根据你的文档实现解决方案。 - -发送给 AI 助手的每条消息都会计入你的套餐消息额度。若超出额度,额外消息将产生超额费用。你可以设置支出上限,或在达到额度时禁用 AI 助手。 - -你可以在控制台查看 AI 助手的使用情况,从而了解用户行为和文档效果。导出并分析 query 数据,以帮助识别: - -* 可能需要更充分覆盖的常见问题。 -* 用户难以找到答案的内容空白。 -* 适合补充更多内容的热门主题。 - -
- ## 配置 AI 助手 -
- -AI 助手在 Pro 和 Custom 方案中默认启用。你可以在[控制台](https://dashboard.mintlify.com/products/assistant/settings)管理 AI 助手,包括启用或禁用、配置响应处理,以及设置支出上限。 - -
- ### AI 助手状态 -
- -切换 AI 助手状态,以在你的文档站点上启用或禁用 AI 助手。 - -
- ### AI 助手分流 -
- -启用 AI 助手在无法解答时将问题转交给你的支持团队。提供一个电子邮箱地址,AI 助手在无法回答用户提问时会将该地址提供给用户。 - -
- ### 搜索站点 -
- - - 站点搜索目前为测试版。要为你的文档站点启用该功能,请[联系销售团队](mailto:gtm@mintlify.com)。 - - -配置 AI 助手在回答问题时可检索的站点,以获取更多上下文。 - -* 站点必须对公众可访问。 -* 需要 JavaScript 才能加载内容的站点不受支持。 - -在配置外部站点时,你可以使用以下过滤语法: - -* **域级过滤** - * `example.com`:仅搜索 `example.com` domain - * `docs.example.com`:仅搜索 `docs.example.com` 子域 - * `*.example.com`:搜索 `example.com` 的所有子域 -* **路径级过滤** - * `docs.example.com/api`:搜索 `/api` 子路径下的所有页面 -* **多重模式** - * 可添加多个条目以覆盖站点的不同部分 - -
- ### 支出上限 -
- -设置支出上限,以控制在达到消息配额时的处理方式。默认情况下,即使你已用尽消息配额,AI 助手仍会继续回答用户问题,从而产生超额费用。 - -在 [Assistant Configurations](https://dashboard.mintlify.com/products/assistant/settings) 页面的 **Billing** 标签页中,你可以为超出配额的 AI 助手消息设置支出上限。当达到支出上限时,AI 助手将被禁用,直到你的消息配额重置。 - -你还可以设置用量提醒,在达到支出上限的指定百分比时接收电子邮件通知。 - -
- ## 使用 AI 助手 -
- -用户可以通过三种方式使用 AI 助手: - -* **键盘快捷键**:Command + I(Windows 上为 Ctrl + I) -* 搜索栏旁边的 **Assistant 按钮** - 浅色模式下的搜索栏和助手按钮。 - 深色模式下的搜索栏和助手按钮。 -* 在 **URL** 末尾添加 `?assistant=open`,页面加载时会自动打开 AI 助手。例如,[https://mintlify.com/docs?assistant=open](https://mintlify.com/docs?assistant=open)。 - -上述任一方式都会在文档右侧打开聊天面板。用户可以提出任何问题,AI 助手会在你的文档中搜索答案;如果未找到相关信息,AI 助手会提示无法回答该问题。 - -
- ## 让内容便于 AI 读取与理解 -
- -组织你的文档,以帮助 AI 助手提供准确、相关的答案。清晰的结构与完善的上下文同时有利于读者和 AI 的理解。 - - - * 使用语义化标记。 - * 为各部分撰写具有描述性的标题。 - * 建立清晰、合理的信息层级。 - * 在文档中保持一致的格式。 - * 在页面 frontmatter 中包含完整的 metadata。 - * 将长文本拆分为更短的段落。 - - - - * 首次出现时定义特定术语和首字母缩略词。 - * 提供关于功能与流程的充分概念性内容。 - * 包含示例和用例。 - * 交叉引用相关主题。 - * 添加包含额外上下文的[隐藏页面](/zh/guides/hidden-pages),这些内容用户不需要,但 AI 助手可以引用。 - - -
- ## 导出与分析查询 -
- -在控制台中审阅并导出查询,以了解用户如何与文档交互并识别改进机会。通过分析查询,你可以: - -* 识别高频查询却答案不足的内容缺口。 -* 从查询中的主题与模式中发现用户行为规律和常见信息需求。 -* 为高流量页面的准确性与质量提升设定优先级。 - -你可以在[控制台](https://dashboard.mintlify.com/products/assistant)中查看查询,但为了获得更深入的洞察,建议导出包含查询、回复和来源的 `CSV` 文件,并用你偏好的 AI 工具进行分析。 - -1. 在控制台前往 [AI 助手页面](https://dashboard.mintlify.com/products/assistant)。 -2. 选择 **Export to CSV**。 -3. 使用你偏好的工具分析导出的数据。 - - - * 概括查询中最常见的主题。 - * 列出未引用任何来源的查询。 - * 找出未成功交互中的模式。 - \ No newline at end of file diff --git a/zh/guides/changelogs.mdx b/zh/guides/changelogs.mdx deleted file mode 100644 index 5ad17074d..000000000 --- a/zh/guides/changelogs.mdx +++ /dev/null @@ -1,146 +0,0 @@ ---- -title: "更新日志" -description: "在文档中发布产品更新,并提供可订阅的 RSS 源" -icon: "newspaper" ---- - -在页面中添加[Update 组件](/zh/components/update),即可为文档创建更新日志。 - -查看 [Mintlify 更新日志](/zh/changelog) 作为示例:你可以在每次更新中加入链接、图片、文本,以及新功能演示。 - -
- ## 设置更新日志 -
- - - - 1. 在文档中创建一个新页面,例如 `changelog.mdx` 或 `updates.mdx`。 - 2. 将该更新日志页面添加到 `docs.json` 的 navigation 配置中。 - - - - 为每条更新记录添加一个 `Update`。 - - 包含相关信息,例如功能发布、缺陷修复或其他公告。 - - - -```mdx Example changelog.mdx ---- -title: "更新日志" -description: "产品更新和公告" ---- - - 新增冬青薄荷口味。 - - 绿薄荷口味发布新版本,薄荷含量提升10%。 - - - - 绿薄荷口味发布新版本。 - -``` - -
- ## 自定义更新日志 -
- -控制读者如何浏览你的更新日志,并随时掌握产品动态。 - -
- ### 目录 -
- -每个 `Update` 的 `label` 属性都会在右侧边栏的目录中自动创建一个条目。这是更新日志的默认导航方式。 - - - 浅色模式下显示目录的更新日志。 - - 深色模式下显示目录的更新日志。 - - -
- ### 标签筛选 -
- -在 `Update` 组件中添加 `tags`,即可用标签筛选替代目录。用户可以通过选择一个或多个标签来筛选更新日志: - -```mdx Tag filters example wrap - - 添加了新的 Wintergreen 口味。 - - 发布了新版本的 Spearmint 口味,现在薄荷含量增加了 10%。 - - - - 发布了新版本的 Spearmint 口味。 - - - - 已废弃 Peppermint 口味。 - - 发布了新版本的 Spearmint 口味。 - -``` - - - 浅色模式下的更新日志,已选择 Peppermint 标签筛选器。 - - 深色模式下的更新日志,已选择 Peppermint 标签筛选器。 - - - - 当使用 `custom`、`center` 或 `wide` 页面模式时,目录和更新日志筛选器将被隐藏。了解更多[页面模式](/zh/pages#page-mode)。 - - -
- ### 可订阅的更新日志 -
- -使用 `Update` 组件会在页面的 URL 后追加 `/rss.xml`,从而创建一个可订阅的 RSS 源。例如:`mintlify.com/docs/changelog/rss.xml`。 - -当发布新的 `Update` 组件,或在现有的 `` 标签内新增标题时,RSS 源会新增条目。 - -`Update` 组件的顶级标题将作为 RSS 源条目的标题,且这些条目会链接到文档中对应标题的锚点。 - -```xml Example RSS feed - - - - <![CDATA[产品更新]]> - - https://mintlify.com/docs - RSS for Node - Mon, 21 Jul 2025 21:21:47 GMT - - - https://mintlify.com/docs - - <![CDATA[2025年6月]]> - https://mintlify.com/docs/changelog#june-2025 - https://mintlify.com/docs/changelog#june-2025 - Mon, 23 Jun 2025 16:54:22 GMT - - - -``` - -RSS 源可以与 Slack、电子邮件或其他订阅工具集成,用于通知用户产品更新。可选项包括: - -* [Slack](https://slack.com/help/articles/218688467-Add-RSS-feeds-to-Slack) -* 通过 Zapier 的 [Email](https://zapier.com/apps/email/integrations/rss/1441/send-new-rss-feed-entries-via-email) -* 像 [Readybot](https://readybot.io) 或 [RSS Feeds to Discord Bot](https://rss.app/en/bots/rssfeeds-discord-bot) 这样的 Discord 机器人 - -为便于发现 RSS 源,你可以在页面顶部显示一个链接到该源的 RSS icon 按钮。在页面 frontmatter 中添加 `rss: true`: - -```mdx ---- -rss: true ---- -``` - - - 浅色模式的更新日志页面,已启用 RSS 订阅按钮。 - - 深色模式的更新日志页面,已启用 RSS 订阅按钮。 - diff --git a/zh/guides/csp-configuration.mdx b/zh/guides/csp-configuration.mdx deleted file mode 100644 index 15e28ac61..000000000 --- a/zh/guides/csp-configuration.mdx +++ /dev/null @@ -1,157 +0,0 @@ ---- -title: "内容安全策略(CSP)配置" -sidebarTitle: "CSP 配置" -description: "面向实施严格安全策略的反向代理、防火墙和网络的 domain 白名单与响应头配置" ---- - -内容安全策略(CSP)是一项安全标准,通过控制网页可加载的资源来帮助防止跨站脚本(XSS)攻击。Mintlify 默认提供 CSP,能保护大多数站点。如果你的文档托管在会覆盖默认 CSP 的反向代理或防火墙之后,你可能需要配置 CSP 响应头,确保相关功能正常运行。 - -
- ## CSP 指令 -
- -以下 CSP 指令用于控制可加载的资源: - -- `script-src`: 控制可执行的脚本 -- `style-src`: 控制可加载的样式表 -- `font-src`: 控制可加载的字体 -- `img-src`: 控制可加载的图像、icon 和徽标 -- `connect-src`: 控制可连接的 URL,用于 API 调用和 WebSocket 连接 -- `frame-src`: 控制可在 frame 或 iframe 中嵌入的 URL -- `default-src`: 其他指令未显式设置时的回退项 - -
- ## 域名白名单 -
- -| 域名 | 用途 | CSP 指令 | 必需 | -|:-------|:--------|:--------------|:-------| -| `d4tuoctqmanu0.cloudfront.net` | KaTeX CSS、字体 | `style-src`、`font-src` | 必需 | -| `*.mintlify.dev` | 文档内容 | `connect-src`、`frame-src` | 必需 | -| `*.mintlify.com` | 控制台、API、Analytics 代理 | `connect-src` | 必需 | -| `leaves.mintlify.com` | AI 助手 API | `connect-src` | 必需 | -| `d3gk2c5xim1je2.cloudfront.net` | 图标、图像、标志 | `img-src` | 必需 | -| `d1ctpt7j8wusba.cloudfront.net` | Mint 版本与发布文件 | `connect-src` | 必需 | -| `mintcdn.com` | 图像、网站图标(favicon) | `img-src`、`connect-src` | 必需 | -| `*.mintcdn.com` | 图像、网站图标(favicon) | `img-src`、`connect-src` | 必需 | -| `api.mintlifytrieve.com` | 搜索 API | `connect-src` | 必需 | -| `cdn.jsdelivr.net` | 用于 OG 图片的表情符号资源 | `script-src`、`img-src` | 必需 | -| `fonts.googleapis.com` | Google Fonts | `style-src`、`font-src` | 可选 | -| `www.googletagmanager.com` | Google Analytics/GTM | `script-src`、`connect-src` | 可选 | -| `cdn.segment.com` | Segment 分析 | `script-src`、`connect-src` | 可选 | -| `plausible.io` | Plausible 分析 | `script-src`、`connect-src` | 可选 | -| `us.posthog.com` | PostHog 分析 | `connect-src` | 可选 | -| `cdn.getkoala.com` | Koala 分析 | `script-src` | 可选 | -| `tag.clearbitscripts.com` | Clearbit 追踪 | `script-src` | 可选 | -| `cdn.heapanalytics.com` | Heap 分析 | `script-src` | 可选 | -| `chat.cdn-plain.com` | Plain 聊天小部件 | `script-src` | 可选 | -| `chat-assets.frontapp.com` | Front 聊天小部件 | `script-src` | 可选 | -| `browser.sentry-cdn.com` | Sentry 错误追踪 | `script-src`、`connect-src` | 可选 | -| `js.sentry-cdn.com` | Sentry JavaScript SDK | `script-src` | 可选 | - -
- ## 示例 CSP 配置 -
- - - 只包含你实际使用的服务的 domain。删除你尚未为文档配置的任何 Analytics 域名。 - - -```text wrap -Content-Security-Policy: -default-src 'self'; -script-src 'self' 'unsafe-inline' 'unsafe-eval' cdn.jsdelivr.net www.googletagmanager.com cdn.segment.com plausible.io -us.posthog.com cdn.getkoala.com tag.clearbitscripts.com cdn.heapanalytics.com chat.cdn-plain.com chat-assets.frontapp.com -browser.sentry-cdn.com js.sentry-cdn.com; -style-src 'self' 'unsafe-inline' d4tuoctqmanu0.cloudfront.net fonts.googleapis.com; -font-src 'self' d4tuoctqmanu0.cloudfront.net fonts.googleapis.com; -img-src 'self' data: blob: d3gk2c5xim1je2.cloudfront.net mintcdn.com *.mintcdn.com cdn.jsdelivr.net; -connect-src 'self' *.mintlify.dev *.mintlify.com d1ctpt7j8wusba.cloudfront.net mintcdn.com *.mintcdn.com -api.mintlifytrieve.com www.googletagmanager.com cdn.segment.com plausible.io us.posthog.com browser.sentry-cdn.com; -frame-src 'self' *.mintlify.dev; -``` - - -
- ## 按代理类型分类的常见配置 -
- -大多数反向代理都支持添加自定义请求头。 - -
- ### Cloudflare 配置 -
- -创建一个 Response Header Transform 规则: - -1. 在你的 Cloudflare 控制台中,进入 **Rules > Overview**。 -2. 选择 **Create rule > Response Header Transform Rule**。 -3. 配置该规则: - -- **Modify response header**:设置为 Static - - **Header name**:`Content-Security-Policy` - - **Header value**: - ```text wrap - default-src 'self'; script-src 'self' 'unsafe-inline' 'unsafe-eval' cdn.jsdelivr.net; style-src 'self' 'unsafe-inline' d4tuoctqmanu0.cloudfront.net fonts.googleapis.com; font-src 'self' d4tuoctqmanu0.cloudfront.net fonts.googleapis.com; img-src 'self' data: blob: d3gk2c5xim1je2.cloudfront.net mintcdn.com *.mintcdn.com cdn.jsdelivr.net; connect-src 'self' *.mintlify.dev *.mintlify.com d1ctpt7j8wusba.cloudfront.net mintcdn.com *.mintcdn.com api.mintlifytrieve.com; frame-src 'self' *.mintlify.dev; - ``` - -4. 部署该规则。 - -
- ### 配置 AWS CloudFront -
- -在 CloudFront 中添加一个响应标头策略: - -```json -{ -"ResponseHeadersPolicy": { - "Name": "MintlifyCSP", - "Config": { - "SecurityHeadersConfig": { - "ContentSecurityPolicy": { - "ContentSecurityPolicy": "default-src 'self'; script-src 'self' 'unsafe-inline' 'unsafe-eval' cdn.jsdelivr.net; style-src 'self' 'unsafe-inline' d4tuoctqmanu0.cloudfront.net fonts.googleapis.com; font-src 'self' d4tuoctqmanu0.cloudfront.net fonts.googleapis.com; img-src 'self' data: blob: d3gk2c5xim1je2.cloudfront.net mintcdn.com *.mintcdn.com cdn.jsdelivr.net; connect-src 'self' *.mintlify.dev *.mintlify.com d1ctpt7j8wusba.cloudfront.net mintcdn.com *.mintcdn.com api.mintlifytrieve.com; frame-src 'self' *.mintlify.dev;", - "Override": true - } - } - } - } -} -``` - - -
- ### Vercel 配置 -
- -将以下内容添加到你的 `vercel.json`: - -```json -{ -"headers": [ - { - "source": "/(.*)", - "headers": [ - { - "key": "Content-Security-Policy", - "value": "default-src 'self'; script-src 'self' 'unsafe-inline' 'unsafe-eval' cdn.jsdelivr.net; style-src 'self' 'unsafe-inline' d4tuoctqmanu0.cloudfront.net fonts.googleapis.com; font-src 'self' d4tuoctqmanu0.cloudfront.net fonts.googleapis.com; img-src 'self' data: blob: d3gk2c5xim1je2.cloudfront.net mintcdn.com *.mintcdn.com cdn.jsdelivr.net; connect-src 'self' *.mintlify.dev *.mintlify.com d1ctpt7j8wusba.cloudfront.net mintcdn.com *.mintcdn.com api.mintlifytrieve.com; frame-src 'self' *.mintlify.dev;" - } - ] - } - ] -} -``` - - -
- ## 疑难排解 -
- -在浏览器控制台中定位 CSP 违规: - -1. 打开浏览器的开发者工具。 -2. 切换到 **Console** 标签页。 -3. 查找以下前缀的错误: - - `Content Security Policy: The page's settings blocked the loading of a resource` - - `Refused to load the script/stylesheet because it violates the following Content Security Policy directive` - - `Refused to connect to because it violates the following Content Security Policy directive` \ No newline at end of file diff --git a/zh/guides/deployments.mdx b/zh/guides/deployments.mdx deleted file mode 100644 index f761baa15..000000000 --- a/zh/guides/deployments.mdx +++ /dev/null @@ -1,31 +0,0 @@ ---- -title: "部署" -description: "排查部署问题" -icon: "boxes" ---- - -当你将更改推送到已连接的存储库时,文档站点会自动部署。这需要正确安装并连接 Mintlify GitHub 应用。 - -如果最新更改没有出现在线上站点上,请先检查拥有你的文档存储库的账户或组织是否已安装 GitHub 应用。更多信息参见[GitHub 故障排查](/zh/settings/github#troubleshooting)。 - -如果 GitHub 应用已连接,但更改仍未部署,你可以在控制台手动触发重新构建。 - -
- ## 手动触发部署 -
- - - - 检查你的最新提交是否已出现在文档存储库中,且未出现任何错误。 - - - - 前往你的[控制台](https://dashboard.mintlify.com)并点击“部署”按钮。 - - - 用橙色矩形标出的“手动更新”按钮。 - - 用橙色矩形标出的“手动更新”按钮。 - - - diff --git a/zh/guides/hidden-page-example.mdx b/zh/guides/hidden-page-example.mdx deleted file mode 100644 index 8e0c60536..000000000 --- a/zh/guides/hidden-page-example.mdx +++ /dev/null @@ -1,61 +0,0 @@ ---- -title: "隐藏页面示例" -description: "隐藏页面的常见用法" -icon: "eye-off" ---- - -此页面是隐藏的!它未包含在 `docs.json` 的 navigation 中,因此你只能通过其 URL 访问。 - -更多信息请参见[隐藏页面](/zh/guides/hidden-pages)。 - -
- ## 隐藏页面的常见用例 -
- - - 默认情况下,隐藏页面可公开访问,但不会通过导航被发现。若要限制对隐藏页面的访问,必须配置[认证](/zh/authentication-personalization/authentication-setup)。 - - -* **测试版文档**:可以公开,但不应通过导航被发现的信息。 -* **供 AI 工具使用的上下文**:如果隐藏页面被索引,AI 工具可以将其作为上下文引用。将对用户不相关、但有助于 AI 工具提供更准确回答的上下文放在隐藏页面中。 -* **遗留页面**:通过直接链接保留旧内容的可访问性,同时将其从导航菜单中移除。 -* **内部工具**:为内部工具、预发布环境的 API 或开发流程编写文档。 - -
- ## 示例 -
- -
- ### AI context -
- -```mdx wrap ---- -title: "API 版本的上下文" -description: "此页面为 AI 工具回答有关 API 版本问题提供上下文" ---- - -当用户询问 API 版本时,始终建议他们使用最新版本的 API。永远不要为 1.0.4 之前的版本生成响应。 -``` - -
- ### 内部 API 终端点 -
- -````mdx wrap ---- -title: "内部 API 端点" -description: "此页面是记录内部 API 端点的隐藏页面" ---- - -```bash -POST /api/internal/reset-cache -Authorization: Bearer internal-token-xyz -``` - -此端点用于清除应用程序缓存,仅在开发环境中可用。 - - - 这是一个内部端点,绝不应在生产环境中使用。 - -```` diff --git a/zh/guides/hidden-pages.mdx b/zh/guides/hidden-pages.mdx deleted file mode 100644 index 901288994..000000000 --- a/zh/guides/hidden-pages.mdx +++ /dev/null @@ -1,88 +0,0 @@ ---- -title: "隐藏页面" -description: "从导航中排除页面" -icon: "eye-closed" ---- - -隐藏页面会从你站点的导航中移除,但任何知道其 URL 的人仍可公开访问。 - -当你希望某些内容在站点上可访问,或作为 AI 工具的上下文被引用,但又不希望通过导航被发现时,请使用隐藏页面。 - -对于需要严格访问控制的内容,必须配置[认证](/zh/authentication-personalization/authentication-setup)。 - -如果你想仅对特定用户群体隐藏页面,请使用个性化来控制[页面可见性](/zh/authentication-personalization/overview#page-visibility)。 - -
- ## 隐藏页面 -
- -如果某个页面未包含在你的 `docs.json` 导航中,则该页面会被隐藏。要隐藏页面,请将其从导航结构中移除。 - -隐藏页面会根据其文件路径使用与常规页面相同的 URL 结构。例如,`guides/hidden-page.mdx` 可通过 `docs.yoursite.com/guides/hidden-page` 访问。 - -查看[隐藏页面示例](/zh/guides/hidden-page-example)。 - - - 某些导航元素(如侧边栏、下拉菜单和选项卡)在隐藏页面上可能会显示为空或导致布局变化。 - - -
- ## 隐藏一组页面 -
- -在 `docs.json` 文件中将 `hidden` 属性设为 `true` 时,该页面组会被隐藏: - -```json highlight={4} -"groups": [ - { - "group": "快速开始", - "hidden": true, - "pages": [ - "index", - "quickstart" - ] - }, - { - "group": "指南", - "pages": [ - "guides/hidden-page.mdx", - "guides/hidden-groups.mdx" - ] - } -] -``` - -在此示例中,`Getting started` 分组被隐藏,而 `Guides` 分组可见。 - -
- ### 隐藏标签页 -
- -你也可以在 `docs.json` 文件中添加 `hidden` 属性来隐藏某个标签页: - -```json highlight={4} -"tabs": [ - { - "tab": "首页", - "hidden": true, - "pages": [ - "index", - "quickstart" - ] - } -] -``` - -
- ## 搜索、SEO(搜索引擎优化)和 AI 索引编入 -
- -默认情况下,隐藏页面不会被编入索引(包括搜索引擎、文档站点内搜索,以及提供给 AI 助手的上下文)。如需将隐藏页面包含在搜索结果中,并作为 AI 助手的上下文使用,请在你的 `docs.json` 中添加 `seo` 属性: - -```json -"seo": { - "indexing": "all" -} -``` - -要排除某个页面,请在其 frontmatter 中添加 `noindex: true`。 diff --git a/zh/guides/migration.mdx b/zh/guides/migration.mdx deleted file mode 100644 index 7c66d7251..000000000 --- a/zh/guides/migration.mdx +++ /dev/null @@ -1,201 +0,0 @@ ---- -title: "迁移" -description: "如何将你当前平台上的文档迁移过来" -icon: "import" ---- - -本指南将帮助你把现有文档迁移到 Mintlify。对于受支持的平台,你可以选择自动迁移;若需要对整个流程进行完全掌控,则可选择手动迁移。 - -
- ## 选择迁移路径 -
- - - - 如果你正在从 Docusaurus、ReadMe 或 GitBook 迁移,可使用我们的工具实现自动迁移。 - - - - 如果你正在从其他平台迁移,请按照我们的指南迁移你的内容。 - - - - - - 使用 [@mintlify/scraping 包](https://www.npmjs.com/package/@mintlify/scraping) 迁移您的文档。该包会抓取您的内容并将其转换为使用 Mintlify 组件。 - - ### 支持的平台 - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -} - horizontal - /> - - - -} - horizontal - /> - - - -} - horizontal - /> - - - 如果您的文档托管在其他平台上,请查看手动迁移步骤。 - - ### 安装爬虫工具 - - 安装 `@mintlify/scraping` 包来开始。 - - ```bash - npm install @mintlify/scraping@latest -g - ``` - - ### 抓取页面和章节 - - 迁移工具会自动检测您的文档平台并转换您的内容。准备好的文件默认存储在本地的 `./docs` 中。 - - 对于大型文档站点,建议分批迁移较小的部分,而不是一次性迁移整个站点。 - - **迁移整个章节:** - - ```bash - mintlify-scrape section https://your-docs-site.com/docs - ``` - - **迁移单个页面:** - - ```bash - mintlify-scrape page https://your-docs-site.com/docs/getting-started - ``` - - **迁移 OpenAPI 规范:** - - ```bash - mintlify-scrape openapi-file [openApiFilename] - ``` - - ### 将准备好的内容添加到您的 Mintlify 项目中 - - 在抓取现有文档平台的内容后,您就可以在 Mintlify 上构建文档了。 - - 确认所有页面都已迁移完成,然后将这些文件添加到您在入门过程中创建的文档存储库中。这通常是一个 GitHub 存储库。 - - - - 在完全掌控流程的情况下,从任意平台迁移你的文档。 - - ### 内容迁移 - - 要将内容迁移到 Mintlify,你需要: - - * 一个有效的 `docs.json` 用于站点设置和导航。参见 [Global settings](/zh/settings) 和 [Navigation](/zh/navigation) 了解更多信息。 - * 每个文档页面对应一个 `MDX` 文件。参见 [Pages](/zh/pages) 了解更多信息。 - * (可选)用于 API 端点页面的 OpenAPI 规范。参见 [OpenAPI setup](/zh/api-playground/openapi-setup) 了解更多信息。 - - 1. 如果内容已是 `MDX` 格式,将页面复制到你的 Mintlify 项目;否则,将内容转换为 `MDX` 格式。 - 2. 创建 `docs.json`,并引用 `MDX` 页面路径。 - 3. 如果有 OpenAPI 规范,将其添加到 `docs.json` 并配置 API 操作台。 - - ### 资源迁移 - - 1. 将资源复制到存储库的 `images/` 目录。 - 2. 更新 `MDX` 文件中的引用: - ```mdx - ![Alt text](/images/screenshot.png) - ``` - - - -
- ## 迁移后检查清单 -
- -完成迁移(自动或手动)后,建议检查: - -* 所有页面均能正常渲染 -* 导航按预期工作 -* 内部链接能正确解析 -* 图片和资源加载正常 -* 代码块语法高亮显示正常 -* 搜索功能可用 -* 部署已配置 -* 已设置自定义域名 diff --git a/zh/guides/monorepo.mdx b/zh/guides/monorepo.mdx deleted file mode 100644 index 843d3415f..000000000 --- a/zh/guides/monorepo.mdx +++ /dev/null @@ -1,51 +0,0 @@ ---- -title: "Monorepo 设置" -description: "从包含多个项目的仓库部署你的文档" -icon: "folder-git" ---- - -将 Mintlify 配置为从 monorepo 中的特定目录部署文档。此方案可让你在包含多个项目或服务的仓库中,将文档与代码并行维护。 - - - -
- ## 先决条件 -
- -* 你对 Mintlify 项目拥有管理员权限。 -* 文档文件已在 monorepo 中的独立目录内组织。 -* 文档目录中包含有效的 `docs.json` 文件。 - - - -
- ## 配置 monorepo 部署 -
- - - -在控制台中前往 [Git Settings](https://dashboard.mintlify.com/settings/deployment/git-settings)。 - - -Git Settings 菜单中的项目设置面板。Set up as monorepo 开关已启用,并指定了 /docs 目录的路径。 -Git Settings 菜单中的项目设置面板。Set up as monorepo 开关已启用,并指定了 /docs 目录的路径。 - - - - -1. 打开 **Set up as monorepo** 开关。 -2. 输入文档目录的相对路径。例如,如果文档位于 `docs` 目录,请输入 `/docs`。 - - 路径末尾不要包含斜杠。 - -3. 点击 **Save changes**。 - - diff --git a/zh/guides/reverse-proxy.mdx b/zh/guides/reverse-proxy.mdx deleted file mode 100644 index e6475a268..000000000 --- a/zh/guides/reverse-proxy.mdx +++ /dev/null @@ -1,160 +0,0 @@ ---- -title: "反向代理" -description: "配置自定义反向代理以为文档提供服务" ---- - - - 反向代理配置仅适用于 [Custom 方案](https://mintlify.com/pricing?ref=reverse-proxy)。 - - -要通过自定义反向代理为文档提供服务,您需要配置路由规则、缓存策略和请求头转发。 - -实施反向代理后,请留意可能出现的 domain 验证、SSL 证书签发、认证流程、性能以及 Analytics 追踪方面的问题。 - -
- ## 路由配置 -
- -将以下路径按指定缓存策略代理到你的 Mintlify 子域: - -| 路径 | 目标 | 缓存 | -|------|-------------|---------| -| `/.well-known/acme-challenge/*` | `.mintlify.app` | 不缓存 | -| `/.well-known/vercel/*` | `.mintlify.app` | 不缓存 | -| `/mintlify-assets/_next/static/*` | `.mintlify.app` | 启用缓存 | -| `/_mintlify/*` | `.mintlify.app` | 不缓存 | -| `/*` | `.mintlify.app` | 不缓存 | -| `/` | `.mintlify.app` | 不缓存 | - -
- ## 必填的请求头配置 -
- -按以下请求头要求配置你的反向代理: - -- **Origin**:包含目标子域 `.mintlify.app` -- **X-Forwarded-For**:保留客户端 IP 信息 -- **X-Forwarded-Proto**:保留原始协议(HTTP/HTTPS) -- **X-Real-IP**:转发真实的客户端 IP 地址 -- **User-Agent**:转发用户代理 - - - 确保不要转发 `Host` 请求头 - - -
- ## NGINX 配置示例 -
- -```nginx -server { - listen 80; - server_name .com; - - # Let's Encrypt 验证路径 - location ~ ^/\.well-known/acme-challenge/ { - proxy_pass https://.mintlify.app; - proxy_set_header Origin .mintlify.app; - proxy_set_header X-Real-IP $remote_addr; - proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; - proxy_set_header X-Forwarded-Proto $scheme; - proxy_set_header User-Agent $http_user_agent; - - # 禁用验证路径的缓存 - add_header Cache-Control "no-cache, no-store, must-revalidate"; - } - - # Vercel 验证路径 - location ~ ^/\.well-known/vercel/ { - proxy_pass https://.mintlify.app; - proxy_set_header Origin .mintlify.app; - proxy_set_header X-Real-IP $remote_addr; - proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; - proxy_set_header X-Forwarded-Proto $scheme; - proxy_set_header User-Agent $http_user_agent; - - # 禁用验证路径的缓存 - add_header Cache-Control "no-cache, no-store, must-revalidate"; - } - - # 带缓存的静态资源 - location ~ ^/mintlify-assets/_next/static/ { - proxy_pass https://.mintlify.app; - proxy_set_header Origin .mintlify.app; - proxy_set_header X-Real-IP $remote_addr; - proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; - proxy_set_header X-Forwarded-Proto $scheme; - proxy_set_header User-Agent $http_user_agent; - - # 启用静态资源缓存 - add_header Cache-Control "public, max-age=86400"; - } - - # Mintlify 特定路径 - location ~ ^/_mintlify/ { - proxy_pass https://.mintlify.app; - proxy_set_header Origin .mintlify.app; - proxy_set_header X-Real-IP $remote_addr; - proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; - proxy_set_header X-Forwarded-Proto $scheme; - proxy_set_header User-Agent $http_user_agent; - - # 禁用 Mintlify 路径的缓存 - add_header Cache-Control "no-cache, no-store, must-revalidate"; - } - - # 根路径 - location = / { - proxy_pass https://.mintlify.app; - proxy_set_header Origin .mintlify.app; - proxy_set_header X-Real-IP $remote_addr; - proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; - proxy_set_header X-Forwarded-Proto $scheme; - proxy_set_header User-Agent $http_user_agent; - - # 禁用动态内容的缓存 - add_header Cache-Control "no-cache, no-store, must-revalidate"; - } - - # 所有其他文档路径 - location / { - proxy_pass https://.mintlify.app; - proxy_set_header Origin .mintlify.app; - proxy_set_header X-Real-IP $remote_addr; - proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; - proxy_set_header X-Forwarded-Proto $scheme; - proxy_set_header User-Agent $http_user_agent; - - # 禁用动态内容的缓存 - add_header Cache-Control "no-cache, no-store, must-revalidate"; - } -} -``` - - -
- ## 故障排除 -
- -
- ### 404 错误 -
- -**症状**:文档能加载,但功能不可用。API 调用失败。 - -**原因**:转发了 `Host` 请求头,或缺少 `Origin` 请求头。 - -**解决方案**: - -- 停止转发 `Host` 请求头 -- 将 `Origin` 请求头设置为 `.mintlify.app` - -
- ### 性能问题 -
- -**症状**:页面加载缓慢并出现布局跳动。 - -**原因**:缓存配置不正确。 - -**解决方案**:仅为 `/mintlify-assets/_next/static/*` 路径启用缓存。 \ No newline at end of file diff --git a/zh/image-embeds.mdx b/zh/image-embeds.mdx deleted file mode 100644 index 070102ea5..000000000 --- a/zh/image-embeds.mdx +++ /dev/null @@ -1,194 +0,0 @@ ---- -title: "图像与嵌入" -description: "添加图像、视频和 iframe" -icon: "image" ---- - -在文档中添加图像、嵌入视频,并通过 iframe 包含交互式内容。 - - - 一张风景照片:前景是紫色花朵,远处是群山,天空蔚蓝点缀着疏散的云。 - - -
- ## 图像 -
- -向文档添加图像,以提供可视化的上下文、示例或装饰。 - -
- ### 基本图片语法 -
- -使用[Markdown 语法](https://www.markdownguide.org/basic-syntax/#images)向文档中添加图片: - -```mdx -![描述图像的替代文本](/path/to/image.png) -``` - - - 请务必添加具有描述性的替代文本,以提升无障碍性和 SEO(搜索引擎优化)。替代文本应清楚描述图像所呈现的内容。 - - -图像文件必须小于 20 MB。对于更大的文件,请将其托管在 CDN 服务上,例如 [Amazon S3](https://aws.amazon.com/s3) 或 [Cloudinary](https://cloudinary.com)。 - -
- ### HTML 图像嵌入 -
- -若需更精确地控制图像的显示效果,请使用 HTML 的 `` 标签: - -```html -主控制台界面 -``` - -
- #### 禁用缩放功能 -
- -若要禁用图片点击时的默认缩放,请添加 `noZoom` 属性: - -```html highlight="4" -描述性替代文本 -``` - - - -要让图片可点击并跳转,请将图片包裹在一个 a(锚点)标签中,并添加 `noZoom` 属性: - -```html - - Mintlify 徽标 - -``` - - - 放在 a(锚点)标签内的图像会自动显示指针形光标,表示它们可点击。 - - -
- #### 亮色和暗色模式的图像 -
- -要为亮色与暗色主题分别展示不同的图像,请使用 Tailwind CSS 类: - -```html - -浅色模式界面 - - -深色模式界面 -``` - -
- ## 视频 -
- -Mintlify 支持在 Markdown 中使用 [HTML 标签](https://www.markdownguide.org/basic-syntax/#html),让你能灵活创建丰富内容。 - - - 请始终在视频元素内提供备用文本内容,以便在不支持视频播放的浏览器中显示。 - - -
- ### 嵌入 YouTube 视频 -
- -使用 iframe 元素嵌入 YouTube 视频: - -```html - -``` - - - -``` - - - - - 了解如何使用 Frame 组件呈现图像。 - \ No newline at end of file diff --git a/zh/list-table.mdx b/zh/list-table.mdx deleted file mode 100644 index b27a19507..000000000 --- a/zh/list-table.mdx +++ /dev/null @@ -1,92 +0,0 @@ ---- -title: "列表与表格" -description: "以列表和表格呈现信息" -icon: "list" ---- - - - -
- ## 列表 -
- -列表遵循官方的[Markdown 语法](https://www.markdownguide.org/basic-syntax/#lists-1)。 - -
- ### 有序列表 -
- -要创建有序列表,请在每个列表项前加上数字并紧跟一个句点。 - -1. 第一项 -2. 第二项 -3. 第三项 -4. 第四项 - -```mdx -1. 第一项 -2. 第二项 -3. 第三项 -4. 第四项 -``` - -
- ### 无序列表 -
- -要创建无序列表,请在每个列表项前添加短横线(`-`)、星号(`*`)或加号(`+`)。 - -* 第一项 -* 第二项 -* 第三项 -* 第四项 - -```mdx -- 第一项 -- 第二项 -- 第三项 -- 第四项 -``` - -
- ### 嵌套列表 -
- -通过缩进列表项来实现嵌套。 - -* 第一项 -* 第二项 - * 子项 - * 子项 -* 第三项 - -```mdx -- 第一项 -- 第二项 - - 附加项 - - 附加项 -- 第三项 -``` - - -
- ## 表格 -
- -表格遵循官方的 [Markdown 语法](https://www.markdownguide.org/extended-syntax/#tables)。 - -要添加表格,使用三个或更多连字符(`---`)创建每一列的表头,并使用竖线(`|`)分隔各列。为兼容性起见,行首和行尾也应各添加一个竖线。 - -| 属性 | 说明 | -| -------- | ------------------------ | -| 名称 | 用户全名 | -| 年龄 | 用户填写的年龄 | -| 加入 | 用户是否已加入社区 | - -```mdx -| Property | 说明 | -| -------- | ------------------------------------- | -| Name | 用户全名 | -| Age | 年龄 | -| Joined | 用户是否已加入社区 | -``` diff --git a/zh/navigation.mdx b/zh/navigation.mdx deleted file mode 100644 index e8beb733c..000000000 --- a/zh/navigation.mdx +++ /dev/null @@ -1,619 +0,0 @@ ---- -title: "Navigation" -description: "构建并自定义文档的导航层级结构" -icon: "map" ---- - -`docs.json` 中的 [navigation](zh/settings#param-navigation) 属性用于控制文档的结构与信息层次。 - -通过合理的导航配置,你可以更好地组织内容,帮助用户快速找到他们需要的信息。 - -
- ## 页面 -
- -页面是导航中最基础的组成部分。每个页面对应构成文档的 MDX 文件。 - - - - - -在 `navigation` 对象中,`pages` 是一个数组,其中每个条目都必须引用一个[页面文件](zh/pages)的路径。 - -```json -{ - "navigation": { - "pages": [ - "settings", - "pages", - "navigation", - "themes", - "custom-domain" - ] - } -} -``` - -
- ## 组 -
- -使用组将侧边栏导航划分为多个部分。组可以彼此嵌套、添加标签,并设置图标样式。 - - - - - -在 `navigation` 对象中,`groups` 是一个数组,其中每个条目都是一个对象,且必须包含 `group` 和 `pages` 字段。`icon`、`tag` 和 `expanded` 字段为可选。 - -```json -{ - "navigation": { - "groups": [ - { - "group": "快速入门", - "icon": "play", - "expanded": false, - "pages": [ - "quickstart", - { - "group": "编辑", - "icon": "pencil", - "pages": [ - "installation", - "editor" - ] - } - ] - }, - { - "group": "编写内容", - "icon": "notebook-text", - "tag": "NEW", - "pages": [ - "writing-content/page", - "writing-content/text" - ] - } - ] - } -} -``` - -
- ### 默认展开状态 -
- -在某个分组上设置 `expanded: true`,即可使其在导航侧边栏中默认展开。这有助于突出重要部分,或提升关键内容的可发现性。 - -```json -{ - "group": "快速入门", - "expanded": true, - "pages": ["quickstart", "installation"] -} -``` - -
- ## 选项卡 -
- -选项卡可将文档划分为彼此独立的板块,每个板块都有自己的 URL 路径。它会在文档顶部生成一条水平导航栏,方便用户在不同板块之间切换。 - - - - - -在 `navigation` 对象中,`tabs` 是一个数组,其中每个条目是一个对象,必须包含 `tab` 字段,并且可以包含其他导航字段,例如 groups、pages、icon,或指向外部页面的链接。 - -```json -{ - "navigation": { - "tabs": [ - { - "tab": "API 参考", - "icon": "square-terminal", - "pages": [ - "api-reference/get", - "api-reference/post", - "api-reference/delete" - ] - }, - { - "tab": "SDK", - "icon": "code", - "pages": [ - "sdk/fetch", - "sdk/create", - "sdk/delete" - ] - }, - { - "tab": "博客", - "icon": "newspaper", - "href": "https://external-link.com/blog" - } - ] - } -} -``` - - - -菜单会为某个标签页添加下拉式导航项。使用菜单可帮助用户在该标签页内直接跳转到特定页面。 - -在 `navigation` 对象中,`menu` 是一个数组,其中每个条目都是一个对象,必须包含 `item` 字段,并且还可以包含其他导航相关字段,例如 groups、pages、icons,或指向外部页面的链接。 - -```json -{ - "navigation": { - "tabs": [ - { - "tab": "开发者工具", - "icon": "square-terminal", - "menu": [ - { - "item": "API 参考", - "icon": "rocket", - "groups": [ - { - "group": "核心端点", - "icon": "square-terminal", - "pages": [ - "api-reference/get", - "api-reference/post", - "api-reference/delete" - ] - } - ] - }, - { - "item": "SDK", - "icon": "code", - "description": "SDK 用于与 API 进行交互。", - "pages": [ - "sdk/fetch", - "sdk/create", - "sdk/delete" - ] - } - ] - } - ] - } -} -``` - -
- ## 锚点 -
- -锚点会在侧边栏顶部添加常驻的导航项。你可以用锚点为内容分区、提供快速访问外部资源,或创建醒目的行动号召。 - - - - - -在 `navigation` 对象中,`anchors` 是一个数组,其中每一项是一个对象,必须包含 `anchor` 字段,并且可以包含其他导航字段,例如 groups、页面、icon,或指向外部页面的链接。 - -```json -{ - "navigation": { - "anchors": [ - { - "anchor": "文档", - "icon": "book-open", - "pages": [ - "quickstart", - "development", - "navigation" - ] - }, - { - "anchor": "API 参考", - "icon": "square-terminal", - "pages": [ - "api-reference/get", - "api-reference/post", - "api-reference/delete" - ] - }, - { - "anchor": "博客", - "href": "https://external-link.com/blog" - } - ] - } -} -``` - -对于仅指向外部链接的锚点,请使用 `global` 关键字。位于 `global` 对象中的锚点必须包含 `href` 字段,且不能指向相对路径。 - -全局锚点特别适用于链接到不属于你的文档、但应让用户易于访问的资源,例如博客或支持门户。 - -```json -{ - "navigation": { - "global": { - "anchors": [ - { - "anchor": "社区", - "icon": "house", - "href": "https://slack.com" - }, - { - "anchor": "博客", - "icon": "pencil", - "href": "https://mintlify.com/blog" - } - ] - }, - "tabs": /*...*/ - } -} -``` - - - -下拉菜单位于侧边栏导航顶部的可展开菜单中。下拉菜单中的每个项目都会跳转到文档的某个部分。 - - - - - -在 `navigation` 对象中,`dropdowns` 是一个数组,其中每个条目都是一个对象,必须包含 `dropdown` 字段,并且可以包含其他导航字段,例如 groups、pages、icons,或指向外部页面的链接。 - -```json -{ - "navigation": { - "dropdowns": [ - { - "dropdown": "文档", - "icon": "book-open", - "pages": [ - "quickstart", - "development", - "navigation" - ] - }, - { - "dropdown": "API 参考", - "icon": "square-terminal", - "pages": [ - "api-reference/get", - "api-reference/post", - "api-reference/delete" - ] - }, - { - "dropdown": "博客", - "href": "https://external-link.com/blog" - } - ] - } -} -``` - -
- ## OpenAPI -
- -将 OpenAPI 规范直接集成到你的导航结构中,自动生成 API 文档。你可以创建专门的 API 部分,或将端点页面放入其他导航组件中。 - -可在导航层级的任意层级设置默认 OpenAPI 规范。子元素会继承该规范,除非它们另行定义。 - -```json -{ - "navigation": { - "groups": [ - { - "group": "API 参考", - "openapi": "/path/to/openapi-v1.json", - "pages": [ - "overview", - "authentication", - "GET /users", - "POST /users", - { - "group": "产品", - "openapi": "/path/to/openapi-v2.json", - "pages": [ - "GET /products", - "POST /products" - ] - } - ] - } - ] - } -} -``` - -有关在文档中引用 OpenAPI 端点的更多信息,请参阅 [OpenAPI 设置](/zh/api-playground/openapi-setup)。 - -
- ## 版本 -
- -将导航划分为不同版本。可以通过下拉菜单进行选择。 - - - - - -在 `navigation` 对象中,`versions` 是一个数组,其中每个项都是一个对象,必须包含 `version` 字段,并且可以包含其他任意导航字段。 - -```json -{ - "navigation": { - "versions": [ - { - "version": "1.0.0", - "groups": [ - { - "group": "快速入门", - "pages": ["v1/overview", "v1/quickstart", "v1/development"] - } - ] - }, - { - "version": "2.0.0", - "groups": [ - { - "group": "快速入门", - "pages": ["v2/overview", "v2/quickstart", "v2/development"] - } - ] - } - ] - } -} -``` - -
- ## 语言 -
- -将导航按语言分区。可以从下拉菜单中选择语言。 - - - - - -在 `navigation` 对象中,`languages` 是一个数组,其中每个条目都是一个对象,必须包含 `language` 字段,并且可以包含任何其他导航字段。 - -我们目前支持以下本地化语言: - - - } horizontal /> - - } horizontal /> - - } horizontal /> - - } horizontal /> - - } horizontal /> - - } horizontal /> - - } horizontal /> - - } horizontal /> - - } horizontal /> - - } horizontal /> - - } horizontal /> - - } horizontal /> - - } horizontal /> - - } horizontal /> - - -```json -{ - "navigation": { - "languages": [ - { - "language": "en", - "groups": [ - { - "group": "开始使用", - "pages": ["en/overview", "en/quickstart", "en/development"] - } - ] - }, - { - "language": "es", - "groups": [ - { - "group": "开始使用", - "pages": ["es/overview", "es/quickstart", "es/development"] - } - ] - } - ] - } -} -``` - -如需自动翻译,[请联系销售团队](mailto:gtm@mintlify.com)以讨论解决方案。 - -
- ## 嵌套 -
- -你可以任意组合使用锚点、选项卡和下拉菜单。这些组件可以相互嵌套,以构建所需的导航结构。 - - - ```json 锚点 - { - "navigation": { - "anchors": [ - { - "anchor": "Anchor 1", - "groups": [ - { - "group": "Group 1", - "pages": [ - "some-folder/file-1", - "another-folder/file-2", - "just-a-file" - ] - } - ] - }, - { - "anchor": "Anchor 2", - "groups": [ - { - "group": "Group 2", - "pages": [ - "some-other-folder/file-1", - "various-different-folders/file-2", - "another-file" - ] - } - ] - } - ] - } - } - ``` - - ```json 选项卡 - { - "navigation": { - "tabs": [ - { - "tab": "Tab 1", - "groups": [ - { - "group": "Group 1", - "pages": [ - "some-folder/file-1", - "another-folder/file-2", - "just-a-file" - ] - } - ] - }, - { - "tab": "Tab 2", - "groups": [ - { - "group": "Group 2", - "pages": [ - "some-other-folder/file-1", - "various-different-folders/file-2", - "another-file" - ] - } - ] - } - ] - } - } - ``` - - ```json 带外部锚点的选项卡 - { - "navigation": { - "global": { - "anchors": [ - { - "anchor": "Anchor 1", - "href": "https://mintlify.com/docs" - } - ] - }, - "tabs": [ - { - "tab": "Tab 1", - "groups": [ - { - "group": "Group 1", - "pages": [ - "some-folder/file-1", - "another-folder/file-2", - "just-a-file" - ] - } - ] - }, - { - "tab": "Tab 2", - "groups": [ - { - "group": "Group 2", - "pages": [ - "some-other-folder/file-1", - "various-different-folders/file-2", - "another-file" - ] - } - ] - } - ] - } - } - ``` - - - - -面包屑会在页面顶部显示完整的导航路径。部分主题默认启用面包屑,部分则未启用。你可以通过在 `docs.json` 中设置 `styling` 属性来控制站点是否启用面包屑。 - - - ```json Display full breadcrumbs - "styling": { - "eyebrows": "breadcrumbs" - } - ``` - - ```json Display parent section only - "styling": { - "eyebrows": "section" - } - ``` - - -
- ## 交互配置 -
- -在 `docs.json` 中通过 `interaction` 属性控制用户与导航元素的交互方式。 - -
- ### 为 groups 启用自动导航 -
- -当用户展开一个导航分组时,某些主题会自动跳转到该分组中的第一个页面。你可以使用 `drilldown` 选项覆盖主题的默认行为。 - -* 设为 `true`:在选择导航分组时,强制自动跳转到第一个页面。 -* 设为 `false`:不进行跳转,仅在选择时展开或折叠分组。 -* 不设置:使用主题的默认行为。 - - - ```json Force navigation - "interaction": { - "drilldown": true // 当用户展开下拉列表时,强制跳转到第一个页面 - } - ``` - - ```json Prevent navigation - "interaction": { - "drilldown": false // 始终不跳转,仅展开或折叠分组 - } - ``` - \ No newline at end of file diff --git a/zh/pages.mdx b/zh/pages.mdx deleted file mode 100644 index e0e3a4361..000000000 --- a/zh/pages.mdx +++ /dev/null @@ -1,189 +0,0 @@ ---- -title: "页面" -description: "页面是文档的基本构成单元" -icon: "letter-text" -keywords: ["tags", "tag"] ---- - -每个页面都是一个 MDX 文件,它将 Markdown 内容与 React 组件相结合,帮助你创建丰富、交互性强的文档。 - -
- ## 页面元数据 -
- -每个页面都以 frontmatter 开始,它是在文件开头由 `---` 包裹的 YAML 元数据。该元数据定义了页面的呈现方式和行为。 - -使用元数据可控制: - -* 页面标题和说明 -* 侧边栏标题、图标和标签 - - - 出现在导航和浏览器标签页中的页面标题。 - - - - 对本页内容的简要说明。显示在标题下方,并提升 SEO(搜索引擎优化)效果。 - - - - 显示在侧边栏导航中的简短标题。 - - - - 要显示的图标。 - - 可选项: - - * [Font Awesome icon](https://fontawesome.com/icons) 名称 - * [Lucide icon](https://lucide.dev/icons) 名称 - * 指向外部托管图标的 URL - * 项目中图标文件的路径 - - - - [Font Awesome](https://fontawesome.com/icons) 图标样式。仅在使用 Font Awesome 图标时生效。 - - 选项:`regular`、`solid`、`light`、`thin`、`sharp-solid`、`duotone`、`brands`。 - - - - 显示在侧边栏中页面标题旁边的标签。 - - -```yaml Example YAML frontmatter wrap ---- -title: "关于 frontmatter" -description: "Frontmatter 是控制页面显示和行为的 metadata" -sidebarTitle: "Frontmatter" -icon: "book" -tag: "NEW" ---- -``` - -
- ## 页面模式 -
- -通过 `mode` 设置控制页面的显示方式。 - -
- ### 默认 -
- -如果未指定模式,将采用带有侧边导航和目录的标准布局。 - -```yaml ---- -title: "默认页面标题" ---- -``` - -
- ### 宽屏 -
- -宽屏模式会隐藏目录。这对没有任何标题的页面,或当你想利用更多横向空间时很有用。所有主题均支持宽屏模式。 - -```yaml ---- -title: "宽页面标题" -mode: "wide" ---- -``` - -
- ### 自定义 -
- -自定义模式提供极简布局,除顶部导航栏外移除所有元素。它是一块空白画布,可用于创建登录页或任何其他独特布局,适合需要尽量精简导航元素的场景。自定义模式适用于所有主题。 - -```yaml ---- -title: "自定义页面标题" -mode: "custom" ---- -``` - -
- ### Frame -
- -Frame 模式提供与自定义模式类似的布局,但保留侧边栏导航。该模式在维持默认导航体验的同时,允许使用自定义 HTML 和组件。Frame 模式仅适用于 Aspen 和 Almond 主题。 - -```yaml ---- -title: "Frame 页面标题" -mode: "frame" ---- -``` - -
- ### 居中 -
- -居中模式会移除侧边栏和目录,将内容置于页面中央。它适用于需要突出内容的页面,如更新日志等。居中模式适用于 Mint 和 Linden 主题。 - -```yaml ---- -title: "居中页面标题" -mode: "center" ---- -``` - -
- ## API 页面 -
- -在 frontmatter 中添加 API 规范(`api` 或 `openapi`)即可创建交互式 API 操作台。 - -```yaml ---- -openapi: "GET /endpoint" ---- -``` - -进一步了解如何构建[API 文档](/zh/api-playground/overview)。 - - - -在导航中使用 `url` metadata 直接链接到外部站点。 - -```yaml ---- -title: "npm 包" -url: "https://www.npmjs.com/package/mint" ---- -``` - -
- ## 搜索引擎优化 -
- -大多数 SEO 元标签会自动生成。你也可以手动设置 SEO 元标签,以提升站点的 SEO(搜索引擎优化)、社交分享效果和浏览器兼容性。 - - - 含有冒号的元标签必须用引号括起来。 - - -```yaml ---- -"twitter:image": "/images/social-preview.jpg" ---- -``` - -有关完整的 SEO(搜索引擎优化)metadata 选项,请参阅 [SEO](/zh/settings/seo)。 - -
- ## 内部搜索关键词 -
- -在 metadata 中提供 `keywords`,可提升特定页面在内置搜索中的可发现性。这些关键词不会作为页面内容显示,也不会出现在搜索结果列表中,但当用户搜索这些词时,该页面会相应地显示为搜索结果。 - -```yaml ---- -keywords: ['配置', '设置', '入门指南'] ---- -``` diff --git a/zh/pdf-exports.mdx b/zh/pdf-exports.mdx deleted file mode 100644 index 55982b621..000000000 --- a/zh/pdf-exports.mdx +++ /dev/null @@ -1,37 +0,0 @@ ---- -title: "导出 PDF" -icon: "file-down" -description: "将文档导出为单个 PDF 文件" ---- - -export const DownloadPDFButton = () => { - return ( - - - 查看示例PDF - - ) -} - - - PDF 导出功能适用于 [Custom 计划](https://mintlify.com/pricing)。 - - -你可以将文档导出为单个 PDF 文件,便于离线查看。PDF 将包含文档中的全部内容(包括图片和链接),并提供可导航的目录。 - - -
- ## 导出 PDF -
- -1. 在控制台的“项目设置”中,进入 [General](https://dashboard.mintlify.com/settings/deployment/general) 页面。 -2. 点击 **Export all content** 按钮。 -3. 如有需要,配置导出选项: - - **Page format**:选择 PDF 的页面尺寸。 - - **Scale percentage**:调整 PDF 的缩放比例。 - - **Include footer**:在页脚中包含页码与总页数。 -4. 点击 **Export** 开始导出。 -5. 导出完成后,您将收到一封包含下载链接的电子邮件。 -6. 点击下载链接下载 PDF 文件。 - - \ No newline at end of file diff --git a/zh/react-components.mdx b/zh/react-components.mdx deleted file mode 100644 index b9561034c..000000000 --- a/zh/react-components.mdx +++ /dev/null @@ -1,255 +0,0 @@ ---- -title: "React" -description: "使用 React 组件构建交互且可复用的元素" -icon: "react" ---- - -import { ColorGenerator } from "/snippets/color-generator.jsx"; - -[React 组件](https://react.dev) 是在文档中创建交互式、可复用元素的强大方式。 - -
- ## 使用 React 组件 -
- -你可以在 `MDX` 文件中直接使用 [React hooks](https://react.dev/reference/react/hooks) 来构建 React 组件。 - -
- ### 示例 -
- -此示例先声明一个 `Counter` 组件,然后通过 `` 调用它。 - -```mdx -export const Counter = () => { - const [count, setCount] = useState(0) - - const increment = () => setCount(count + 1) - const decrement = () => setCount(count - 1) - - return ( -
-
- - -
- {count} -
- - -
-
- ) -} - - -``` - -export const Counter = () => { - const [count, setCount] = useState(0) - - const increment = () => setCount(count + 1) - const decrement = () => setCount(count - 1) - - return ( -
-
- - -
- {count} -
- - -
-
- ) -} - -计数器会以可交互的 React 组件形式渲染。 - - - -
- ## 导入组件 -
- -你可以从 `snippets` 文件夹导入组件。与常规 React 不同,你不能从任意 `MDX` 文件导入组件。可复用组件必须引用自 `snippets` 文件夹内的文件。了解更多:[可复用代码片段](/zh/reusable-snippets)。 - -
- ### 示例 -
- -此示例声明了一个使用多个 React Hook 的 `ColorGenerator` 组件,并在一个 `MDX` 文件中使用它。 - -在 `snippets` 文件夹中创建 `color-generator.jsx` 文件: - -```mdx /snippets/color-generator.jsx [expandable] -export const ColorGenerator = () => { - const [hue, setHue] = useState(180) - const [saturation, setSaturation] = useState(50) - const [lightness, setLightness] = useState(50) - const [colors, setColors] = useState([]) - - useEffect(() => { - const newColors = [] - for (let i = 0; i < 5; i++) { - const l = Math.max(10, Math.min(90, lightness - 20 + i * 10)) - newColors.push(`hsl(${hue}, ${saturation}%, ${l}%)`) - } - setColors(newColors) - }, [hue, saturation, lightness]) - - const copyToClipboard = (color) => { - navigator.clipboard - .writeText(color) - .then(() => { - console.log(`已复制 ${color} 到剪贴板!`) - }) - .catch((err) => { - console.error("复制失败:", err) - }) - } - - return ( -
-
-
- - - - - -
- -
- {colors.map((color, idx) => ( -
copyToClipboard(color)} - /> - ))} -
- -
-

- 基础颜色:hsl({hue}, {saturation}%, {lightness}%) -

-
-
-
- ) -} -``` - -导入 `ColorGenerator` 组件,并在 `MDX` 文件中使用它: - -```mdx -import { ColorGenerator } from "/snippets/color-generator.jsx" - - -``` - -颜色生成器会以交互式 React 组件的形式呈现。 - - - -
- ## 注意事项 -
- - - - React Hook 组件在客户端渲染,这带来以下影响: - - * **SEO(搜索引擎优化)**:搜索引擎可能无法完整索引动态内容。 - * **初始加载**:在组件渲染前,访客可能会看到内容加载的闪烁。 - * **无障碍**:确保动态内容的变化能够被屏幕阅读器正确播报。 - - - - * **优化依赖数组**:在 `useEffect` 的依赖数组中仅包含必要的依赖。 - * **记忆化复杂计算**:对开销较大的操作使用 `useMemo` 或 `useCallback`。 - * **减少重复渲染**:将大型组件拆分为更小的组件以避免级联式重复渲染。 - * **懒加载**:考虑对复杂组件进行懒加载,以改善页面的初始加载时间。 - - diff --git a/zh/reusable-snippets.mdx b/zh/reusable-snippets.mdx deleted file mode 100644 index 933e7945e..000000000 --- a/zh/reusable-snippets.mdx +++ /dev/null @@ -1,129 +0,0 @@ ---- -title: '可复用片段' -description: '复用自定义片段,保持内容一致' -icon: 'recycle' ---- - -软件开发的核心原则之一是 DRY(Don't Repeat Yourself,不要重复),这同样适用于文档。如果你发现在多个位置重复相同的内容,应该创建自定义片段以保持内容一致。 - -
- ## 创建自定义片段 -
- -**前置条件**:必须在 `snippets` 目录中创建片段文件,导入才能生效。 - -`snippets` 目录中的任何页面都会被视为片段,不会被渲染为独立页面。若要基于该片段创建独立页面,请将其导入到另一个文件中,并以组件形式调用。 - -
- ### 默认导出 -
- -1. 将你希望复用的内容添加到片段文件中。你也可以添加变量,在导入片段时通过 props 进行填充。在此示例中,我们的变量是 word。 - -```typescript snippets/my-snippet.mdx -你好世界!这是我想要在各个页面中重复使用的内容。 -``` - -2. 将该代码片段导入到目标文件中。 - -```typescript destination-file.mdx ---- -title: 我的标题 -description: 我的说明 ---- - -import MySnippet from '/snippets/path/to/my-snippet.mdx'; - -## 标题 - -Lorem ipsum dolor sit amet. - - - -``` - -
- ### 使用变量导出 -
- -1. 你也可以选择添加一些变量,在导入该片段时通过 props 传入并填充。在本示例中,我们的变量是 word。 - -```typescript snippets/my-snippet.mdx -我今天的关键词是 {word}。 -``` - -2. 在目标文件中使用该变量导入代码片段。该属性会根据你的设定自动填充。 - -```typescript destination-file.mdx ---- -title: 我的标题 -description: 我的说明 ---- - -import MySnippet from '/snippets/path/to/my-snippet.mdx'; - -## 标题 - -Lorem ipsum dolor sit amet. - - - -``` - -
- ### 可重用变量 -
- -1. 从你的代码片段(snippet)文件中导出一个变量: - -```typescript snippets/path/to/custom-variables.mdx -export const myName = '我的名字'; - -export const myObject = { fruit: '草莓' }; -``` - -2. 从目标文件导入该代码片段,并使用该变量: - -```typescript destination-file.mdx ---- -title: 我的标题 -description: 我的说明 ---- - -import { myName, myObject } from '/snippets/path/to/custom-variables.mdx'; - -你好,我的名字是 {myName},我喜欢 {myObject.fruit}。 -``` - -
- ### JSX 片段 -
- -1. 从片段文件中导出一个 JSX 组件。(参见[React 组件](/zh/react-components)了解更多信息): - -```js icon=square-js snippets/my-jsx-snippet.jsx -export const MyJSXSnippet = () => { - return ( -
-

你好,世界!

-
- ) -} -``` - - - 重要:创建 JSX 代码片段时,请使用箭头函数语法(`=>`),不要使用函数声明。在此 context 中不支持 `function` 关键字。 - - -2. 从目标文件中导入该片段,并使用该组件: - -```typescript destination-file.mdx ---- -title: 我的标题 -description: 我的说明 ---- - -import { MyJSXSnippet } from '/snippets/my-jsx-snippet.jsx'; - - -``` diff --git a/zh/settings.mdx b/zh/settings.mdx deleted file mode 100644 index 303bab6ed..000000000 --- a/zh/settings.mdx +++ /dev/null @@ -1,1620 +0,0 @@ ---- -title: "全局设置" -description: "使用 `docs.json` 文件配置全站设置" -icon: "settings-2" -keywords: ["docs.json", "设置", "自定义", "配置"] ---- - -import IconsOptional from "/snippets/zh/icons-optional.mdx"; - -`docs.json` 文件可将一组 Markdown 文件构建成可导航、可自定义的文档站点。这个必需的配置文件控制样式、navigation、integrations 等设置,是你的文档的蓝图。 - -`docs.json` 中的设置会全局作用于所有页面。 - -
- ## 配置你的 `docs.json` -
- -开始时,你只需指定 `theme`、`name`、`colors.primary` 和 `navigation`。其他字段是可选的,可随着文档需求的增长逐步添加。 - -为获得最佳编辑体验,请在 `docs.json` 文件开头加入模式(schema)引用。这样可在大多数代码编辑器中启用自动补全、校验和实用的悬浮提示: - -```json -{ - "$schema": "https://mintlify.com/docs.json", - "theme": "mint", - "name": "您的文档", - "colors": { - "primary": "#ff0000" - }, - "navigation": { - // 您的导航结构 - } - // 配置的其余部分 -} -``` - -
- ## 参考 -
- -本节提供 `docs.json` 文件的完整参考资料。 - -
- ### 自定义 -
- - - 站点的布局主题。 - - 可选项:`mint`、`maple`、`palm`、`willow`、`linden`、`almond`、`aspen`。 - - 详见 [Themes](zh/themes)。 - - - - 您的项目、组织或产品名称。 - - - - 文档中使用的配色。不同主题的应用方式不同。若仅提供主色,将用于所有相关颜色元素。 - - - - 文档的主色。通常用于浅色模式中的强调效果,具体随主题有所差异。 - - 必须为以 `#` 开头的十六进制色值。 - - - - 深色模式下用于强调的颜色。 - - 必须为以 `#` 开头的十六进制色值。 - - - - 浅色与深色模式下按钮与悬停状态所用的颜色,具体随主题有所差异。 - - 必须为以 `#` 开头的十六进制色值。 - - - - - - 面向 SEO(搜索引擎优化)与 AI 索引编入的站点说明。 - - - - 适用于浅色与深色模式的徽标。 - - - - 指向浅色模式徽标文件的路径,需包含文件扩展名。示例:`/logo.png` - - - - 指向深色模式徽标文件的路径,需包含文件扩展名。示例:`/logo-dark.png` - - - - 点击徽标时跳转的 URL。如未提供,徽标将链接至您的首页。示例:`https://mintlify.com` - - - - - - 指向 favicon 文件的路径,需包含文件扩展名。将自动调整为合适的 favicon 尺寸。 - 可为单个文件,或分别为浅色/深色模式提供文件。示例:`/favicon.png` - - - - 指向浅色模式 favicon 文件的路径,需包含文件扩展名。示例:`/favicon.png` - - - - 指向深色模式 favicon 文件的路径,需包含文件扩展名。示例:`/favicon-dark.png` - - - - - - 社交媒体与页面预览的缩略图自定义。 - - - - 缩略图的视觉主题。若未指定,将使用 `colors` 字段定义的站点配色方案。 - - - - 缩略图背景图像。可为相对路径或绝对 URL。 - - - - - - 视觉样式配置。 - - - - 页面 eyebrow 的样式。选择 `section` 显示章节名称,或选择 `breadcrumbs` 显示完整导航路径。默认值为 `section`。 - - - - 代码块主题配置。默认值为 `"system"`。 - - **简单配置:** - - * `"system"`:跟随当前站点模式(浅色或深色) - * `"dark"`:始终使用深色模式 - - **自定义主题配置:** - - * 使用字符串为所有代码块指定一个 [Shiki 主题](https://shiki.style/themes) - * 使用对象分别为浅色和深色模式指定 [Shiki 主题](https://shiki.style/themes) - - - 一个同时用于浅色与深色模式的 Shiki 主题名称。 - - ```json - "styling": { - "codeblocks": { - "theme": "dracula" - } - } - ``` - - - - 分别为浅色和深色模式设置主题。 - - - - 浅色模式的 Shiki 主题名称。 - - - - 深色模式的 Shiki 主题名称。 - - - ```json - "styling": { - "codeblocks": { - "theme": { - "light": "github-light", - "dark": "github-dark" - } - } - } - ``` - - - - - - - - 图标库设置。 - - - - 文档全站使用的图标库。默认值为 `fontawesome`。 - - - 无论库设置如何,您都可以为任意单个图标指定外部托管图标的 URL、项目中图标文件的路径,或兼容 JSX 的 SVG 代码。 - - - - - - - 文档站点的字体配置。默认字体为 [Inter](https://fonts.google.com/specimen/Inter)。 - - - - 字体系列,例如“Open Sans”。 - - - - 字重,例如 400 或 700。可变字体支持更精细的字重,例如 550。 - - - - 字体源文件的 URL,例如 https://mintlify-assets.b-cdn.net/fonts/Hubot-Sans.woff2。指定 Google 字体的 `family` 名称时会自动加载 [Google Fonts](https://fonts.google.com),因此无需提供 source 的 URL。 - - - - 字体文件格式。 - - - - 专用于标题的字体设置覆盖。 - - - - 字体系列,例如“Open Sans”、“Playfair Display”。 - - - - 字重,例如 400、700。可变字体支持更精细的字重,例如 550。 - - - - 字体源文件的 URL,例如 https://mintlify-assets.b-cdn.net/fonts/Hubot-Sans.woff2。指定 Google 字体的 `family` 名称时会自动加载 [Google Fonts](https://fonts.google.com),因此无需提供 source 的 URL。 - - - - 字体文件格式。 - - - - - - 专用于正文的字体设置覆盖。 - - - - 字体系列,例如“Open Sans”、“Playfair Display”。 - - - - 字重,例如 400、700。可变字体支持更精细的字重,例如 550。 - - - - 字体源文件的 URL,例如 https://mintlify-assets.b-cdn.net/fonts/Hubot-Sans.woff2。指定 Google 字体的 `family` 名称时会自动加载 [Google Fonts](https://fonts.google.com),因此无需提供 source 的 URL。 - - - - 字体文件格式。 - - - - - - - - 明/暗模式切换设置。 - - - - 默认主题模式。选择 `system` 以匹配用户的操作系统设置,或选择 `light` 或 `dark` 以强制特定模式。默认值为 `system`。 - - - - 是否隐藏明/暗模式切换。默认值为 `true`。 - - - - - - 背景颜色与装饰的设置。 - - - - 站点的背景图片。可为单个文件,或分别为浅色与深色模式提供不同文件。 - - - - 浅色模式的背景图片路径。需包含文件扩展名。示例:`/background.png`。 - - - - 深色模式的背景图片路径。需包含文件扩展名。示例:`/background-dark.png`。 - - - - - - 主题的背景装饰效果。 - - - - 为浅色与深色模式自定义背景颜色。 - - - - 浅色模式的背景颜色。 - - 必须是以 `#` 开头的十六进制色值。 - - - - 深色模式的背景颜色。 - - 必须是以 `#` 开头的十六进制色值。 - - - - - - -
- ### 结构 -
- - - 指向外部链接的导航栏条目。 - - - - 要在导航栏中显示的链接 - - - - 链接文本。 - - - - 链接目标。必须是有效的外部 URL。 - - - - - - - - 导航栏中的主按钮。 - - - - 按钮样式。选择 `button` 表示带有文本的标准按钮;选择 `github` 表示指向 GitHub 存储库并带有 icon 的链接。 - - - - 按钮文本。仅当 `type` 为 `button` 时生效。 - - - - 按钮目标。必须是外部 URL。若 `type` 为 `github`,则必须是 GitHub 存储库的 URL。 - - - - - - - - 您内容的导航结构。 - - - - 在所有页面和章节中显示的全局导航元素。 - - - - 本地化站点的语言切换配置。 - - - - 符合 ISO 639-1 的语言代码 - - - - 是否为默认语言。 - - - - 是否默认隐藏此语言选项。 - - - - 指向该语言文档版本的有效路径或外部链接。 - - - - - - 用于多版本站点的版本切换器配置。 - - - - 版本的显示名称。 - - 最小长度:1 - - - - 是否为默认版本。 - - - - 是否默认隐藏该版本选项。 - - - - 指向该文档版本的 URL 或路径。 - - - - - - 用于组织主要版块的顶层导航选项卡。 - - - - 标签页的显示名称。 - - 最小长度:1 - - - - - - 是否默认隐藏此标签页。 - - - - 指向该标签页目标的 URL 或路径。 - - - - - - 在侧边栏导航中醒目显示的锚点链接。 - - - - 锚点的显示名称。 - - 最小长度:1 - - - - - - 锚点的自定义颜色。 - - - - 浅色模式下的锚点颜色。 - - 必须是以 `#` 开头的十六进制色值。 - - - - 深色模式下的锚点颜色。 - - 必须是以 `#` 开头的十六进制色值。 - - - - - - 是否默认隐藏此锚点。 - - - - 指向锚点目标的 URL 或路径。 - - - - - - 用于组织相关内容的下拉菜单。 - - - - 下拉菜单的显示名称。 - - 最小长度:1 - - - - - - 是否默认隐藏该下拉菜单。 - - - - 下拉菜单目标的 URL 或路径。 - - - - - - - - 适用于[多语言](zh/navigation#languages)站点的语言切换器。 - - - - 为拥有多个[版本](zh/navigation#versions)的网站提供版本切换器。 - - - - 顶层导航的 [tabs](zh/navigation#tabs)。 - - - - 侧边栏[锚点](zh/navigation#anchors)。 - - - - [下拉菜单](zh/navigation#dropdowns),用于分组相关内容。 - - - - [Groups](zh/navigation#groups) 用于将内容组织成各个部分。 - - - - 构成文档的各个[页面](zh/navigation#pages)。 - - - - - - 导航元素的用户交互设置。 - - - - 控制选择导航分组时的自动导航行为。设为 `true` 时,在展开导航分组时强制进入第一篇页面。设为 `false` 时不跳转,仅展开或折叠该分组。留空则使用主题的默认行为。 - - - - - - 页脚内容与社交媒体链接。 - - - - 要在页脚中显示的社交媒体帐号。每个 key 为平台名称,每个 value 为你的个人资料 URL。例如: - - ```json - { - "x": "https://x.com/mintlify" - } - ``` - - 可用的属性名称:`x`、`website`、`facebook`、`youtube`、`discord`、`slack`、`github`、`linkedin`、`instagram`、`hacker-news`、`medium`、`telegram`、`twitter`、`x-twitter`、`earth-americas`、`bluesky`、`threads`、`reddit`、`podcast` - - - - 要在页脚中显示的链接。 - - - - 列标题。 - - 最小长度:1 - - - - 要在该列中显示的链接。 - - - - 链接文本。 - - 最小长度:1 - - - - 链接目标 URL。 - - - - - - - - - - 显示在页面顶部的全站横幅。 - - - - 横幅内容。支持纯文本和 Markdown 格式。例如: - - ```json - { - "content": "🚀 Banner is live! [Learn more](mintlify.com)" - } - ``` - - - - 用户是否可以关闭横幅。默认为 `false`。 - - - - - - 针对页面移动、重命名或删除的重定向。 - - - - 要从中重定向的源路径。示例:`/old-page` - - - - 要重定向到的目标路径。示例:`/new-page` - - - - 是否使用永久重定向(301)。默认为 `true`。 - - - - - - 用于 AI 优化内容和集成的上下文菜单。 - - - - 上下文菜单中的可用操作。第一个选项将作为默认项显示。 - - * `copy`:将当前页面以 Markdown 形式复制到剪贴板。 - * `view`:在新标签页中以 Markdown 查看当前页面。 - * `chatgpt`:将当前页面内容发送到 ChatGPT。 - * `claude`:将当前页面内容发送到 Claude。 - * `perplexity`:将当前页面内容发送到 Perplexity。 - * `mcp`:将你的 MCP 服务器 URL 复制到剪贴板。 - * `cursor`:在 Cursor 中安装你托管的 MCP 服务器。 - * `vscode`:在 VSCode 中安装你托管的 MCP 服务器。 - - Contextual Menu - - - 上下文菜单仅在预览和生产部署中可用。 - - - - - -
- ### API 配置 -
- - - API 文档与交互式操作台的相关设置。 - - - - 用于生成 API 文档的 OpenAPI 规范文件。可为单个 URL/路径,也可为多个 URL/路径组成的数组。 - - - - OpenAPI 规范文件的 URL 或路径。 - - 最小长度:1 - - - - 用于搜索 OpenAPI 文件的目录。 - - 请勿以斜杠开头。 - - - - - - 用于生成 API 文档的 AsyncAPI 规范文件。可为单个 URL/路径,也可为多个 URL/路径组成的数组。 - - - - AsyncAPI 规范文件的 URL 或路径。 - - 最小长度:1 - - - - 用于搜索 AsyncAPI 文件的目录。 - - 请勿以斜杠开头。 - - - - - - API 参数的显示设置。 - - - - 是否默认展开所有参数。默认值为 `closed`。 - - - - - - API 操作台设置。 - - - - API 操作台的显示模式。默认值为 `interactive`。 - - - - 是否通过代理服务器转发 API 请求。默认值为 `true`。 - - - - - - 自动生成的 API 示例配置。 - - - - 自动生成的 API 代码片段的示例语言。 - - - - 是否在 API 示例中显示可选参数。默认值为 `all`。 - - - - - - 基于 `MDX` 文件生成的 API 页面配置。 - - - - 基于 MDX 的 API 请求的认证配置。 - - - - API 请求的认证方式。 - - - - API 请求的认证名称。 - - - - - - API 请求的服务器配置。 - - - - - - - - - - SEO(搜索引擎优化)索引配置。 - - - - 添加到每个页面的 Meta 标签。必须是有效的 key-value 键值对。可在 [常用 Meta 标签参考](/zh/settings/seo#common-meta-tags-reference) 中查看可选项。 - - - - 指定哪些页面应被搜索引擎收录。选择 `navigable` 仅收录 `docs.json` 的 navigation 中的页面,选择 `all` 则收录所有页面。默认值为 `navigable`。 - - - - - - 搜索展示设置。 - - - - 搜索栏的占位提示文本。 - - - - -
- ### 集成 -
- - - 第三方集成。 - - - - Amplitude Analytics 集成。 - - - - 您的 Amplitude API 密钥。 - - - - - - Clearbit 数据富集集成。 - - - - 您的 Clearbit API key。 - - - - - - Fathom Analytics 集成。 - - - - 您的 Fathom 站点 ID。 - - - - - - Front 聊天集成。 - - - - 你的 Front 聊天代码片段 ID。 - - 最小长度:6 - - - - - - Google Analytics 4 集成。 - - - - 您的 Google Analytics 4 measurement ID。 - - 必须符合模式:^G - - - - - - Google Tag Manager 集成。 - - - - 您的 Google Tag Manager 标签 ID。 - - 必须符合模式:^G - - - - - - Heap Analytics 集成。 - - - - 你的 Heap appId。 - - - - - - Hotjar 集成。 - - - - 您的 Hotjar ID。 - - - - 您的 Hotjar 脚本版本。 - - - - - - Intercom 集成。 - - - - 您的 Intercom 应用 ID。 - - 最小长度:6 - - - - - - Koala 集成。 - - - - 您的 Koala 公共 API key。 - - 最小长度:2 - - - - - - LogRocket 集成。 - - - - 您的 LogRocket 应用 ID。 - - - - - - Mixpanel 集成。 - - - - 您的 Mixpanel 项目令牌。 - - - - - - 与 Osano 的集成。 - - - - 您的 Osano 脚本地址。 - - - - - - Pirsch Analytics 集成。 - - - - 你的 Pirsch ID。 - - - - - - PostHog 集成。 - - - - 你的 PostHog API key。 - - 必须匹配模式:^phc_ - - - - 你的 PostHog API 主机地址。 - - - - - - Plausible Analytics 集成。 - - - - 你的 Plausible domain(域名)。 - - - - 你的 Plausible 服务器地址。 - - - - - - Segment 集成。 - - - - 你的 Segment key。 - - - - - - 遥测设置。 - - - - 是否启用遥测。 - - - - - - Cookie 设置。 - - - - Cookie 的 key。 - - - - Cookie 的值。 - - - - - - -
- ### 错误 -
- - - 错误处理设置。 - - - - 404“页面未找到”错误的处理。 - - - - 当页面未找到时是否自动重定向到首页。 - - - - 404 错误页面的自定义标题。 - - - - 404 错误页面的自定义说明。支持 Markdown 格式。 - - - - - - -
- ## 示例 -
- - - - ```json title="docs.json" wrap lines - { - "$schema": "https://mintlify.com/docs.json", - "theme": "maple", - "name": "Example Co.", - "description": "Example Co. 是一家提供示例内容和占位符文本的公司。", - "colors": { - "primary": "#3B82F6", - "light": "#F8FAFC", - "dark": "#0F172A" - }, - "navigation": { - "dropdowns": [ - { - "dropdown": "文档", - "icon": "book", - "description": "如何使用 Example Co. 产品", - "groups": [ - { - "group": "快速开始", - "pages": [ - "index", - "quickstart" - ] - }, - { - "group": "自定义配置", - "pages": [ - "settings", - "users", - "features" - ] - }, - { - "group": "计费管理", - "pages": [ - "billing/overview", - "billing/payments", - "billing/subscriptions" - ] - } - ] - }, - { - "dropdown": "更新日志", - "icon": "history", - "description": "产品更新和变更记录", - "pages": [ - "changelog" - ] - } - ] - }, - "logo": { - "light": "/logo-light.svg", - "dark": "/logo-dark.svg", - "href": "https://example.com" - }, - "navbar": { - "links": [ - { - "label": "社区", - "href": "https://example.com/community" - } - ], - "primary": { - "type": "button", - "label": "立即开始", - "href": "https://example.com/start" - } - }, - "footer": { - "socials": { - "x": "https://x.com/example", - "linkedin": "https://www.linkedin.com/company/example", - "github": "https://github.com/example", - "slack": "https://example.com/community" - }, - "links": [ - { - "header": "资源", - "items": [ - { - "label": "客户案例", - "href": "https://example.com/customers" - }, - { - "label": "企业版", - "href": "https://example.com/enterprise" - }, - { - "label": "申请试用", - "href": "https://example.com/preview" - } - ] - }, - { - "header": "公司", - "items": [ - { - "label": "招聘信息", - "href": "https://example.com/careers" - }, - { - "label": "博客", - "href": "https://example.com/blog" - }, - { - "label": "隐私政策", - "href": "https://example.com/legal/privacy" - } - ] - } - ] - }, - "integrations": { - "ga4": { - "measurementId": "G-XXXXXXXXXX" - }, - "koala": { - "publicApiKey": "pk_example_key_123" - }, - "telemetry": { - "enabled": true - }, - "cookies": { - "key": "example_cookie_key", - "value": "example_cookie_value" - } - }, - "contextual": { - "options": [ - "copy", - "view", - "chatgpt", - "claude" - ] - }, - "errors": { - "404": { - "redirect": false, - "title": "页面未找到", - "description": "这个_页面_到底**怎么了**?" - } - } - } - ``` - - - - ```json title="docs.json" wrap lines highlight={43-61, 72-79} - { - "$schema": "https://mintlify.com/docs.json", - "theme": "maple", - "name": "Example Co.", - "description": "Example Co. 是一家提供示例内容和占位符文本的公司。", - "colors": { - "primary": "#3B82F6", - "light": "#F8FAFC", - "dark": "#0F172A" - }, - "navigation": { - "dropdowns": [ - { - "dropdown": "文档", - "icon": "book", - "description": "如何使用 Example Co. 产品", - "groups": [ - { - "group": "快速入门", - "pages": [ - "index", - "quickstart" - ] - }, - { - "group": "自定义配置", - "pages": [ - "settings", - "users", - "features" - ] - }, - { - "group": "计费管理", - "pages": [ - "billing/overview", - "billing/payments", - "billing/subscriptions" - ] - } - ] - }, - { - "dropdown": "API 参考", - "icon": "terminal", - "description": "如何使用 Example Co. API", - "groups": [ - { - "group": "API 参考", - "pages": [ - "api-reference/introduction" - ] - }, - { - "group": "接口端点", - "openapi": { - "source": "openapi.json" - } - } - ] - }, - { - "dropdown": "更新日志", - "icon": "history", - "description": "更新和变更记录", - "pages": [ - "changelog" - ] - } - ] - }, - "api": { - "playground": { - "display": "interactive" - }, - "examples": { - "languages": ["javascript", "curl", "python"] - } - }, - "logo": { - "light": "/logo-light.svg", - "dark": "/logo-dark.svg", - "href": "https://example.com" - }, - "navbar": { - "links": [ - { - "label": "社区", - "href": "https://example.com/community" - } - ], - "primary": { - "type": "button", - "label": "立即开始", - "href": "https://example.com/start" - } - }, - "footer": { - "socials": { - "x": "https://x.com/example", - "linkedin": "https://www.linkedin.com/company/example", - "github": "https://github.com/example", - "slack": "https://example.com/community" - }, - "links": [ - { - "header": "资源", - "items": [ - { - "label": "客户案例", - "href": "https://example.com/customers" - }, - { - "label": "企业版", - "href": "https://example.com/enterprise" - }, - { - "label": "申请预览", - "href": "https://example.com/preview" - } - ] - }, - { - "header": "公司", - "items": [ - { - "label": "招聘信息", - "href": "https://example.com/careers" - }, - { - "label": "博客", - "href": "https://example.com/blog" - }, - { - "label": "隐私政策", - "href": "https://example.com/legal/privacy" - } - ] - } - ] - }, - "integrations": { - "ga4": { - "measurementId": "G-XXXXXXXXXX" - }, - "koala": { - "publicApiKey": "pk_example_key_123" - }, - "telemetry": { - "enabled": true - }, - "cookies": { - "key": "example_cookie_key", - "value": "example_cookie_value" - } - }, - "contextual": { - "options": [ - "copy", - "view", - "chatgpt", - "claude" - ] - }, - "errors": { - "404": { - "redirect": false, - "title": "页面未找到", - "description": "这个**页面**到底_去哪了_?" - } - } - } - ``` - - - - ```json title="docs.json" wrap lines - { - "$schema": "https://mintlify.com/docs.json", - "theme": "maple", - "name": "Example Co.", - "description": "Example Co. 是一家提供示例内容和占位符文本的公司。", - "colors": { - "primary": "#3B82F6", - "light": "#F8FAFC", - "dark": "#0F172A" - }, - "navigation": { - "global": { - "anchors": [ - { - "anchor": "文档", - "href": "https://mintlify.com/docs" - }, - { - "anchor": "更新日志", - "href": "https://mintlify.com/docs/changelog" - } - ] - }, - "languages": [ // [!code highlight:3] - { - "language": "en", - "dropdowns": [ - { - "dropdown": "文档", - "icon": "book", - "description": "如何使用 Example Co. 产品", - "pages": [ - { - "group": "快速入门", - "pages": ["index", "quickstart"] - }, - { - "group": "自定义配置", - "pages": ["settings", "users", "features"] - }, - { - "group": "计费管理", - "pages": [ - "billing/overview", - "billing/payments", - "billing/subscriptions" - ] - } - ] - }, - { - "dropdown": "更新日志", - "icon": "history", - "description": "更新和变更记录", - "pages": ["changelog"] - } - ] - }, - { - "language": "es",// [!code highlight] - "dropdowns": [ - { - "dropdown": "文档", - "icon": "book", - "description": "如何使用 Example Co. 产品", - "pages": [ - { - "group": "快速入门", - "pages": ["es/index", "es/quickstart"] - }, - { - "group": "自定义配置", - "pages": ["es/settings", "es/users", "es/features"] - }, - { - "group": "计费管理", - "pages": [ - "es/billing/overview", - "es/billing/payments", - "es/billing/subscriptions" - ] - } - ] - }, - { - "dropdown": "更新日志", - "icon": "history", - "description": "更新和变更记录", - "pages": ["es/changelog"] - } - ] - } - ] - }, - "logo": { - "light": "/logo-light.svg", - "dark": "/logo-dark.svg", - "href": "https://example.com" - }, - "navbar": { - "links": [ - { - "label": "社区", - "href": "https://example.com/community" - } - ], - "primary": { - "type": "button", - "label": "立即开始", - "href": "https://example.com/start" - } - }, - "footer": { - "socials": { - "x": "https://x.com/example", - "linkedin": "https://www.linkedin.com/company/example", - "github": "https://github.com/example", - "slack": "https://example.com/community" - }, - "links": [ - { - "header": "资源", - "items": [ - { - "label": "客户案例", - "href": "https://example.com/customers" - }, - { - "label": "企业版", - "href": "https://example.com/enterprise" - }, - { - "label": "申请试用", - "href": "https://example.com/preview" - } - ] - }, - { - "header": "公司", - "items": [ - { - "label": "招聘信息", - "href": "https://example.com/careers" - }, - { - "label": "博客", - "href": "https://example.com/blog" - }, - { - "label": "隐私政策", - "href": "https://example.com/legal/privacy" - } - ] - } - ] - }, - "integrations": { - "ga4": { - "measurementId": "G-XXXXXXXXXX" - }, - "koala": { - "publicApiKey": "pk_example_key_123" - }, - "telemetry": { - "enabled": true - }, - "cookies": { - "key": "example_cookie_key", - "value": "example_cookie_value" - } - }, - "contextual": { - "options": ["copy", "view", "chatgpt", "claude"] - }, - "errors": { - "404": { - "redirect": false, - "title": "页面未找到", - "description": "这个**页面**到底_怎么了_?" - } - } - } - ``` - - - -
- ## 从 `mint.json` 升级 -
- -如果你的文档项目仍在使用已废弃的 `mint.json` 文件,请按以下步骤升级到 `docs.json`。 - - - - 如果你尚未安装[命令行界面(CLI)](/zh/installation),请先安装: - - - ```bash npm - npm i -g mint - ``` - - ```bash yarn - yarn global add mint - ``` - - ```bash pnpm - pnpm add -g mint - ``` - - - 如果你已经安装了 CLI,请确保更新至最新版本: - - ```bash - mint update - ``` - - - - 在你的文档存储库中运行: - - ```bash - mint upgrade - ``` - - 该命令会基于现有的 `mint.json` 生成一个 `docs.json` 文件。请检查生成的文件,确保所有设置正确。 - - - - 在确认 `docs.json` 配置无误后,你即可安全删除旧的 `mint.json` 文件。 - - \ No newline at end of file diff --git a/zh/settings/broken-links.mdx b/zh/settings/broken-links.mdx deleted file mode 100644 index 3b7ead960..000000000 --- a/zh/settings/broken-links.mdx +++ /dev/null @@ -1,47 +0,0 @@ ---- -title: "重定向与失效链接" -description: "防止链接失效的工具" -icon: "link-2" ---- - -当你更改 docs 文件夹中文件的路径时,该页面的 URL 也会随之更改。这通常发生在重组文档或更改侧边栏标题时。 - - - -使用我们的命令行界面(CLI)检查并发现失效链接。[安装 CLI](/zh/installation) 后运行以下命令: - -```bash -mint broken-links -``` - -命令行界面(CLI)会检测文档中所有指向不存在目标的相对链接。 - -
- ## 重定向 -
- -在你的 `docs.json` 文件中添加 `redirects` 字段来设置 301 重定向。 - -```json -"redirects": [ - { - "source": "/source/path", - "destination": "/destination/path" - } -] -``` - -这会将 `/source/path` 永久重定向到 `/destination/path`,从而保留原页面既有的 SEO(搜索引擎优化)权重。 - -要匹配通配路径,请在参数后使用 `*`。在此示例中,`/beta/:slug*` 会匹配 `/beta/introduction`,并将其重定向到 `/v2/introduction`。 - -```json -"redirects": [ - { - "source": "/beta/:slug*", - "destination": "/v2/:slug*" - } -] -``` diff --git a/zh/settings/ci.mdx b/zh/settings/ci.mdx deleted file mode 100644 index e5f70faad..000000000 --- a/zh/settings/ci.mdx +++ /dev/null @@ -1,425 +0,0 @@ ---- -title: "CI 检查" -description: "在更新流程中添加死链检测、lint 与语法检查" -icon: "circle-check" ---- - - - [Pro 和 Enterprise 套餐](https://mintlify.com/pricing?ref=docs-ci)包含针对 GitHub 仓库的 CI 检查。 - - -使用 CI 检查对文档进行 lint、发现错误,并在部署前提供 Warning。CI 检查会在对已配置的部署用分支的提交上,或针对该分支的拉取请求(PR)上运行。 - -
- ## 安装 -
- -首先,请按照 [GitHub](/zh/settings/github) 页面上的步骤操作。 - -对于 GitHub 应用,您可以选择仅为单个存储库授予权限。我们强烈建议这样做,因为我们只需要访问托管您文档的存储库。 - -
- ## 配置 -
- -前往控制台的 [附加组件](https://dashboard.mintlify.com/products/addons) 页面,配置在部署中启用的 CI 检查。启用你希望运行的检查项。 - -启用检查时,你可以选择以 `Warning` 或 `Blocking` 级别运行。 - -* `Warning` 级别的检查即使存在错误或建议,也不会标记为失败。 -* `Blocking` 级别的检查若未通过或提出了更改建议,将标记为失败。 - -
- ## 可用的 CI 检查 -
- - - -与本地的 [CLI 链接检查器](/zh/settings/broken-links#broken-links) 类似,我们会自动扫描文档中的断链。 - -要查看检查结果,请前往 GitHub 上该特定提交的检查结果页面。 - -
- ### Vale -
- -[Vale](https://vale.sh/) 是一个开源的、基于规则的文本风格校验器,支持包括 Markdown 和 MDX 在内的多种文档类型。 - -Mintlify 支持在 CI 检查中自动运行 Vale,并将结果显示为检查状态。 - -
- #### 配置 -
- -如果在部署的根内容目录中有 `.vale.ini` 文件,我们会自动使用该配置文件。我们也会自动加载你在 `stylesPath` 中指定的任何配置文件。 - -如果没有 Vale 配置文件,将使用默认配置。 - -```mdx Default vale.ini configuration expandable -# 顶级样式 -StylesPath = /app/styles -MinAlertLevel = suggestion -IgnoredScopes = code, tt, img, url, a -SkippedScopes = script, style, pre, figure, code - -# 词汇表 -Vocab = Mintlify - -# 这是必需的,因为 Vale 官方不支持 MDX -[formats] -mdx = md - -# MDX 支持 -[*.mdx] -BasedOnStyles = Vale -Vale.Terms = NO # 强制执行非常严格的大小写规则,保持关闭 - -# `import ...`, `export ...` -# `` -# `...` -# `{ ... }` -TokenIgnores = (?sm)((?:import|export) .+?$), \ -(?)(?!`), \ -(<[A-Z]\w+>.+?<\/[A-Z]\w+>) - -# 排除: -# `` -BlockIgnores = (?sm)^(<\w+\n .*\s\/>)$, \ -(?sm)^({.+.*}) - -CommentDelimiters = {/*, */} -``` - -```text Default Vale vocabulary expandable -Mintlify -mintlify -VSCode -openapi -OpenAPI -GitHub -API - -repo -npm -dev - -Lorem -ipsum -impsum -amet - -const -myName -myObject -bearerAuth -favicon -topbar -url -borderRadius -args -modeToggle -ModeToggle -isHidden -autoplay - -_italic_ -Strikethrough -Blockquotes -Blockquote -Singleline -Multiline - -onboarding - -async -await -boolean -enum -func -impl -init -instanceof -typeof -params -stdin -stdout -stderr -stdout -stdin -var -const -let -null -undefined -struct -bool - -cors -csrf -env -xhr -xhr2 -jwt -oauth -websocket -localhost -middleware -runtime -webhook -stdin -stdout - -json -yaml -yml -md -txt -tsx -jsx -css -scss -html -png -jpg -svg - -cdn -命令行界面(CLI) -css -dom -dto -env -Git -gui -http -https -ide -jvm -mvc -orm -rpc -SDK -sql -ssh -ssl -tcp -tls -uri -URL -ux -ui - -nodejs -npm -yarn -pnpm -eslint -pytest -golang -rustc -kubectl -mongo -postgres -redis - -JavaScript -TypeScript -Python -Ruby -Rust -Go -Golang -Java -Kotlin -Swift -Node.js -NodeJS -Deno - -React -Vue -Angular -Next.js -Nuxt -Express -Django -Flask -Spring -Laravel -Redux -Vuex -TensorFlow -PostgreSQL -MongoDB -Redis -PNPM - -Docker -Kubernetes -AWS -Azure -GCP -Terraform -Jenkins -CircleCI -GitLab -Heroku - -Git -git -GitHub -GitLab -Bitbucket -VSCode -Visual Studio Code -IntelliJ -WebStorm -ESLint -eslint -Prettier -prettier -Webpack -webpack -Vite -vite -Babel -babel -Jest -jest -Mocha -Cypress -Postman - -HTTP -HTTPS -OAuth -JWT(JSON Web Token) -GraphQL -REST -WebSocket -TCP/IP - -NPM -Yarn -PNPM -Pip -PIP -Cargo -RubyGems - -Swagger -OpenAPI -Markdown -MDX -Storybook -TypeDoc -JSDoc - -MySQL -PostgreSQL -MongoDB -Redis -Elasticsearch -DynamoDB - -Linux -Unix -macOS -iOS - -Firefox -Chromium -WebKit - -config -ctx -desc -dir -elem -err -len -msg -num -obj -prev -proc -ptr -req -res -str -tmp -val -vars - -todo -href -lang -nav -prev -next -toc -``` - - - 请注意,出于安全原因,我们不支持任何绝对路径的 `stylesPath`,以及包含 `..` 的 `stylesPath`。请使用相对路径,并将 `stylesPath` 包含在你的存储库中。 - - -
- #### 包 -
- -Vale 支持一系列[包](https://vale.sh/docs/keys/packages),可用于检查拼写和样式错误。 -你在存储库中按正确的 `stylesPath` 放置的任何包都会被自动安装,并用于你的 Vale 配置。 - -对于未包含在存储库中的包,你可以从 [Vale package registry](https://vale.sh/explorer) 指定任意包,它们会被自动下载并用于你的 Vale 配置。 - - - 请注意,出于安全原因,我们不支持自动下载不来自 [Vale package registry](https://vale.sh/explorer) 的包。 - - -
- #### 在 `MDX` 中使用 Vale -
- -Vale 并不原生支持 `MDX`,但 Vale 的作者提供了一个[自定义扩展](https://github.com/errata-ai/MDX)来实现支持。 - -如果你不想使用此扩展,我们建议在 `.vale.ini` 文件中加入以下几行: - -```ini -[formats] -mdx = md - -[*.mdx] -CommentDelimiters = {/*, */} - -TokenIgnores = (?sm)((?:import|export) .+?$), \ -(?)(?!`), \ -(<[A-Z]\w+>.+?<\/[A-Z]\w+>) - -BlockIgnores = (?sm)^(<\w+\n .*\s\/>)$, \ -(?sm)^({.+.*}) -``` - -要在文档中使用 Vale 的文内注释,请采用 MDX 风格的注释 `{/* ... */}`。如果你在配置中启用 `CommentDelimiters = {/*, */}` [设置](https://vale.sh/docs/keys/commentdelimiters),Vale 会在 lint 过程中自动识别这些注释。这样你就可以轻松使用 Vale 的内置功能,比如跳过某些行或部分。 - -```mdx -{/* vale off */} - -此文本将被 Vale 忽略 - -{/* vale on */} -``` - -如果你选择不使用 `CommentDelimiters`,但仍要使用 Vale 的注释,则必须将所有 Vale 注释包裹在 MDX 注释 `{/* ... */}` 中。例如: - -```mdx -{/* */} - -此文本将被 Vale 忽略 - -{/* */} -``` - -这些注释标签在 Mintlify 组件内不受支持,但可以在文档的根级任意位置使用。 diff --git a/zh/settings/custom-404-page.mdx b/zh/settings/custom-404-page.mdx deleted file mode 100644 index 8422ef25f..000000000 --- a/zh/settings/custom-404-page.mdx +++ /dev/null @@ -1,46 +0,0 @@ ---- -title: "自定义 404 页面" -description: "自定义 404 错误页面的标题和说明" -icon: "file-warning" ---- - -你可以自定义当用户访问失效或缺失链接时显示的 404 错误页面的标题和说明。 - -在自定义 404 页面时,利用说明引导用户前往文档中的相关资源或链接,帮助他们找到所需内容。 - -
- ## 配置 -
- -在 `docs.json` 文件的 `errors.404` 部分配置你的 404 页面: - -```json -"errors": { - "404": { - "redirect": false, - "title": "页面未找到", - "description": "这个_页面_**怎么了**?" - } -} -``` - - -
- ## 参数 -
- - - 当页面未找到时,是否自动重定向到首页。 - - 设为 `true` 会重定向到首页。 - - 设为 `false` 将显示自定义 404 页面。 - - - - 404 错误页面的自定义标题。此项将替换默认的“Page not found”标题。 - - - - 404 错误页面的自定义说明。支持 Markdown 格式。 - \ No newline at end of file diff --git a/zh/settings/custom-domain.mdx b/zh/settings/custom-domain.mdx deleted file mode 100644 index 19d3b99a9..000000000 --- a/zh/settings/custom-domain.mdx +++ /dev/null @@ -1,55 +0,0 @@ ---- -title: "自定义域名" -description: "将文档托管在你的网站自定义域名下" -icon: "globe" ---- - -要在自定义域名下托管文档,你需要先在 Mintlify 设置中填写所需的自定义域名,并在你的域名服务商处配置 DNS(域名系统)记录。 - - - 想设置类似 `mintlify.com/docs` 的自定义子目录?请查看[自定义子目录](/zh/advanced/subpath/cloudflare)文档。 - - -
- ## 控制台设置 -
- -1. 前往你的[控制台](https://dashboard.mintlify.com) -2. 选择「设置」 -3. 选择「域名设置」 -4. 输入你想使用的自定义域名,例如:`docs.mintlify.com` - - - 自定义域名 - - 自定义域名 - - -
- ## 配置你的 DNS -
- -1. 在域名提供商的网站中,进入你的域名的 DNS 设置页面。 -2. 新建一条 DNS 记录,并输入以下值: - -```bash -CNAME | docs | cname.vercel-dns.com. -``` - - - DNS - - -
- ## 面向特定提供商的设置 -
- - - - 如果 Vercel 是你的域名提供商,你必须添加一个用于验证的 `TXT` 记录。提交自定义域名后,这些信息会显示在你的控制台中,并通过电子邮件发送给你。 - - - - 如果 Cloudflare 是你的 DNS 提供商,你必须在 HTTPS 设置中启用“Full (strict)”安全选项。 - - \ No newline at end of file diff --git a/zh/settings/custom-scripts.mdx b/zh/settings/custom-scripts.mdx deleted file mode 100644 index 8ec60b335..000000000 --- a/zh/settings/custom-scripts.mdx +++ /dev/null @@ -1,195 +0,0 @@ ---- -title: "自定义脚本" -description: "通过自定义 CSS 和 JS 完全定制你的文档" -icon: "code" ---- - -使用 CSS 为 HTML 元素设置样式,或添加自定义 CSS 和 JavaScript,以全面定制文档的外观与体验。 - -
- ## 使用 Tailwind CSS 进行样式设计 -
- -使用 Tailwind CSS v3 为 HTML 元素设置样式。你可以控制布局、间距、颜色及其他视觉属性。常见的类包括: - -* `w-full` - 宽度占满容器 -* `aspect-video` - 16:9 宽高比 -* `rounded-xl` - 大号圆角 -* `block`, `hidden` - 显示控制 -* `dark:hidden`, `dark:block` - 深色模式下的可见性 - -不支持 Tailwind CSS 的任意值语法。需要自定义值时,请改用 `style` 属性。 - -```html - -``` - - -
- ## 自定义 CSS -
- -将 CSS 文件添加到你的存储库后,其中定义的类名会自动生效,并可在所有 `MDX` 文件中使用。 - -
- ### 添加 `style.css` -
- -例如,你可以添加下面的 `style.css` 文件来自定义导航栏和页脚的样式。 - -```css -#navbar { - background: "#fffff2"; - padding: 1rem; -} - -footer { - margin-top: 2rem; -} -``` - - -
- ### 使用标识符和选择器 -
- -Mintlify 提供了一组常用的标识符和选择器,帮助你为 UI 中的重要元素打上标签。 - - - 使用“检查元素”来定位你想自定义的元素及其引用。 - - - - - - APIPlaygroundInput: `api-playground-input` - - AssistantEntry: `assistant-entry` - - AssistantEntryMobile: `assistant-entry-mobile` - - Banner: `banner` - - ChangelogFilters: `changelog-filters` - - ChangelogFiltersContent: `changelog-filters-content` - - ChatAssistantSheet: `chat-assistant-sheet` - - ChatAssistantTextArea: `chat-assistant-textarea` - - ContentArea: `content-area` - - ContentContainer: `content-container` - - ContentSideLayout: `content-side-layout` - - Footer: `footer` - - Header: `header` - - NavBarTransition: `navbar-transition` - - NavigationItems: `navigation-items` - - Navbar: `navbar` - - PageContextMenu: `page-context-menu` - - PageContextMenuButton: `page-context-menu-button` - - PageTitle: `page-title` - - Pagination: `pagination` - - Panel: `panel` - - RequestExample: `request-example` - - ResponseExample: `response-example` - - SearchBarEntry: `search-bar-entry` - - SearchBarEntryMobile: `search-bar-entry-mobile` - - SearchInput: `search-input` - - Sidebar: `sidebar` - - SidebarContent: `sidebar-content` - - TableOfContents: `table-of-contents` - - TableOfContentsContent: `table-of-contents-content` - - TableOfContentsLayout: `table-of-contents-layout` - - TopbarCtaButton: `topbar-cta-button` - - - - Accordion: `accordion` - - AccordionGroup: `accordion-group` - - AlmondLayout: `almond-layout` - - AlmondNavBottomSection: `almond-nav-bottom-section` - - AlmondNavBottomSectionDivider: `almond-nav-bottom-section-divider` - - Anchor: `nav-anchor` - - Anchors: `nav-anchors` - - APISection: `api-section` - - APISectionHeading: `api-section-heading` - - APISectionHeadingSubtitle: `api-section-heading-subtitle` - - APISectionHeadingTitle: `api-section-heading-title` - - Callout: `callout` - - Card: `card` - - CardGroup: `card-group` - - ChatAssistantSheet: `chat-assistant-sheet` - - ChatAssistantSheetHeader: `chat-assistant-sheet-header` - - ChatAssistantSheetContent: `chat-assistant-sheet-content` - - ChatAssistantInput: `chat-assistant-input` - - ChatAssistantSendButton: `chat-assistant-send-button` - - CodeBlock: `code-block` - - CodeGroup: `code-group` - - Content: `mdx-content` - - DropdownTrigger: `nav-dropdown-trigger` - - DropdownContent: `nav-dropdown-content` - - DropdownItem: `nav-dropdown-item` - - DropdownItemTextContainer: `nav-dropdown-item-text-container` - - DropdownItemTitle: `nav-dropdown-item-title` - - DropdownItemDescription: `nav-dropdown-item-description` - - DropdownItemIcon: `nav-dropdown-item-icon` - - Expandable: `expandable` - - Eyebrow: `eyebrow` - - FeedbackToolbar: `feedback-toolbar` - - Field: `field` - - Frame: `frame` - - Icon: `icon` - - Link: `link` - - LoginLink: `login-link` - - Logo: `nav-logo` - - Mermaid: `mermaid` - - MethodNavPill: `method-nav-pill` - - MethodPill: `method-pill` - - NavBarLink: `navbar-link` - - NavTagPill: `nav-tag-pill` - - NavTagPillText: `nav-tag-pill-text` - - OptionDropdown: `option-dropdown` - - PaginationNext: `pagination-next` - - PaginationPrev: `pagination-prev` - - PaginationTitle: `pagination-title` - - Panel: `panel` - - SidebarGroup: `sidebar-group` - - SidebarGroupIcon: `sidebar-group-icon` - - SidebarGroupHeader: `sidebar-group-header` - - SidebarNavGroupDivider: `sidebar-nav-group-divider` - - SidebarTitle: `sidebar-title` - - Step: `step` - - Steps: `steps` - - Tab: `tab` - - Tabs: `tabs` - - TabsBar: `nav-tabs` - - TabsBarItem: `nav-tabs-item` - - TableOfContents: `toc` - - TableOfContentsItem: `toc-item` - - Tooltip: `tooltip` - - TopbarRightContainer: `topbar-right-container` - - TryitButton: `tryit-button` - - Update: `update` - - - - - 随着平台演进,引用与常见元素的样式可能会变更。请谨慎使用自定义样式。 - - -
- ## 自定义 JavaScript -
- -自定义 JS 允许你在全局添加自定义可执行代码,相当于在每个页面都插入一个包含 JS 代码的 `