发布文章到 GitLab

连接一次 GitLab，你就可以将任何 Clevera 文章作为 Markdown 文件发布到 GitLab 项目中，随时可用于文档站点、docs/ 文件夹或项目手册。本文介绍了如何连接、选择项目和文件夹、文件外观以及更新的工作方式。

开始之前#

• **计划：**发布到 GitLab 是 Pro 和 Custom 计划的一部分。在 Free 和 Starter 计划中，发布选项卡会显示“发布到你的工具包含在 Pro 计划中”。请参阅 选择计划。
• **在 Clevera 中的角色：**只有工作区所有者或管理员可以连接或断开 GitLab。一旦连接，任何可以编辑文章的人都可以发布它。
• **仅限 GitLab.com：**Clevera 连接到 GitLab.com。不支持自托管的 GitLab 服务器。
• **在 GitLab 中的角色：**Clevera 会列出连接账户拥有“开发”角色或更高权限的项目。要提交到受保护的默认分支，该账户通常需要“维护者”权限（请参阅 受保护分支）。
• **文章：**你发布的是属于视频或录制内容的文章。请先生成它；请参阅 将录制内容转换为文章。

发布不消耗额度。

连接 GitLab#

1. 打开集成#

   在侧边栏中，打开工作区菜单并选择集成。在可用集成（或开发选项卡）下找到 GitLab，然后点击连接。

2. 登录 GitLab 并授权#

   如果尚未登录，请登录 GitLab.com。GitLab 会要求你使用以下范围授权 Clevera：

   GitLab 范围	原因
   api	GitLab 的文件 API 需要它来创建和更新文件
   read_user	以便在 Clevera 中显示你的 GitLab 用户名
   read_repository	以检查文件是否已存在
   write_repository	以提交 Markdown 文件及其图片

   点击授权。

3. 检查连接#

   你将返回到集成页面，并看到“GitLab 已成功连接到”以及你的 GitLab 用户名。GitLab 会移动到已连接列表，并带有已连接徽章。在你发布任何内容之前，它会显示“尚未发布任何内容”。

发布文章#

1. 打开发布选项卡#

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

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

2. 选择项目和文件夹#

   在发布位置下，选择：

   字段	选择内容	备注
   存储库	存放文件的 GitLab 项目	你拥有“开发”或更高权限的项目，按最近更新排序。第一个项目会被默认选中
   文件夹	路径，例如 docs 或 articles/guides	“Markdown 文件在此处创建。留空则存放在存储库根目录。”默认为 docs。尚不存在的文件夹会被自动创建

   Clevera 会记住你下次的选择。

   

3. 发布#

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

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

文件存放位置#

• **分支：**项目的默认分支（通常为 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>。
• **提交作者：**连接该集成的 GitLab 账户。

受保护分支#

GitLab 默认保护默认分支，通常只有“维护者”可以推送代码。如果连接的账户是“开发”角色，提交会被拒绝，并显示“GitLab 拒绝了提交：你需要开发人员或更高权限，且分支不得受保护。”你可以赋予该账户“维护者”角色，或者在项目的设置 → 存储库 → 受保护分支中允许“开发”人员推送。

文件外观#

Clevera 编写的 Markdown 可由 GitLab 渲染，顶部包含一个简短的 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 的链接，一段时间后会过期；再次发布以更新它。

与文档站点一起使用#

如果 GitLab Pages 或其他静态站点生成器（如 MkDocs、Docusaurus 或 Hugo）从项目构建你的文档，请将文件夹指向它读取的文件夹。每次发布都是一次正常的提交，因此你的流水线会照常运行。大多数生成器会从 front matter 中读取 title 并忽略它们不知道的字段。

更新已发布的文章#

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

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

如果标题在 Clevera 中发生了更改，文件名也会更改，因此发布会创建一个与旧文件并列的新文件。请自行在 GitLab 中删除或重命名旧文件。Clevera 不会删除你项目中的任何文件。

断开 GitLab 连接#

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

断开连接会删除 Clevera 的令牌。若要同时撤销 Clevera 在 GitLab 上的访问权限，请打开你的 GitLab 头像菜单 → 编辑个人资料 → 应用程序，在已授权的应用程序下找到 Clevera 并点击撤销。

故障排除#

相关内容#