發布文章到 GitLab

連接一次 GitLab，您就可以將任何 Clevera 文章以 Markdown 檔案形式發布到 GitLab 專案中，隨時可用於文件網站、docs/ 資料夾或專案手冊。本文涵蓋了連接方式、選擇專案和資料夾、檔案外觀以及更新運作方式。

開始之前#

• 方案： 發布到 GitLab 是 Pro 和 Custom 方案的一部分。在 Free 和 Starter 方案中，發布標籤頁會顯示「發布到您的工具包含在 Pro 方案中」。請參閱 選擇方案。
• 在 Clevera 中的角色： 只有工作區擁有者或管理員可以連接或中斷 GitLab 連線。一旦連接，任何可以編輯文章的人都可以發布它。
• 僅限 GitLab.com： Clevera 連接到 GitLab.com。不支援自架的 GitLab 伺服器。
• 在 GitLab 中的角色： Clevera 會列出連接帳戶具有開發者 (Developer) 或更高權限的專案。若要提交到受保護的預設分支，該帳戶通常需要維護者 (Maintainer) 權限（請參閱 受保護的分支）。
• 文章： 您發布的是屬於影片或錄製內容的文章。請先產生它；請參閱 將錄製內容轉為文章。

發布功能不消耗點數。

連接 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 寫入 GitLab 可渲染的 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 連結；請再次發布以更新它。

與文件網站搭配使用#

如果 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 並點擊撤銷。

疑難排解#

相關#