将文章发布到 GitHub

连接一次 GitHub，你就可以将任何 Clevera 文章作为 Markdown 文件发布到存储库中，适用于文档网站、wiki 风格的 docs/ 文件夹或 README 合集。本文介绍了如何连接、选择存储库和文件夹、文件的外观以及更新的工作方式。

开始之前#

• 计划： 发布到 GitHub 是 Pro 和 Custom 计划的一部分。在 Free 和 Starter 计划中，发布选项卡会显示“发布到你的工具中已包含在 Pro 计划内”。请参阅 选择计划。
• 在 Clevera 中的角色： 只有工作区所有者或管理员可以连接或断开 GitHub。一旦连接，任何可以编辑文章的人都可以发布它。
• 在 GitHub 中的访问权限： 进行连接的人员需要对你想要发布到的存储库拥有写入权限，并有权在该个人账户或组织上安装 GitHub App（或者由组织所有者批准）。
• 文章： 你可以发布属于视频或录制内容的文章。请先生成它；请参阅 将录制内容转换为文章。

发布不消耗额度。

连接 GitHub#

1. 打开集成#

   在侧边栏中，打开工作区菜单并选择集成。在可用集成（或开发选项卡）下找到 GitHub，然后点击连接。当你指向该卡片时，按钮会出现。

   

2. 在 GitHub 上授权 Clevera#

   GitHub 会要求你授权 Clevera AI 应用。它请求读取你的组织成员身份的权限，以便 Clevera 可以列出你所属的账户。点击授权。

3. 在你的存储库上安装该应用#

   随后 GitHub 会打开 Clevera AI 应用安装页面。选择你的个人账户或组织，然后选择所有存储库或仅选择存储库。该应用请求以下权限：

   GitHub 权限	原因
   内容：读取和写入	用于创建和更新 Markdown 文件及其图片
   元数据：只读	GitHub 对每个应用的要求；允许 Clevera 列出存储库

   点击安装。对你想要发布到的每个组织重复此操作。

4. 检查连接#

   回到集成页面，GitHub 会移动到已连接列表中，显示你的 GitHub 账户或组织名称以及已连接徽章。在你发布任何内容之前，它会显示“尚未发布任何内容”。

   

稍后添加或移除存储库#

Clevera 只能看到安装了该应用的存储库。要更改此设置，请打开集成，点击 GitHub，然后在访问权限下点击存储库访问权限。在 GitHub 上，打开该账户，点击配置并更改存储库列表。新的存储库会在你下次打开发布选项卡时显示。

发布文章#

1. 打开发布选项卡#

   在编辑器中，点击分享并打开发布选项卡。在发布文章下，点击准备发布下方的 GitHub 磁贴。

   文章将以你在编辑器中打开的语言发布。若要发布翻译版本，请先在顶部栏切换语言。

2. 选择账户、存储库和文件夹#

   在发布位置下，选择：

   字段	选择内容	说明
   账户	你的个人账户或组织	仅当你的存储库属于多个账户时显示
   存储库	文件的存储库	按最近更新排序。第一个会被默认选中
   文件夹	路径，例如 docs 或 articles/guides	“Markdown 文件在此处创建。留空则位于存储库根目录。”默认为 docs。尚不存在的文件夹会被自动创建

   Clevera 会记住你下次的选择。

   

3. 发布#

   点击发布到 GitHub。你会看到“正在 GitHub 中查找现有副本”，然后是正在写入页面。完成后，你会看到“已发布到 GitHub”。点击在 GitHub 中打开以查看文件。

   你可以在发布过程中关闭分享窗口；完成后会有通知提醒你。

文件去向#

• 分支： 存储库的默认分支（通常为 main）。Clevera 直接提交到该分支；它不会打开拉取请求，你也不能选择其他分支。
• 文件名： 标题的小写形式，空格转换为连字符，以 .md 结尾。“Create your first invoice”变为 create-your-first-invoice.md。其他脚本或带重音符号的标题会先拼写为拉丁字母（“Créer une facture”变为 creer-une-facture.md）。如果标题无法拼写（例如仅由表情符号组成），则会获得一个简短的固定代码（article- 加 8 个字符）。名称在 80 个字符处截断。
• 图片： 文章的截图会放入同一文件夹内的 assets/<file name>/ 中，并在同一次提交中完成。
• 提交消息： Add article: <title>，或更新现有文件时的 Update article: <title>。
• 提交作者： 连接该集成的 GitHub 账户。

文件的外观#

Clevera 编写 GitHub 风格的 Markdown，并在顶部包含一个简短的 front matter 块：

---
title: "Create your first invoice"
created_at: "2026-10-12T09:30:00+00:00"
updated_at: "2026-10-12T10:05:00+00:00"
source: "Clevera"
---

文章来源的视频不会添加到文件中。放置在文章内的 Clevera 视频仅在开启视频分享链接时才会变为指向其播放器的链接。请参阅 在文章中展示视频。

图片#

截图会与文件一起提交到你的存储库，Markdown 通过相对路径 (assets/<file name>/…) 链接到它们。它们在没有 Clevera 的情况下也能正常工作，并且在私有存储库中，它们会像存储库的其他部分一样保持私密。

你上传到文章中的视频文件不会被提交。它保持为指向 Clevera 的链接，一段时间后会过期；再次发布以更新它。

与文档网站配合使用#

大多数从存储库构建的静态网站生成器（如 Docusaurus、MkDocs、Jekyll 或 Hugo）会从 front matter 中读取 title 并忽略它们不认识的字段。常见设置：

1. 将文件夹指向你的文档网站读取的文件夹，例如 docs 或 content/guides。
2. 在那里发布每篇文章；你网站的常规构建会获取新的提交。
3. 检查你的生成器是否渲染 GitHub 提醒、数学和 <details>；有些会将提醒显示为普通引用。

更新已发布的文章#

发布是单向的。你在 Clevera 中所做的编辑会保留在 Clevera 中，直到你再次发布；而在 GitHub 上对文件所做的更改永远不会同步回 Clevera。

当你发布到同一个存储库和文件夹时，Clevera 会找到同名文件并显示“此文章已存在于 GitHub 中”。点击查看它以打开现有文件，然后选择：

如果标题在 Clevera 中发生了更改，文件名也会随之更改，因此发布操作会在旧文件旁边创建一个新文件。请自行在 GitHub 上删除或重命名旧文件。

Clevera 中的任何操作都不会删除你存储库中的文件。

断开 GitHub 连接#

1. 打开 集成，点击 GitHub 行上的 ⋯ 菜单并选择 断开连接（或点击 GitHub，然后点击 断开连接）。
2. 确认。"你将无法再从编辑器发布到该位置。你已发布的内容将保留在 GitHub 中。"

断开连接会删除 Clevera 的访问令牌。若要同时移除 Clevera 在 GitHub 上的访问权限，请卸载 Clevera AI 应用（GitHub 设置 → 应用程序 → 已安装的 GitHub 应用 → 配置 → 卸载），并在 已授权的 GitHub 应用 下撤销授权。

故障排除#

相关内容#