Documentation Style Guide · Gitlab 中文文檔

# Documentation Style Guide > 原文：[https://docs.gitlab.com/ee/development/documentation/styleguide.html](https://docs.gitlab.com/ee/development/documentation/styleguide.html) * [Documentation is the single source of truth (SSOT)](#documentation-is-the-single-source-of-truth-ssot) * [Why a single source of truth](#why-a-single-source-of-truth) * [All information](#all-information) * [All media types](#all-media-types) * [No special types](#no-special-types) * [Link instead of summarize](#link-instead-of-summarize) * [Organize by topic, not by type](#organize-by-topic-not-by-type) * [Docs-first methodology](#docs-first-methodology) * [Markdown](#markdown) * [HTML in Markdown](#html-in-markdown) * [Markdown Rules](#markdown-rules) * [Markdown rule `MD044/proper-names` (capitalization)](#markdown-rule-md044proper-names-capitalization) * [Structure](#structure) * [Folder structure overview](#folder-structure-overview) * [Work with directories and files](#work-with-directories-and-files) * [Avoid duplication](#avoid-duplication) * [References across documents](#references-across-documents) * [Structure within documents](#structure-within-documents) * [Language](#language) * [Point of view](#point-of-view) * [Capitalization](#capitalization) * [Language to avoid](#language-to-avoid) * [Word usage clarifications](#word-usage-clarifications) * [Contractions](#contractions) * [Text](#text) * [Emphasis](#emphasis) * [Punctuation](#punctuation) * [Placeholder text](#placeholder-text) * [Lists](#lists) * [Ordered vs. unordered lists](#ordered-vs-unordered-lists) * [Markup](#markup) * [Punctuation](#punctuation-1) * [Nesting inside a list item](#nesting-inside-a-list-item) * [Tables](#tables) * [Creation guidelines](#creation-guidelines) * [Feature tables](#feature-tables) * [Quotes](#quotes) * [Headings](#headings) * [Heading titles](#heading-titles) * [Anchor links](#anchor-links) * [Links](#links) * [Basic link criteria](#basic-link-criteria) * [Links to internal documentation](#links-to-internal-documentation) * [Links to external documentation](#links-to-external-documentation) * [Links requiring permissions](#links-requiring-permissions) * [Link to specific lines of code](#link-to-specific-lines-of-code) * [Navigation](#navigation) * [Images](#images) * [Capture the image](#capture-the-image) * [Save the image](#save-the-image) * [Add the image link to content](#add-the-image-link-to-content) * [Remove image shadow](#remove-image-shadow) * [Compress images](#compress-images) * [Videos](#videos) * [Link to video](#link-to-video) * [Embed videos](#embed-videos) * [Code blocks](#code-blocks) * [GitLab SVG icons](#gitlab-svg-icons) * [Use GitLab SVGs to describe UI elements](#use-gitlab-svgs-to-describe-ui-elements) * [Alert boxes](#alert-boxes) * [Note](#note) * [When to use](#when-to-use) * [Tip](#tip) * [Caution](#caution) * [Danger](#danger) * [Blockquotes](#blockquotes) * [Terms](#terms) * [Merge Requests (MRs)](#merge-requests-mrs) * [Describe UI elements](#describe-ui-elements) * [Verbs for UI elements](#verbs-for-ui-elements) * [Other Verbs](#other-verbs) * [GitLab versions and tiers](#gitlab-versions-and-tiers) * [Text for documentation requiring version text](#text-for-documentation-requiring-version-text) * [Versions in the past or future](#versions-in-the-past-or-future) * [Importance of referencing GitLab versions and tiers](#importance-of-referencing-gitlab-versions-and-tiers) * [Products and features](#products-and-features) * [Avoid line breaks in names](#avoid-line-breaks-in-names) * [Product badges](#product-badges) * [How it works](#how-it-works) * [Specific sections](#specific-sections) * [GitLab restart](#gitlab-restart) * [Installation guide](#installation-guide) * [Configuration documentation for source and Omnibus installations](#configuration-documentation-for-source-and-omnibus-installations) * [Troubleshooting](#troubleshooting) * [Feature flags](#feature-flags) * [API](#api) * [API topic template](#api-topic-template) * [Fake user information](#fake-user-information) * [Fake URLs](#fake-urls) * [Fake tokens](#fake-tokens) * [Method description](#method-description) * [cURL commands](#curl-commands) * [cURL Examples](#curl-examples) * [Simple cURL command](#simple-curl-command) * [cURL example with parameters passed in the URL](#curl-example-with-parameters-passed-in-the-url) * [Post data using cURL’s `--data`](#post-data-using-curls---data) * [Post data using JSON content](#post-data-using-json-content) * [Post data using form-data](#post-data-using-form-data) * [Escape special characters](#escape-special-characters) * [Pass arrays to API calls](#pass-arrays-to-api-calls) # Documentation Style Guide[](#documentation-style-guide "Permalink") 本文檔定義了 GitLab 文檔內容和文件的標準. 有關該文檔的更多信息，請參見《 [文檔指南》](index.html) . 有關遵循該準則的編程幫助，請參閱" [測試"](index.html#testing) . 請參閱 GitLab 手冊，以獲取適用于所有 GitLab 內容（不僅是文檔）的進一步的[寫作風格指南](https://about.gitlab.com/handbook/communication/#writing-style-guidelines) . ## Documentation is the single source of truth (SSOT)[](#documentation-is-the-single-source-of-truth-ssot "Permalink") ### Why a single source of truth[](#why-a-single-source-of-truth "Permalink") GitLab 產品和功能的文檔是 SSOT，其中包含與實施，使用和故障排除有關的所有信息. 它與新產品和功能保持一致，并不斷改進，以提高清晰度，準確性和完整性. 該策略可以防止信息孤島，從而更輕松地查找有關 GitLab 產品的信息. 它還可以就我們包含在文檔中的內容種類提供決策. ### All information[](#all-information "Permalink") 只要可以以充分詳細的警告和警告的形式提供適當的上下文，就可以包括解決可能很少見或被認為是"危險"的解決問題的措施. 應該包括這類內容，因為它可能對其他人有幫助，并且在正確解釋后，其好處大于風險. 如果您認為發現此規則有例外，請與技術寫作團隊聯系. 無論用戶遇到何種情況，我們都會將所有故障排除信息添加到文檔中. 對于" [疑難解答"部分](#troubleshooting) ，GitLab 支持人員可以自己合并添加項. ### All media types[](#all-media-types "Permalink") 如果內容與讀者相關，則包括任何媒體類型/來源. 您可以自由地包含或鏈接演示文稿，圖表，視頻等；不管它最初是為誰創作的，如果對我們的聽眾有幫助，我們都可以將其包括在內. * 如果使用的圖像具有單獨的源文件（例如，矢量或圖表格式），則將該圖像鏈接到源文件，以便任何人都可以重用或更新它. * 除非從引用來源中引用有限的內容，否則請勿復制和粘貼其他來源的內容. 通常，最好用您自己的話語重述相關信息或鏈接到其他來源. ### No special types[](#no-special-types "Permalink") 在軟件行業中，最佳實踐是組織不同類型的文檔. 例如， [Divio 建議](https://www.divio.com/blog/documentation/) ： 1. Tutorials 2. 入門指南 3. Explanation 4. 參考（例如，詞匯表）在 GitLab，我們的月度版本中有太多產品更改，以至于我們無法承受持續更新多種類型的信息的負擔. 如果我們有多種類型，則信息將過時. 因此，我們只有一個文檔[模板](structure.html) . 我們目前不區分特定的文檔類型，盡管一旦文檔達到成熟度和質量的未來階段，我們可以重新考慮此政策. 如果您正在閱讀此書，那么盡管我們不斷進行改進，但仍未達到這一點. ### Link instead of summarize[](#link-instead-of-summarize "Permalink") 有誘惑力將信息匯總在另一頁上. 這將導致信息存在于兩個地方. 相反，鏈接到 SSOT 并解釋為什么使用信息很重要. ### Organize by topic, not by type[](#organize-by-topic-not-by-type "Permalink") 除了頂級受眾類型的文件夾（例如， `administration` ）之外，我們還按主題而不是按類型組織內容，因此可以在主題的單一來源（SSOT）部分中盡可能輕松地找到內容物. 例如，不要創建相似媒體類型的分組. 例如： * Glossaries. * FAQs. * 所有文章或視頻的集合. 按類型對內容進行這種分組使得難以瀏覽所需信息，并且難以維護最新內容. 而是按主題組織內容（例如，與 CI 相關的所有內容都放在一起），并在任何相關內容之間進行交叉鏈接. ### Docs-first methodology[](#docs-first-methodology "Permalink") 我們采用**文檔優先的方法，**以幫助確保文檔保持完整且受信任的資源，并使有關 GitLab 使用的交流更加有效. * 如果文檔中存在問題的答案，請共享文檔鏈接，而不要改寫信息. * 當您遇到 GitLab 文檔中沒有的新信息時（例如，在處理支持案例或測試功能時），第一步應該是創建合并請求（MR），以將該信息添加到文檔中. 然后，您可以共享 MR 以便傳達此信息. 如上所述，對將來的 GitLab 使用或故障排除有用的新信息不應直接寫在論壇或其他消息系統中，而應添加到文檔 MR 中，然后再進行引用. 請注意，除其他任何文檔更改外，您還可以： * 如果不存在，請在文檔中添加" [疑難解答"部分](#troubleshooting) . * 取消注釋并使用占位符疑難解答部分，該部分包含在我們的[文檔模板中](structure.html#template-for-new-docs) （如果存在）. 我們向文檔自如地添加有用信息的次數越多，文檔就越會被用來（更成功）有效地完成任務和解決問題. 如果您在考慮，創作或編輯文檔時遇到問題，請提及適用于[DevOps 階段](https://about.gitlab.com/handbook/product/product-categories/#devops-stages)的編寫者，以`#docs`或 GitLab 中的 Slack 的技術寫作團隊提出. 否則，請盡力而為. 它并不一定是完美的. 團隊很樂意審查和改進您的內容. 在開始您的第一個文檔 MR 之前，請查閱[文檔指南](index.html) . 具有與文檔不同的任何形式的知識庫都將違反文檔優先方法，因為其內容會與文檔重疊. ## Markdown[](#markdown "Permalink") 所有的 GitLab 文檔都是使用[Markdown](https://en.wikipedia.org/wiki/Markdown)編寫的. [文檔網站](https://s0docs0gitlab0com.icopy.site)使用 GitLab Kramdown 作為 Markdown 渲染引擎. 有關完整的 Kramdown 參考，請參閱《 [GitLab Markdown Kramdown 指南》](https://about.gitlab.com/handbook/markdown-guide/) . [`gitlab-kramdown`](https://gitlab.com/gitlab-org/gitlab_kramdown) Ruby gem 將來將支持所有[GFM 標記](../../user/markdown.html) . 也就是說，所有標記都支持在 GitLab 應用程序本身中顯示. 目前，請按照鏈接的樣式指南中的規則使用常規的 Markdown 標記. 請注意，特定于 Kramdown 的標記（例如`{:.class}` ）不會在[`/help`](index.html#gitlab-help)下的 GitLab 實例上正確呈現. ### HTML in Markdown[](#html-in-markdown "Permalink") 硬編碼的 HTML 是有效的，盡管在使用`/help`時不建議使用. 只要允許 HTML，就可以： * Markdown 中沒有等效的標記. * 高級表是必需的. * 需要特殊的樣式. * 由技術作家審查和批準. ### Markdown Rules[](#markdown-rules "Permalink") GitLab 通過使用[markdownlint](index.html#markdownlint) [測試文檔更改](index.html#testing)來確保所有文檔中使用的 Markdown 是一致的，并且易于查看和維護. 當任何文檔的 Markdown 格式存在問題時，此棉絨測試將失敗，該問題可能導致頁面在 GitLab 中無法正確呈現. 當文檔使用非標準 Markdown（可以正確顯示，但不是 GitLab 文檔的當前標準）時，它也會失敗. #### Markdown rule `MD044/proper-names` (capitalization)[](#markdown-rule-md044proper-names-capitalization "Permalink") 可能引起混亂的規則是`MD044/proper-names` ，因為可能無法立即弄清是什么導致 markdownlint 失敗或如何糾正失敗. 此規則檢查每個項目的`.markdownlint.json`文件中列出的已知單詞的列表，以驗證是否正確使用了大寫字母和反引號. 反引號中的單詞將被 markdownlint 忽略. 通常，產品名稱應緊跟產品，協議等正式名稱的大寫字母. 請參閱[`.markdownlint.json`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/.markdownlint.json)以獲取有關 GitLab 文檔中經過適當大寫測試的單詞. 如果使用不正確的大小寫，則某些示例將失敗： * MinIO（需要資本`IO` ） * NGINX（需要所有資金） * runit（需要小寫`r` ）此外，反引號中必須包含命令，參數，值，文件名等. 例如： * "在您的`.gitlab.yml`更改`needs`關鍵字……" * `needs`是一個參數，而`.gitlab.yml`是一個文件，因此兩者都需要反引號. 此外， `.gitlab.yml`沒有`.gitlab.yml` G 或 L，它將使 markdownlint 失敗而沒有反引號. * “Run `git clone` to clone a Git repository…” * `git clone`是命令，因此它必須是小寫字母，而 Git 是乘積，因此它必須具有大寫字母 G. ## Structure[](#structure "Permalink") 因為我們希望文檔成為 SSOT，所以我們應該[按主題（而不是類型）進行組織](#organize-by-topic-not-by-type) . ### Folder structure overview[](#folder-structure-overview "Permalink") 該文檔由頂級受眾文件夾[`user`](https://gitlab.com/gitlab-org/gitlab-foss/tree/master/doc/user) ， [`administration`](https://gitlab.com/gitlab-org/gitlab-foss/tree/master/doc/administration)和[`development`](https://gitlab.com/gitlab-org/gitlab-foss/tree/master/doc/development) （貢獻）文件夾分開. Beyond that, we primarily follow the structure of the GitLab user interface or API. 我們的目標是要建立一個清晰的層次結構，并包含有意義的 URL，例如`docs.gitlab.com/user/project/merge_requests/` . 使用這種模式，您可以立即知道您正在導航到有關 Project 功能的用戶相關文檔；特別是關于合并請求. 我們網站的路徑與我們存儲庫的路徑匹配，因此清晰的結構還使文檔更易于更新. 下表顯示了什么樣的文檔. | Directory | 這里屬于什么 | | --- | --- | | `doc/user/` | 與用戶相關的文檔. 可以在 GitLab UI 中完成的所有操作都在這里進行，包括使用`/admin`界面. | | `doc/administration/` | 要求用戶有權訪問安裝了 GitLab 的服務器的文檔. 可以通過 GitLab 界面訪問的管理設置位于`doc/user/admin_area/` . | | `doc/api/` | API 相關文檔. | | `doc/development/` | 與 GitLab 開發相關的文檔，無論是貢獻代碼還是文檔. 相關的流程和樣式指南應該在此處. | | `doc/legal/` | 有關對 GitLab 進行貢獻的法律文件. | | `doc/install/` | 包含有關安裝 GitLab 的說明. | | `doc/update/` | 包含有關更新 GitLab 的說明. | | `doc/topics/` | 每個主題的索引（ `doc/topics/topic-name/index.md` ）：該主題的所有資源. | ### Work with directories and files[](#work-with-directories-and-files "Permalink") 1. 創建新目錄時，請始終以`index.md`文件開頭. 不要使用其他文件名， **也不要**創建`README.md`文件. 2. **請勿**在文件名，目錄名，分支名和任何會生成路徑的文件中使用特殊字符和空格或大寫字母. 3. 創建新文檔時，如果名稱中包含多個單詞，請確保使用下劃線而不是空格或破折號（ `-` ）. 例如，正確的命名應為`import_projects_from_github.md` . 相同的規則適用于圖像. 4. 對于圖像文件，請勿超過 100KB. 5. 不要將視頻文件上傳到產品存儲庫. [鏈接或嵌入視頻](#videos) . 6. 有四個主要目錄， `user` ， `administration` ， `api`和`development` . 7. `doc/user/`目錄具有五個主要子目錄： `project/` ， `group/` ， `profile/` ， `dashboard/`和`admin_area/` . 1. `doc/user/project/`應包含所有與項目相關的文檔. 2. `doc/user/group/`應包含所有與組有關的文檔. 3. `doc/user/profile/`應包含所有與個人資料相關的文檔. 您在`/profile`下導航的每個頁面都應該有其自己的文檔，例如`account.md` ， `applications.md`或`emails.md` . 4. `doc/user/dashboard/`應包含所有與儀表板相關的文檔. 5. `doc/user/admin_area/`應該包含所有與管理員相關的文檔，這些文檔描述了通過訪問 GitLab 的管理界面可以實現的目的（ *不要與需要服務器訪問權限的`doc/administration`混淆* ）. 1. `/admin/application_settings/`下的每個類別都應有自己的文檔，位于`doc/user/admin_area/settings/` . 例如，" **可見性和訪問控制"**類別應具有位于`doc/user/admin_area/settings/visibility_and_access_controls.md` . 8. `doc/topics/`目錄包含與主題相關的技術內容. 必要時創建`doc/topics/topic-name/subtopic-name/index.md` . 應放置與用戶和管理員相關的常規文檔. 9. 目錄`/workflow/` ， `/university/`和`/articles/`已被**棄用** ，并且大多數文檔已通過較小的迭代移動到了正確的位置. 如果您不確定文檔或內容添加應該放在哪里，那么這不會阻止您創作和貢獻. 您可以根據自己的最佳判斷，然后要求 MR 的審閱者確認您的決定，和/或在此過程的任何階段詢問技術作家. 技術寫作團隊將審查所有文檔更改，無論如何，并且如果有合適的位置，可以移動內容. ### Avoid duplication[](#avoid-duplication "Permalink") 不要在多個地方包含相同的信息. [鏈接到 SSOT.](#link-instead-of-summarize) ### References across documents[](#references-across-documents "Permalink") * 給每個文件夾一個 index.md 頁面，該頁面介紹該主題，介紹其中的頁面，并鏈接到其中的頁面（包括任何下一級子路徑的索引頁面）. * 為確保可發現性，請確保每個新文檔或重命名的文檔都從其更高級別的索引頁面和其他相關頁面鏈接. * 當引用其他 GitLab 產品和功能時，至少在第一次提及時，鏈接到它們各自的文檔. * 當引用第三方產品或技術時，請鏈接到其外部站點，文檔和資源. ### Structure within documents[](#structure-within-documents "Permalink") * 包括[結構和模板](structure.html)頁面上所述的所有適用小節. * Structure content in alphabetical order in tables, lists, and so on, unless there is a logical reason not to (for example, when mirroring the UI or an otherwise ordered sequence). ## Language[](#language "Permalink") GitLab 文檔應清晰易懂. * 清楚，簡明并遵守文檔的目標. * 用美國英語和美國語法書寫. （在[`British.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/British.yml)測試.） * 使用包容性語言. ### Point of view[](#point-of-view "Permalink") 在大多數情況下，使用第二人稱（您自己）的觀點是適當的，因為它友好且易于理解. （在[`FirstPerson.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/FirstPerson.yml)測試.） ### Capitalization[](#capitalization "Permalink") * 在 GitLab 中大寫" G"和" L". * 句子大小寫用于： * 標題. * 標簽. * 菜單項. * 紐扣. * 標題. 除非標題中提及產品功能，否則請勿在標題中大寫其他單詞. 例如： * 大寫"問題"在`## What you can do with GitLab Issues` ，但在`## Closing multiple issues`不可接受. * 引用時使用標題大小寫： * [GitLab 功能](https://about.gitlab.com/features/) . 例如，發行板，地緣和亞軍. * GitLab [產品層](https://about.gitlab.com/pricing/) . 例如，GitLab Core 和 GitLab Ultimate. （在[`BadgeCapitalization.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/BadgeCapitalization.yml)測試.） * 第三方產品. 例如，Prometheus，Kubernetes 和 Git. * 方法或方法論. 例如，持續集成，持續部署，Scrum 和敏捷. （在[`.markdownlint.json`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/.markdownlint.json)測試.） **注意：**某些功能也是對象. 例如，" GitLab 的合并請求支持 X"和"為 Z 創建新的合并請求". ### Language to avoid[](#language-to-avoid "Permalink") 創建文檔時，請限制或避免使用以下動詞時態，單詞和短語： * 避免行話. * 避免使用不常見的單詞. * 不要以第一人稱單數形式書寫. （在[`FirstPerson.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/FirstPerson.yml)測試.） * 代替"我"或"我"，而使用"我們"，"您"，"我們"或"一個". * 在可能的情況下，通過寫第二人稱（" you"或命令式）來保持用戶的注意力. * 不要過度使用" that". 在許多情況下，您可以從句子中刪除" that"并提高可讀性. * 避免使用將來時： * 代替"在執行此命令后，GitLab 將顯示結果"，而應使用"在執行此命令后，GitLab 顯示結果". * 僅在將來某個時間實際發生動作或結果時，才使用將來時來表達. * 不要使用斜杠將不同的單詞組合在一起，也不要用"或"代替： * 代替"和/或"，可以考慮使用"或"，或使用其他明智的結構. * 其他示例包括"克隆/獲取"，作者/受讓人和"命名空間/存儲庫名稱". 以適當的方式拆分任何此類實例. * 該規則的例外情況包括公認的技術術語，例如 CI / CD 和 TCP / IP. * We discourage use of Latin abbreviations, such as “e.g.,” “i.e.,” or “etc.,” as even native users of English might misunderstand them. (Tested in [`LatinTerms.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/LatinTerms.yml).) * 代替"即"，使用"即". * 代替"例如"，使用"例如"，"例如"，"例如"或"喜歡". * 代替"等"，可以使用"依此類推"，也可以考慮對其進行編輯，因為它可能含糊不清. * 在談論產品或其功能時，請避免*當前*使用該詞. 該文檔按原樣描述了該產品，而不是將來的某個不確定點. * 避免在增加 GitLab 為其他用戶的性能時使用*可擴展性*一詞. 在其他情況下，可以使用" *縮放"*或" *縮放"*一詞，但對于其他用戶而言，提高 GitLab 性能的參考應將讀者引導至 GitLab [參考架構](../../administration/reference_architectures/index.html)頁面. * 避免使用所有形式的短語" *高可用性"*和" *HA"* ，而是將讀者引導至 GitLab [參考體系結構，](../../administration/reference_architectures/index.html)以獲取有關配置 GitLab 使其隨著時間的推移具有更多用戶所需的性能的信息. * 不要使用褻瀆或 ob 褻. 這樣做可能會對其他用戶和貢獻者產生負面影響，這與 GitLab 的" [多樣性"，"包容性"和"歸屬"](https://about.gitlab.com/handbook/values/#diversity-inclusion)的價值背道而馳. * 避免使用對[種族不敏感的術語或短語](https://www.marketplace.org/2020/06/17/tech-companies-update-language-to-avoid-offensive-terms/) . 例如： * 將*主*數據庫和*輔助*數據庫用于數據庫和服務器關系. * 使用*allowlist*和*denylist*來描述訪問控制列表. ### Word usage clarifications[](#word-usage-clarifications "Permalink") * 不要互換使用" may"和" might"： * 使用"可能"表示發生某事的可能性. "如果跳過此步驟，則導入過程可能會失敗." * 使用"可能"表示允許某人做某事，或者考慮使用"可以". "您可以在此屏幕上選擇一個選項." 或者，"您可以在此屏幕上選擇任一選項." ### Contractions[](#contractions "Permalink") * Use common contractions when it helps create a friendly and informal tone, especially in tutorials, instructional documentation, and [UIs](https://design.gitlab.com/content/punctuation/#contractions). (Tested in [`Contractions.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/Contractions.yml).) | Do | Don’t | | --- | --- | | it’s | 它是 | | can’t | cannot | | wouldn’t | 不會 | | you’re | 你是 | | you’ve | 你有 | | haven’t | 沒有 | | don’t | 不要 | | we’re | 我們是 | | that’s | 那是 | | won’t | 將不會 | * 避免少見的宮縮： | Do | Don’t | | --- | --- | | 他會 | he’d | | 它會 | it’ll | | 應該有 | should’ve | | 那里會 | there’d | * 不要使用帶有專有名詞和動詞的縮略詞. 例如： | Do | Don’t | | --- | --- | | GitLab 正在創建 X | manbetx 客戶端打不開創建 X | * 當您需要強調負面情緒時，不要使用收縮. 例如： | Do | Don’t | | --- | --- | | **不要**為 Y 安裝 X | **不要**將 X 與 Y 一起安裝 | * 不要在參考文檔中使用收縮. 例如： | Do | Don’t | | --- | --- | | **不要**設置限制大于 1000 | **請勿**將限制設置為大于 1000 | | 對于`parameter1` ，默認值為 10 | 對于`parameter1` ，默認值為 10 | * 避免錯誤消息中出現收縮. 例子： | Do | Don’t | | --- | --- | | 不允許對本地主機的請求 | 不允許對本地主機的請求 | | 指定的 URL 不能使用 | 指定的網址無法使用 | ## Text[](#text "Permalink") * [Write in Markdown](#markdown). * 分隔長行（最好最多 100 個字符）可以更輕松地提供有關小塊文本的反饋. * 在新段落中插入一個空行. * 在不同的標記之間插入一個空行（例如，在每個段落，標題，列表等之后）. 例： ``` ## Header Paragraph. - List item 1 - List item 2 ``` ### Emphasis[](#emphasis "Permalink") * 使用雙星號（ `**` ）將單詞或文本標記為粗體（ `**bold**` ）. * 下劃線（ `_` ）用于斜體（ `_italic_` ）文本. * 塊引用使用大于（ `>` ）. ### Punctuation[](#punctuation "Permalink") 檢查下表中 GitLab 文檔的常規標點規則. 檢查以下[列表的](#lists)特定標點規則. | Rule | Example | | --- | --- | | 總是以句號結束完整的句子. | *有關完整概述，請通讀本文檔.* | | 在開始新句子時，請始終在句點之后添加空格. | *有關完整的概述，請查看此文檔. 有關其他參考，請查閱本指南.* | | 不要使用雙空格. （在[`SentenceSpacing.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/SentenceSpacing.yml)測試.） | — | | 不要使用制表符進行縮進. 請改用空格. 您可以將代碼編輯器配置為在按 Tab 鍵時輸出空格而不是制表符. | — | | 在列表中最后一個"和/或"之前使用連續逗號（"牛津逗號"）. （在[`OxfordComma.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/OxfordComma.yml)測試.） | *您可以創建新問題，合并請求和里程碑.* | | 在句子中使用破折號之前和之后，請始終添加空格（例如，用于替換逗號）. | *您應該嘗試這樣做-還是不可以.* | | 總是在冒號后面使用小寫字母. | *相關問題：一種在問題之間建立關系的方法.* | ### Placeholder text[](#placeholder-text "Permalink") 在示例中，編寫者通常會提供除特定于閱讀者的值之外完整的命令或配置. 在這些情況下，使用[`<`和`>`](https://en.wikipedia.org/wiki/Usage_message#Pattern)指出讀者必須用自己的值替換文本的位置. 例如： ``` cp <your_source_directory> <your_destination_directory> ``` ## Lists[](#lists "Permalink") * 始終使用大寫字母開頭列表項，除非它們是反引號或類似的參數或命令. * 始終在列表前后留空行. * 以空格（不是制表符）開頭的行表示[嵌套的子項](#nesting-inside-a-list-item) . ### Ordered vs. unordered lists[](#ordered-vs-unordered-lists "Permalink") 僅當其項目描述要遵循的步驟序列時，才使用有序列表. Do: ``` These are the steps to do something: 1. First, do the first step. 1. Then, do the next step. 1. Finally, do the last step. ``` Don’t: ``` This is a list of available features: 1. Feature 1 1. Feature 2 1. Feature 3 ``` ### Markup[](#markup "Permalink") * 對于無序列表，請使用破折號（ `-` ）代替星號（ `*` ）. * 在有序列表中的每個項目之前添加前綴`1.` .. 呈現后，列表項將自動以順序編號顯示. ### Punctuation[](#punctuation-1 "Permalink") * 不要在列表項的末尾添加逗號（ `,` ）或分號（ `;` ）. * 如果項目由完整的句子組成，則僅在項目的末尾添加句號. [完整句子](https://www2.le.ac.uk/offices/ld/all-resources/writing/grammar/grammar-guides/sentence)的[定義](https://www2.le.ac.uk/offices/ld/all-resources/writing/grammar/grammar-guides/sentence)是： *"完整句子總是包含一個動詞，表達一個完整的構想，并且在單獨存在時有意義"* . * Be consistent throughout the list: if the majority of the items do not end in a period, do not end any of the items in a period, even if they consist of a complete sentence. The opposite is also valid: if the majority of the items end with a period, end all with a period. * 從解釋性文字分隔列表項用冒號（ `:` ）. 例如： ``` The list is as follows: - First item: this explains the first item. - Second item: this explains the second item. ``` **Examples:** Do: * 第一個清單項目 * 第二個清單項目 * 第三清單項目 Don’t: * 第一個清單項目 * 第二個清單項目 * 第三列表項. Do: * 假設這是一個完整的句子. * 假設這也是一個完整的句子. * 句子不完整. 請勿（各種句號的使用；多數規則）： * 假設這是一個完整的句子. * 假設這也是一個完整的句子. * 句子不完整 ### Nesting inside a list item[](#nesting-inside-a-list-item "Permalink") 可以將項目嵌套在列表項目下，以便它們呈現與列表項目相同的縮進. 這可以通過以下方式完成： * [Code blocks](#code-blocks) * [Blockquotes](#blockquotes) * [Alert boxes](#alert-boxes) * [Images](#images) 嵌套在列表中的項目應始終與列表項目的第一個字符對齊. 在無序列表（使用`-` ）中，這表示每個縮進級別有兩個空格： ``` - Unordered list item 1 A line nested using 2 spaces to align with the `U` above. - Unordered list item 2 > A quote block that will nest > inside list item 2. - Unordered list item 3 ```plaintext a codeblock that will next inside list item 3 ``` - Unordered list item 4 ![an image that will nest inside list item 4](image.png) ``` 對于有序列表，每個縮進級別使用三個空格： ``` 1. Ordered list item 1 A line nested using 3 spaces to align with the `O` above. 1. Ordered list item 2 > A quote block that will nest > inside list item 2. 1. Ordered list item 3 ```plaintext a codeblock that will next inside list item 3 ``` 1. Ordered list item 4 ![an image that will nest inside list item 4](image.png) ``` 您可以使用與上述相同的規則將完整列表嵌套在其他列表中. 如果您希望混合類型，也可以，只要您不混合同一級別的項目即可： ``` 1. Ordered list item one. 1. Ordered list item two. - Nested unordered list item one. - Nested unordered list item two. 1. Ordered list item three. - Unordered list item one. - Unordered list item two. 1. Nested ordered list item one. 1. Nested ordered list item two. - Unordered list item three. ``` ## Tables[](#tables "Permalink") 應該使用表格以簡單的方式描述復雜的信息. 請注意，在許多情況下，無序列表足以描述一個項目列表，而每個項目只有一個簡單的描述. 但是，如果您擁有最能用矩陣描述的數據，則表是使用的最佳選擇. ### Creation guidelines[](#creation-guidelines "Permalink") 由于可訪問性和可掃描性要求，表中不應包含任何空白單元格. 如果某個單元格沒有其他有意義的值，請考慮輸入*N / A* （"不適用"）或*不輸入* . 為了使表更易于維護，請考慮在列寬上添加額外的空格以使其一致. 例如： ``` | App name | Description | Requirements | |:---------|:---------------------|:---------------| | App 1 | Description text 1\. | Requirements 1 | | App 2 | Description text 2\. | None | ``` 考慮在編輯器中安裝插件或擴展程序以格式化表格： * 用于 Visual Studio 代碼的[Markdown 表修飾符](https://marketplace.visualstudio.com/items?itemName=darkriszty.markdown-table-prettify) * 升華文字的[Markdown 表格式化](https://packagecontrol.io/packages/Markdown Table Formatter)程序 * 用于 Atom 的[Markdown 表格式化](https://atom.io/packages/markdown-table-formatter)程序 ### Feature tables[](#feature-tables "Permalink") 創建功能列表時（例如，" [權限"](../../user/permissions.html#project-members-permissions)頁面上的某些角色是否可以使用功能），請使用以下短語（基于 SVG 圖標）： * *No*: No * *Yes*: Yes ## Quotes[](#quotes "Permalink") 僅適用于 Markdown 內容，不適用于優先事項條目： * 標準引號：雙引號（ `"` ）.例如："這用雙引號引起來". * 用引號引起來：雙引號（ `"` ）包裹單引號（ `'` ）.例如："我正在用引號引起來". 有關其他標點規則，請參考[GitLab UX 指南](https://design.gitlab.com/content/punctuation/) . ## Headings[](#headings "Permalink") * 通過在每個文檔的開頭添加`#` （在使用 Markdown 時）， **僅**在每個文檔中添加**一個 H1** . `h1`將是文檔`<title>` . * 從`h2` （ `##` ）開始，并遵循`h2` > `h3` > `h4` > `h5` > `h6`的順序. 切勿跳過層次結構級別，例如`h2` > `h4` * 避免將數字放在標題中. 數字移動，因此文檔錨鏈接也移動，最終導致死鏈接. 如果您認為在標題中添加數字非常有必要，請確保至少與"合并請求"中的某人進行討論. * [避免](https://gitlab.com/gitlab-org/gitlab-docs/-/issues/84)在標題中[使用符號和特殊字符](https://gitlab.com/gitlab-org/gitlab-docs/-/issues/84) . 只要有可能，它們應為純文本和簡短文本. * 避免添加顯示短暫狀態的內容. 例如，如果某個功能被認為是 Beta 或試驗性功能，請將此信息放在注釋中而不是標題中. * 引入新文檔時，請注意標題在語法和語法上都是正確的. 提及[指定的技術作家（TW）](https://about.gitlab.com/handbook/product/product-categories/)以進行審查. 這是為了確保沒有錯誤標題的文檔將在未經審核的情況下生效，從而防止在糾正時出現無效鏈接和重定向問題. * 在標題前后只留一個空白行. * 不要在標題中使用鏈接. * 根據功能所屬的級別添加相應的[產品徽章](#product-badges) . * 我們的 docs 網站搜索引擎會區分標題和副標題中使用的單詞的優先級. 如[標題標題](#heading-titles)部分所示，使標題標題清晰，描述性且完整，以幫助用戶找到正確的示例. * 有關將標題[大寫](#capitalization)的指南，請參見[大寫](#capitalization) . ### Heading titles[](#heading-titles "Permalink") 保持標題清晰，直接. 使每個單詞都重要. 為了適應搜索引擎優化（SEO），請盡可能使用命令. | Do | Don’t | | --- | --- | | Configure GDK | Configuring GDK | | GitLab 發布和維護政策 | 本節介紹 GitLab 的發布和維護政策 | | 向后移植到較舊的版本 | 向后移植到較舊的版本 | | GitLab 頁面示例 | Examples | 有關大寫標題的準則，請參見[大寫](#capitalization)部分. **注意：**如果更改現有標題，請當心. 任何此類更改可能不僅影響頁面內的[鏈接](#anchor-links) ，而且還可能影響來自 GitLab 本身的鏈接以及指向 GitLab 文檔的外部鏈接. ### Anchor links[](#anchor-links "Permalink") 渲染時，標題會自動生成錨鏈接. `## This is an example`生成錨點`#this-is-an-example` . 請記住，GitLab UI 鏈接到大量文檔以及相應的錨鏈接，以將用戶帶到正確的位置. 因此，當您更改標題時，請在`doc/*` ， `app/views/*`和`ee/app/views/*`搜索舊的錨點，以確保您不會破壞從其他文檔或 GitLab UI 鏈接的錨點. 如果找到舊的錨，請確保將其替換為新的錨. Important: * 除非需要鏈接到文檔的特定部分，否則請避免將文檔交到標題. 如果方向改變，這將避免將來破壞錨. * 如果可能，請避免更改標題，因為它們不僅是內部鏈接的. 互聯網上有指向 GitLab 文檔的各種鏈接，例如教程，演示文稿，StackOverflow 帖子和其他資源. * 不要鏈接到`h1`標題. 需要注意的是，與 Kramdown，也可以自定義 ID 添加到與降價的標記 HTML 元素，但他們**沒有**在 GitLab 的工作`/help` . 因此，除非另行通知，否則不要使用此選項. ## Links[](#links "Permalink") 鏈接在 GitLab 文檔中很重要. 它們使您可以[鏈接而不是進行匯總，](#link-instead-of-summarize)以幫助在 GitLab 文檔中保留[SSoT](#why-a-single-source-of-truth) . 我們提供以下類別的鏈接指南： * 如何設置標題的[錨鏈接](#anchor-links) . * 如何設置[標準](#basic-link-criteria)配置的鏈接. * [鏈接到`help`](../documentation/index.html#linking-to-help)頁面時要設置的內容. * 如何設置[指向內部文檔的鏈接以](#links-to-internal-documentation)進行交叉引用. * 如何建立[指向](#links-to-external-documentation)權威來源的[外部文檔的鏈接](#links-to-external-documentation) . * 何時使用[需要權限的鏈接](#links-requiring-permissions) . * 如何設置[視頻鏈接](#link-to-video) . * 如何在[版本文本中包含鏈接](#text-for-documentation-requiring-version-text) . * 如何[鏈接到特定的代碼行](#link-to-specific-lines-of-code) ### Basic link criteria[](#basic-link-criteria "Permalink") * 使用內聯鏈接 Markdown 標記`[Text](https://example.com)` . 它更易于閱讀，查看和維護. **不要**使用`[Text][identifier]` . * 使用[有意義的錨文本](https://www.futurehosting.com/blog/links-should-have-meaningful-anchor-text-heres-why/) . 例如， `Read more about GitLab Issue Boards [here](LINK)`編寫類似" `Read more about GitLab Issue Boards [here](LINK)` ，而不是撰寫`Read more about [GitLab Issue Boards](LINK)` . ### Links to internal documentation[](#links-to-internal-documentation "Permalink") **注意：** *內部*是指同一項目中的文檔. 鏈接到單獨項目中的文檔時（例如，從 GitLab 文檔鏈接到 Omnibus 文檔），必須使用絕對 URL. 請勿使用`https://docs.gitlab.com/ee/index.html`類的絕對 URL 交叉鏈接到同一項目中的其他文檔. 使用指向文件的相對鏈接，例如`../index.md` . （在呈現網站時將這些轉換為 HTML.）相對鏈接使交叉鏈接可以正常工作： * 在 Review Apps，本地預覽和`/help` . * 在本地處理文檔時，您可以在此過程中盡早驗證它們是否有效. * 瀏覽各自存儲庫中的文檔文件時，可以在 GitLab UI 中使用. 例如，顯示在`https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/README.md`的鏈接. 鏈接到內部文檔： * 使用相對鏈接指向同一存儲庫中的 Markdown 文件. * 不要使用絕對 URL 或`docs.gitlab.com` URL. * 使用`../`導航到更高級別的目錄. * 不要相對于根鏈接. 例如，/ `/ee/user/gitlab_com/index.md` . Don’t: * `https://docs.gitlab.com/ee/administration/geo/replication/troubleshooting.html` * `/ee/administration/geo/replication/troubleshooting.md` Do: `../../geo/replication/troubleshooting.md` * 始終在鏈接末尾添加文件名`file.md` ，擴展名為`.md`而不是`.html` . Don’t: * `../../merge_requests/` * `../../issues/tags.html` * `../../issues/tags.html#stages` Do: * `../../merge_requests/index.md` * `../../issues/tags.md` * `../../issues/tags.md#stages` **注意：** GitLab 的[`/help`](index.html#gitlab-help)部分必須使用 Markdown 擴展名. ### Links to external documentation[](#links-to-external-documentation "Permalink") 描述與外部軟件的交互時，包括指向外部文檔的鏈接通常會很有幫助. 如果可能，請確保您鏈接到**權威**來源. 例如，如果您要描述 Microsoft Active Directory 中的功能，請包括指向 Microsoft 官方文檔的鏈接. ### Links requiring permissions[](#links-requiring-permissions "Permalink") 不要直接鏈接到： * [Confidential issues](../../user/project/issues/confidential_issues.html). * 需要[特殊權限](../../user/permissions.html)才能查看的項目功能. 這些將因以下原因而失敗： * 那些沒有足夠權限的人. * 自動鏈接檢查器. Instead: * 為了減少混亂，請在文本中提及以下信息之一： * 包含在一個機密問題中. * 需要項目的特殊權限才能查看. * 在反勾號（ ``` ）中提供一個鏈接，以便那些有權訪問該問題的人可以輕松導航到該問題. Example: ``` For more information, see the [confidential issue](../../user/project/issues/confidential_issues.md) `https://gitlab.com/gitlab-org/gitlab-foss/-/issues/<issue_number>`. ``` ### Link to specific lines of code[](#link-to-specific-lines-of-code "Permalink") 鏈接到文件中的特定行時，請鏈接到提交而不是分支. 代碼行隨時間變化，因此，使用 commit 鏈接鏈接到一行可確保用戶落在您所指的行上. 在查看項目中的文件時，可以使用" **永久鏈接"**按鈕，它可以輕松生成指向給定文件的最新提交的鏈接. * **Do:** `[link to line 3](https://gitlab.com/gitlab-org/gitlab/-/blob/11f17c56d8b7f0b752562d78a4298a3a95b5ce66/.gitlab/issue_templates/Feature%20proposal.md#L3)` * **Don’t:** `[link to line 3](https://gitlab.com/gitlab-org/gitlab/-/blob/master/.gitlab/issue_templates/Feature%20proposal.md#L3).` 如果由于進一步的提交，該鏈接的表達式不再在文件的該行中，則您仍然可以在文件中搜索該查詢. 在這種情況下，請更新文檔以確保其鏈接到文件的最新版本. ## Navigation[](#navigation "Permalink") 指示通過 UI 導航的步驟： * 使用界面中顯示的確切字詞，包括所有大寫字母. * 使用粗體文本顯示導航項，并使用字符"大于"（ `>` ）作為分隔符（例如， `Navigate to your project's **Settings > CI/CD**` ）. * 如果有任何可展開的菜單，請確保提及用戶需要展開選項卡以找到您要引用的設置（例如， `Navigate to your project's **Settings > CI/CD** and expand **General pipelines**` ）. ## Images[](#images "Permalink") 圖像（包括屏幕截圖）可以幫助讀者更好地理解概念. 但是，它們可能難以維護，應謹慎使用. 在文檔中包括圖片之前，請確保它為讀者提供了價值. ### Capture the image[](#capture-the-image "Permalink") 使用圖像可以幫助讀者了解它們在過程中的位置，或與應用程序進行交互的方式. 截屏時： * *捕獲頁面中最相關的區域.* 不要包含不必要的空白或頁面區域，以免說明您的觀點. 另外，如果不需要，不要包括整個頁面，而且還要確保圖像包含足夠的信息以允許用戶確定事物的位置. * *始終如一.* 找到適合您的瀏覽器窗口大小，該窗口大小還會顯示產品的所有區域，包括左側導航欄（通常> 1200 像素寬）. 為了保持一致，請通過安裝用于將窗口設置為特定大小的瀏覽器擴展程序（例如，用于 Google Chrome 的[Window Resizer](https://chrome.google.com/webstore/detail/window-resizer/kkelicaakdanhinjdeammmilcgefonfh/related?hl=en) ），將此瀏覽器窗口大小用于屏幕截圖. ### Save the image[](#save-the-image "Permalink") * 用一個小寫的文件名保存該圖像，該文件名描述了圖像中的功能或概念. 如果該圖像屬于 GitLab 界面，則根據以下格式將 GitLab 版本附加到文件名： `image_name_vX_Y.png` . 例如，對于從 GitLab 11.1 的管道頁面中截取的屏幕截圖，有效名稱為`pipelines_v11_1.png` . 如果要添加的插圖不包含用戶界面的各個部分，請添加與添加圖像的版本相對應的版本號；對于添加到 11.1 里程碑中的 MR，插圖的有效名稱是`devops_diagram_v11_1.png` . * 將圖像放置在名為`img/`的單獨目錄中，該目錄與您正在使用的`.md`文檔所在的目錄相同. * 考慮使用 PNG 圖像而不是 JPEG. * [Compress all PNG images](#compress-images). * 使用[https://ezgif.com/optimize](https://ezgif.com/optimize)或類似工具壓縮 gif. * 應該使用圖像（僅在必要時使用）來*說明*過程說明，而不是*替代*過程. * 圖片大小上限：100KB（含 Gif）. * 另請參閱如何鏈接和嵌入[視頻](#videos)以說明文檔. ### Add the image link to content[](#add-the-image-link-to-content "Permalink") 用于在文檔中包含圖像的 Markdown 代碼為： `![Image description which will be the alt tag](img/document_image_title_vX_Y.png)` 圖像描述是 docs 網站上渲染圖像的替代文本. 對于可訪問性和 SEO，請使用以下[描述](https://webaim.org/techniques/alttext/) ： * 準確，簡潔且獨特. * 請勿使用*…的圖像*或*…的* *圖形*來描述圖像. 另外，如果標題緊隨圖像之后，請確保在圖像和標題之間添加三個破折號（ `---` ）. ### Remove image shadow[](#remove-image-shadow "Permalink") 默認情況下，在[GitLab 文檔站點](https://s0docs0gitlab0com.icopy.site)上顯示的所有圖像都有一個陰影框. 要刪除框陰影，請使用直接應用于 HTML `img`標簽的圖像類`.image-noshadow` ： ``` <img src="path/to/image.jpg" alt="Alt text (required)" class="image-noshadow"> ``` ### Compress images[](#compress-images "Permalink") 您應該始終壓縮添加到文檔中的任何新圖像. 一種已知的工具是[`pngquant`](https://pngquant.org/) ，它是跨平臺和開源的. 通過訪問官方網站并按照您的操作系統說明進行安裝. GitLab 有一個[Rake 任務](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/tasks/pngquant.rake) ，可用于自動執行該過程. 在本地`https://gitlab.com/gitlab-org/gitlab`副本的根目錄中，在終端中運行： * 壓縮之前，如果需要，請檢查是否已壓縮所有文檔 PNG 圖像： ``` bundle exec rake pngquant:lint ``` * 使用`pngquant`壓縮所有文檔 PNG 圖像： ``` bundle exec rake pngquant:compress ``` 唯一需要注意的是，該任務將在`doc/`下的所有圖像上運行，而不僅僅是您可能包含在合并請求中的圖像. 在這種情況下，您可以運行 compress 任務，僅提交與合并請求相關的圖像. ## Videos[](#videos "Permalink") 強烈建議將 GitLab 的現有 YouTube 視頻教程添加到文檔中，除非該視頻已過時. 視頻不應取代文檔，而應補充或說明文檔. 如果視頻中的內容是功能及其關鍵用例的基礎，但是文檔中沒有對此進行充分介紹，請將此詳細信息添加到文檔文本中，或者創建問題以查看視頻并這樣做. 不要將視頻上傳到產品存儲庫. [鏈接](#link-to-video)或[嵌入](#embed-videos)它們. ### Link to video[](#link-to-video "Permalink") 要鏈接到視頻，請添加 YouTube 圖標，以便讀者在閱讀之前可以快速輕松地掃描頁面上的視頻： ``` <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> For an overview, see [Video Title](link-to-video). ``` 您可以鏈接任何對 GitLab 用戶有用的最新視頻. ### Embed videos[](#embed-videos "Permalink") 在 GitLab 12.1 中[引入](https://gitlab.com/gitlab-org/gitlab-docs/-/merge_requests/472) . [GitLab Docs 網站](https://s0docs0gitlab0com.icopy.site)支持嵌入式視頻. 您只能嵌入來自[GitLab 的官方 YouTube 帳戶的視頻](https://www.youtube.com/channel/UCnMGQ8QHMAnVIsI3xJrihhg) . 對于其他來源的視頻，請[鏈接](#link-to-video)它們. 在大多數情況下，最好[鏈接到視頻](#link-to-video) ，因為嵌入會占用頁面上的大量空間，并且可能分散讀者的注意力. 要嵌入視頻，請按照以下說明進行操作，并確保您的 MR 已得到技術作家的審查和批準. 1. 復制下面的代碼，并將其粘貼到 Markdown 文件中. 在其上方和下方保留空白行. 請勿編輯代碼（請勿刪除或添加任何空格）. 2. 在 YouTube 上，訪問要顯示的視頻 URL. 從您的瀏覽器復制常規 URL（ `https://www.youtube.com/watch?v=VIDEO-ID` ），然后替換視頻標題和`<div class="video-fallback">`行中的鏈接. 3. 在 YouTube 上，點擊**共享** ，然后點擊**嵌入** . 4. 僅復制`<iframe>`源（ `src` ） **URL** （ `https://www.youtube.com/embed/VIDEO-ID` ），然后粘貼它，替換`iframe`標記中`src`字段的內容. ``` leave a blank line here <div class="video-fallback"> See the video: <a href="https://www.youtube.com/watch?v=MqL6BMOySIQ">Video title</a>. </div> <figure class="video-container"> <iframe src="https://www.youtube.com/embed/MqL6BMOySIQ" frameborder="0" allowfullscreen="true"> </iframe> </figure> leave a blank line here ``` 它是如何在 GitLab Docs 網站上呈現的：觀看視頻： [什么是 GitLab](https://www.youtube.com/watch?v=enMumwvLAug) . <figure class="video-container"><iframe src="https://www.youtube.com/embed/MqL6BMOySIQ" frameborder="0" allowfullscreen=""></iframe></figure> > Notes: > > * `figure`標記是語義 SEO 所必需的，而`video_container`類是必需的，以確保視頻能夠響應并在不同的移動設備上很好地顯示. > * `<div class="video-fallback">`是 GitLab 的`/help`必需的后備，因為 GitLab 的 Markdown 處理器不支持 iframe. 它隱藏在 docs 網站上，但將顯示在 GitLab 的`/help` . ## Code blocks[](#code-blocks "Permalink") * 始終將添加到句子的代碼包裝在內聯代碼塊（ ``` ）中. 例如`.gitlab-ci.yml` ， `git add .` ， `CODEOWNERS`或`only: [master]` . 文件名，命令，條目以及任何涉及代碼的內容都應添加到代碼塊中. 為了使用戶更輕松，請始終為可復制和粘貼的內容添加完整的代碼塊，因為他們可以使用代碼塊上的按鈕輕松進行操作. * 在代碼塊的上方和下方添加一個空行. * 提供 shell 命令及其輸出時，請在 shell 命令前加上`$`前綴，并在命令和輸出之間留空行. * 提供無輸出的命令時，請不要在 shell 命令前加上`$`前綴. * 如果需要在代碼塊中包括三個反引號，則對代碼塊圍欄使用四個反引號，而不是三個. * 對于常規的受保護代碼塊，請始終使用與該語言對應的突出顯示類，以提高可讀性. 例子： ``` ```ruby Ruby code ``` ```javascript JavaScript code ``` ```markdown [Markdown code example](example.md) ``` ```plaintext Code or text for which no specific highlighting class is available. ``` ``` 加到 GitLab 文檔中的受防護代碼塊要求突出顯示語法. 有關最常用的語言類別，請參考下表，或查看可用語言類別的[完整列表](https://github.com/rouge-ruby/rouge/wiki/List-of-supported-languages-and-lexers) . | 首選語言標簽 | 語言別名和注釋 | | --- | --- | | `asciidoc` | ? | | `dockerfile` | Alias: `docker`. | | `elixir` | ? | | `erb` | ? | | `golang` | Alias: `go`. | | `graphql` | ? | | `haml` | ? | | `html` | ? | | `ini` | 對于一些非 TOML 格式的簡單配置文件. | | `javascript` | Alias `js`. | | `json` | ? | | `markdown` | Alias: `md`. | | `mermaid` | ? | | `nginx` | ? | | `perl` | ? | | `php` | ? | | `plaintext` | 沒有定義語言的示例，例如 shell 命令或 API 調用的輸出. 如果代碼塊沒有語言，則默認為`plaintext` . 別名： `text` . | | `prometheus` | Prometheus 配置示例. | | `python` | ? | | `ruby` | Alias: `rb`. | | `shell` | Aliases: `bash` or `sh`. | | `sql` | ? | | `toml` | Runner 配置示例以及其他 TOML 格式的配置文件. | | `typescript` | Alias: `ts`. | | `xml` | ? | | `yaml` | Alias: `yml`. | 有關代碼塊的完整參考，請參閱《 [Kramdown 指南》](https://about.gitlab.com/handbook/markdown-guide/#code-blocks) . ## GitLab SVG icons[](#gitlab-svg-icons "Permalink") 在 GitLab 12.7 中[引入](https://gitlab.com/gitlab-org/gitlab-docs/-/issues/384) . 您可以直接在文檔中使用來自[GitLab SVG 庫的](https://gitlab-org.gitlab.io/gitlab-svgs/)圖標. This way, you can achieve a consistent look when writing about interacting with GitLab UI elements. 用法示例： * 默認尺寸（16 像素）的`**{icon-name}**` ： `**{icon-name}**` 示例： `**{tanuki}**`呈現為： . * 具有自定義尺寸的`**{icon-name, size}**` ： `**{icon-name, size}**` 可用尺寸（以像素為單位）：8、10、12、14、16、18、24、32、48 和 72 示例： `**{tanuki, 24}**`呈現為： . * 具有自定義尺寸和類別的`**{icon-name, size, class-name}**` ： `**{icon-name, size, class-name}**` . 您可以在 GitLab 文檔 CSS 中訪問此元素可用的任何類. 帶有`float-right`示例， [Bootstrap 實用程序類](https://s0getbootstrap0com.icopy.site/docs/4.4/utilities/float/) ： `**{tanuki, 32, float-right}**`呈現為： ### Use GitLab SVGs to describe UI elements[](#use-gitlab-svgs-to-describe-ui-elements "Permalink") 使用 GitLab SVG 描述屏幕元素時，還應包括該元素的名稱或工具提示作為文本. 例如，對于"管理區"的引用： * Correct: `**{admin}** **Admin Area > Settings**` ( **管理區域>設置**) * Incorrect: `**{admin}** **> Settings**` ( **>設定**) 這將確保源 Markdown 保持可讀性，并應有助于輔助功能. 以下是菜單項的源 Markdown 示例及其發布的輸出： ``` 1. Go to **{home}** **Project overview > Details** 1. Go to **{doc-text}** **Repository > Branches** 1. Go to **{issues}** **Issues > List** 1. Go to **{merge-request}** **Merge Requests** 1. Go to **{rocket}** **CI/CD > Pipelines** 1. Go to **{shield}** **Security & Compliance > Configuration** 1. Go to **{cloud-gear}** **Operations > Metrics** 1. Go to **{package}** **Packages > Container Registry** 1. Go to **{chart}** **Project Analytics > Code Review** 1. Go to **{book}** **Wiki** 1. Go to **{snippet}** **Snippets** 1. Go to **{users}** **Members** 1. Select the **More actions** **{ellipsis_v}** icon > **Hide stage** ``` 1. 去 **項目概述>詳細信息** 2. Go to **資料庫>分支機構** 3. 去 **問題>清單** 4. 去 **合并請求** 5. 去 **CI / CD>管道** 6. 去 **安全與合規>配置** 7. 去 **操作>指標** 8. 去 **包>容器注冊表** 9. 去 **項目分析>代碼審查** 10. 去 **維基** 11. 去 **片段** 12. 去 **會員** 13. 選擇**更多操作** 圖標> **隱藏舞臺** ## Alert boxes[](#alert-boxes "Permalink") 每當您需要特別注意特定句子時，請使用以下標記突出顯示. 請注意，警報框僅適用于一個段落. 多個段落，列表，標題等將無法正確呈現. 對于多行，請改用[blockquotes](#blockquotes) . 警報框僅在 GitLab Docs 網站（ [https://docs.gitlab.com](https://s0docs0gitlab0com.icopy.site) ）上呈現. 在 GitLab 本身中，它們將顯示為純 Markdown 文本（如下面呈現的版本上方的示例）. ### Note[](#note "Permalink") 注釋引起了大多數讀者的注意，因此應謹慎使用. 在大多數情況下，應考慮為便箋考慮的內容： * 僅作為上一段或最相關段落中的另一句話. * 作為其自己的獨立段落. * 作為介紹該主題的新子標題下的內容，使它更明顯/更容易找到. #### When to use[](#when-to-use "Permalink") 當出于某種原因，大多數或所有瀏覽本節的讀者都應看到內容時，請使用注釋. 就是說，如果錯過了它，可能會給少數用戶造成重大麻煩，或者對大多數用戶造成重大麻煩. 權衡分散內容無關用戶的成本與丟失內容（如果未表示為注釋）的用戶成本. ``` NOTE: **Note:** This is something to note. ``` 它如何在 GitLab Docs 網站上呈現： **注意：**這是要注意的事情. ### Tip[](#tip "Permalink") ``` TIP: **Tip:** This is a tip. ``` 它如何在 GitLab Docs 網站上呈現： **提示：**這是一個提示. ### Caution[](#caution "Permalink") ``` CAUTION: **Caution:** This is something to be cautious about. ``` 它如何在 GitLab Docs 網站上呈現： **注意：**這是要謹慎的事情. ### Danger[](#danger "Permalink") ``` DANGER: **Danger:** This is a breaking change, a bug, or something very important to note. ``` 它如何在 GitLab Docs 網站上呈現： **危險：**這是一個重大更改，錯誤或要注意的重要事項. ## Blockquotes[](#blockquotes "Permalink") 要突出顯示藍色方框引號內的文本，請使用以下格式： ``` > This is a blockquote. ``` 在[GitLab 文檔網站上顯示](https://s0docs0gitlab0com.icopy.site)為： > 這是一個大引用. 如果文本跨多行，則可以拆分行. 對于多個段落，請在每行之前使用符號`>` ： ``` > This is the first paragraph. > > This is the second paragraph. > > - This is a list item > - Second item in the list ``` 導致： > 這是第一段. > > 這是第二段. > > * 這是一個清單項目 > * 列表中的第二項 ## Terms[](#terms "Permalink") 為了通過 GitLab 文檔保持一致性，以下內容將指導文檔作者了解一致的樣式和術語的用法. ### Merge Requests (MRs)[](#merge-requests-mrs "Permalink") 合并請求使您可以交換對源代碼所做的更改，并與同一項目中的其他人進行協作. 您將看到此術語以下列方式使用： * 如果您要使用此功能，請使用**合并請求** . * 在任何其他上下文中，請使用**merge request** . 如我們公司的《 [寫作風格指南》所述](https://about.gitlab.com/handbook/communication/#writing-style-guidelines) ，如果您使用**MR**首字母縮寫詞，請在每個文檔頁面上至少展開一次. 例如，第一次指定 MR 時，請指定*Merge Request（MR）*或*merge request（MR）* . Examples: * "我們更喜歡 GitLab 合并請求". * "打開合并請求以修復斷開的鏈接". * "打開合并請求（MR）后，將您的 MR 提交以供審核和批準". ### Describe UI elements[](#describe-ui-elements "Permalink") 以下是在屏幕上描述 UI 元素時要遵循的樣式： * 對于帶有可見標簽的元素，請使用帶有匹配大小寫的粗體標簽. 例如， `the **Cancel** button` . * 對于帶有工具提示或懸停標簽的元素，請使用帶有匹配大小寫的粗體標簽. 例如， `the **Add status emoji** button` . ### Verbs for UI elements[](#verbs-for-ui-elements "Permalink") 以下是建議用于 UI 元素的特定動詞： | Recommended | 用于 | Replaces | | --- | --- | --- | | *click* | 按鈕，鏈接，菜單項 | "點擊"，"按"，"選擇" | | *select* or *clear* | checkboxes | "啟用"，"單擊"，"按" | | *select* | dropdowns | “pick” | | *expand* | expandable sections | “open” | ### Other Verbs[](#other-verbs "Permalink") | Recommended | 用于 | Replaces | | --- | --- | --- | | *去* | 使瀏覽器定位 | "導航至"，"打開" | ## GitLab versions and tiers[](#gitlab-versions-and-tiers "Permalink") 標記和發布版本的 GitLab 文檔可用： * 在[文檔檔案中](https://docs.gitlab.com/archives/) . * 在任何 GitLab 安裝的`/help` URL 中. 引入新功能的版本已添加到文檔主題的頂部，以提供有關該功能開發方式的有用鏈接. ### Text for documentation requiring version text[](#text-for-documentation-requiring-version-text "Permalink") * For features that need to declare the GitLab version that the feature was introduced. Text similar to the following should be added immediately below the heading as a blockquote: * `> Introduced in GitLab 11.3.`. * 只要有可能，版本文本都應具有指向已*完成的*發行，合并請求或引入了該功能的史詩的鏈接. 問題優先于合并請求，而合并請求優先于史詩. 例如： * `> [Introduced](<link-to-issue>) in GitLab 11.3.` . * 如果該功能僅在 GitLab 企業版中可用，請提及該功能在以下位置的[付費層](https://about.gitlab.com/handbook/marketing/product-marketing/#tiers) ： * `> [Introduced](<link-to-issue>) in [GitLab Starter](https://about.gitlab.com/pricing/) 11.3.` . * 如果隨著功能的發展列出了多個版本的信息，請將該信息添加到帶引號的項目符號列表中. 例如： ``` > - [Introduced](<link-to-issue>) in GitLab 11.3. > - Enabled by default in GitLab 11.4. ``` * 如果功能已移至另一層： ``` > - [Introduced](<link-to-issue>) in [GitLab Premium](https://about.gitlab.com/pricing/) 11.5. > - [Moved](<link-to-issue>) to [GitLab Starter](https://about.gitlab.com/pricing/) in 11.8. > - [Moved](<link-to-issue>) to GitLab Core in 12.0. ``` * 如果不推薦使用某個功能，請提供替換鏈接（如果有）： ``` > - [Deprecated](<link-to-issue>) in GitLab 11.3\. Replaced by [meaningful text](<link-to-appropriate-documentation>). ``` 如果可以的話，也可以在周圍的文字中描述替換內容. 如果現有文本中的棄用不明顯，則可能需要添加警告，例如： ``` CAUTION: **Warning:** This feature was [deprecated](link-to-issue) in GitLab 12.3 and replaced by [Feature name](link-to-feature-documentation). ``` **注意：**版本文本必須在其單獨的行上并由空白行包圍才能正確呈現. ### Versions in the past or future[](#versions-in-the-past-or-future "Permalink") 描述過去或將來版本中可用的功能時，請使用： * **較早的** ，不**早** **于之前的** . * **后來** ，并沒有**新的**或**之后** . 例如： * 在 GitLab 12.3 和更早版本中可用. * 在 GitLab 12.4 和更高版本中可用. * 如果使用 GitLab 11.4 或更早版本，… * 如果使用 GitLab 10.6 或更高版本，… ### Importance of referencing GitLab versions and tiers[](#importance-of-referencing-gitlab-versions-and-tiers "Permalink") 提及 GitLab 版本和層對所有用戶和貢獻者來說很重要，以便他們能夠快速訪問引入變更的發行或合并請求以供參考. 此外，鑒于該注釋包含一些關鍵信息，他們可以輕松了解其 GitLab 實例和版本中具有哪些功能. `[Introduced](link-to-issue) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.7`鏈接到引入該功能的問題，說它屬于哪個 GitLab 層，GitLab 說該版本可用的版本，并鏈接到定價頁面，以防用戶想要升級到付費層以使用該功能. 例如，如果您是普通用戶，并且正在查看以前從未使用過的功能的文檔，則可以立即查看該功能是否可用. 另外，如果您長期使用某項功能并且以某種方式進行了更改，那么重要的是要能夠發現更改的時間以及該功能的新增功能. 這一點更為重要，因為我們沒有一個完美的文檔發布流程. 不幸的是，我們仍然看到沒有文檔的功能和沒有功能的文檔. 因此，就目前而言，我們不能 100％依賴 docs 網站版本. 隨著時間的推移，版本文本將引用 GitLab 的逐漸老版本. 如果版本文本引用了 GitLab 的四個或更多個主要版本，您可以考慮刪除不相關或令人困惑的文本. 例如，如果當前的主要版本是 12.x，則在需要更清晰或更干凈的文檔時，需要引用引用 GitLab 8.x 和更早版本的版本文本. ## Products and features[](#products-and-features "Permalink") 在 GitLab 產品文檔中描述產品和功能時，請參考本節中的信息. ### Avoid line breaks in names[](#avoid-line-breaks-in-names "Permalink") 輸入包含空格（例如 GitLab 社區版）或什至其他公司產品（例如 Amazon Web Services）的產品或功能名稱時，請確保不要在插入了換行符的行之間拆分產品或功能名稱. 跨行拆分產品或功能名稱會使搜索這些項目更加困難，并且如果名稱更改則可能導致問題. 例如，以下 Markdown 內容的格式*不*正確： ``` When entering a product or feature name that includes a space (such as GitLab Community Edition), don't split the product or feature name across lines. ``` 而是，它應類似于以下內容： ``` When entering a product or feature name that includes a space (such as GitLab Community Edition), don't split the product or feature name across lines. ``` ### Product badges[](#product-badges "Permalink") 當僅 EE 層中有功能可用時，請根據功能可用性添加相應的層： * 對于 GitLab Core 和 GitLab.com 免費： `**(CORE)**` . * 對于 GitLab Starter 和 GitLab.com 銅牌： `**(STARTER)**` . * 對于 GitLab Premium 和 GitLab.com 銀牌： `**(PREMIUM)**` . * 對于 GitLab Ultimate 和 GitLab.com Gold： `**(ULTIMATE)**` . 要排除 GitLab.com 層（當該功能在 GitLab.com 中不可用時），請添加關鍵字" only"： * 對于 GitLab Core： `**(CORE ONLY)**` . * 對于 GitLab Starter： `**(STARTER ONLY)**`適用于`**(STARTER ONLY)**` . * 對于 GitLab Premium： `**(PREMIUM ONLY)**` . * 對于 GitLab Ultimate： `**(ULTIMATE ONLY)**` . 對于 GitLab.com 僅適用于層（當該功能不適用于自我管理實例時）： * 對于 GitLab 免費和更高級別： `**(FREE ONLY)**` . * 對于 GitLab 青銅級和更高級別： `**(BRONZE ONLY)**`銅級`**(BRONZE ONLY)**` . * 對于 GitLab Silver 和更高級別： `**(SILVER ONLY)**` . * 對于 GitLab Gold： `**(GOLD ONLY)**` . 理想情況下，應將該層添加到標題中，以便顯示完整的徽標. 但是，也可以從段落，列表項和表格單元格中提及. 對于這些情況，層級提及將由橙色的信息圖標**（信息）**表示，該圖標將顯示懸停時的層級. 即使頁面上存在較高級別的層，也應使用頁面級別的最低層. 例如，您可能有一個頁面標記為 Starter，而一個部分標記為 Premium. 例如： * `**(STARTER)**`呈現為 * `**(STARTER ONLY)**`呈現為 * `**(SILVER ONLY)**`呈現為沒有提及層意味著該功能可在 GitLab Core，GitLab.com Free 和所有更高層使用. #### How it works[](#how-it-works "Permalink") 由[！244](https://gitlab.com/gitlab-org/gitlab-docs/-/merge_requests/244)引入的特殊標記`**(STARTER)**`將生成一個`span`元素，以觸發徽章和工具提示（ `<span class="badge-trigger starter">` ）. 添加關鍵字" only"時，將不會顯示相應的 GitLab.com 徽章. ## Specific sections[](#specific-sections "Permalink") 某些樣式應應用于特定部分. 下面概述了特定部分的樣式. ### GitLab restart[](#gitlab-restart "Permalink") 在許多情況下，需要重新啟動/重新配置 GitLab. 為避免重復，請鏈接到可以在[`doc/administration/restart_gitlab.md`](../../administration/restart_gitlab.html)找到的特殊文檔. 通常，文本顯示如下： ``` Save the file and [reconfigure GitLab](../../administration/restart_gitlab.md) for the changes to take effect. ``` 如果您正在編輯的文檔位于 GitLab CE / EE `doc/`目錄之外的其他位置，請使用完整路徑，而不是相對鏈接： `https://docs.gitlab.com/ce/administration/restart_gitlab.html` : `https://docs.gitlab.com/ce/administration/restart_gitlab.html` . 在適當的地方，將`reconfigure`替換為`reconfigure` `restart` . ### Installation guide[](#installation-guide "Permalink") **Ruby：**在[安裝指南的第 2 步中](../../install/installation.html#2-ruby) ，我們從源代碼安裝 Ruby. 每當有新版本需要更新時，請記住在整個代碼塊中進行更改，并替換 sha256sum（可在 Ruby 網站的[下載頁面](https://www.ruby-lang.org/en/downloads/)中找到）. ### Configuration documentation for source and Omnibus installations[](#configuration-documentation-for-source-and-omnibus-installations "Permalink") GitLab currently officially supports two installation methods: installations from source and Omnibus packages installations. 只要有兩種安裝方法都可以配置的設置，就最好在 CE 文檔中進行記錄以避免重復. 配置設置包括： 1. 觸及`config/`配置文件的設置. 2. NGINX 設置和`lib/support/`中的設置通常. 如果有要執行的步驟列表，通常需要編輯配置文件并重新配置/重新啟動 GitLab. 在這種情況下，請按照以下樣式作為指導： ``` **For Omnibus installations** 1. Edit `/etc/gitlab/gitlab.rb`: ```ruby external_url "https://gitlab.example.com" ``` 1. Save the file and [reconfigure](path/to/administration/restart_gitlab.md#omnibus-gitlab-reconfigure) GitLab for the changes to take effect. --- **For installations from source** 1. Edit `config/gitlab.yml`: ```yaml gitlab: host: "gitlab.example.com" ``` 1. Save the file and [restart](path/to/administration/restart_gitlab.md#installations-from-source) GitLab for the changes to take effect. ``` 在這種情況下： * 在每個步驟列表之前，安裝方法以粗體聲明. * 三個破折號（ `---` ）用于創建水平線并將兩種方法分開. * 代碼塊在列表項下縮進一個或多個空格以正確呈現. * 代碼塊中的每個配置使用不同的突出顯示語言. * [GitLab 重新啟動](#gitlab-restart)部分用于說明 GitLab 所需的重新啟動/重新配置. ### Troubleshooting[](#troubleshooting "Permalink") 對于疑難解答部分，您應該提供盡可能多的上下文，以便用戶可以識別自己面臨的問題并自行解決. 您可以通過確保故障排除內容解決以下問題來簡化此操作： 1. 用戶需要解決的問題. 2. 用戶如何確認他們有問題. 3. 用戶可以采取的解決問題的步驟. 如果可以將所有類別的內容匯總在一行中，并且不需要步驟列表，請考慮設置一個帶有" *問題* |標題"的[表](#tables) . *原因* *解決方案* （或*解決方法（*如果此修復程序是臨時的））或*錯誤消息* | *解決方法* . ## Feature flags[](#feature-flags "Permalink") 了解如何[記錄標記后部署的功能](feature_flags.html) . 有關使用功能標記開發 GitLab 的指導，請參閱[GitLab 開發中的功能標記](../feature_flags/index.html) . ## API[](#api "Permalink") 這是必備物品清單. 按照本文檔中出現的確切順序使用它們. 下面給出進一步的解釋. * Every method must have the REST API request. For example: ``` GET /projects/:id/repository/branches ``` * 每個方法都必須[對參數](#method-description)進行詳細[說明](#method-description) . * 每個方法都必須有一個 cURL 示例. * 每個方法都必須具有響應主體（JSON 格式）. ### API topic template[](#api-topic-template "Permalink") 以下內容可以用作入門模板： ``` ## Descriptive title One or two sentence description of what endpoint does. ```plaintext METHOD /endpoint ``` | Attribute | Type | Required | Description | |:------------|:---------|:---------|:----------------------| | `attribute` | datatype | yes/no | Detailed description. | | `attribute` | datatype | yes/no | Detailed description. | Example request: ```shell curl --header "PRIVATE-TOKEN: <your_access_token>" 'https://gitlab.example.com/api/v4/endpoint?parameters' ``` Example response: ```json [ { } ] ``` ``` ### Fake user information[](#fake-user-information "Permalink") 您可能需要演示包含用戶名和電子郵件地址的 API 調用或 cURL 命令. 不要在 API 調用中使用真實的用戶信息： * **電子郵件地址** ：使用以`example.com`結尾的電子郵件地址. * **名稱** ：使用`Example Username` **名之類的**字符串. 或者，使用具有常用姓氏的各種或非性別名稱，例如`Sidney Jones` ， `Zhang Wei` . 或`Maria Garcia` . ### Fake URLs[](#fake-urls "Permalink") 在文檔中包含示例 URL 時，請使用： * 域名通用時為`example.com` . * `gitlab.example.com`指 GitLab 的自我管理的實例時. ### Fake tokens[](#fake-tokens "Permalink") 有時可能需要令牌來證明使用 cURL 或 CI 中使用的變量進行 API 調用. 強烈建議不要在文檔中使用真實令牌，即使令牌被利用的可能性很低. 您可以使用以下偽造的令牌作為示例. | 代幣類型 | 代幣價值 | | --- | --- | | 私人用戶令牌 | `<your_access_token>` | | 個人訪問令牌 | `n671WNGecHugsdEDPsyo` | | 申請編號 | `2fcb195768c39e9a94cec2c2e32c59c0aad7a3365c10892e8116b5d83d4096b6` | | 應用機密 | `04f294d1eaca42b8692017b426d53bbc8fe75f827734f0260710b83a556082df` | | 可變 CI / CD | `Li8j-mLUVA3eZYjPfd_H` | | 特定跑步者令牌 | `yrnZW46BrtBFqM7xDzE7dddd` | | 共享亞軍令牌 | `6Vk7ZsosqQyfreAxXTZr` | | 觸發令牌 | `be20d8dcc028677c931e04f3871a9b` | | Webhook 秘密令牌 | `6XhDroRcYPM5by_h-HLY` | | 健康檢查令牌 | `Tu7BgjR9qeZTEyRzGG2P` | | 請求個人資料令牌 | `7VgpS4Ax5utVD2esNstz` | ### Method description[](#method-description "Permalink") 使用下表標題來描述方法. 屬性應始終位于使用反引號（ ``` ）的代碼塊中. ``` | Attribute | Type | Required | Description | |:----------|:-----|:---------|:------------| ``` 渲染示例： | Attribute | Type | Required | Description | | --- | --- | --- | --- | | `user` | string | yes | GitLab 用戶名 | ### cURL commands[](#curl-commands "Permalink") * 使用`https://gitlab.example.com/api/v4/`作為端點. * 在需要的地方使用此個人訪問令牌： `<your_access_token>` . * 始終將請求放在第一位. `GET`是默認設置，因此您不必包含它. * 將該網址用雙引號（ `"` ）引起來. * 最好使用使用個人訪問令牌的示例，并且不要傳遞用戶名和密碼的數據. | Methods | Description | | --- | --- | | `--header "PRIVATE-TOKEN: <your_access_token>"` | 每當需要身份驗證時，請按原樣使用此方法 | | `--request POST` | 創建新對象時使用此方法 | | `--request PUT` | 更新現有對象時使用此方法 | | `--request DELETE` | 刪除現有對象時使用此方法 | ### cURL Examples[](#curl-examples "Permalink") 以下是一組可以在 API 文檔中使用的[cURL](https://curl.haxx.se)示例. #### Simple cURL command[](#simple-curl-command "Permalink") 獲取組的詳細信息： ``` curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/groups/gitlab-org ``` #### cURL example with parameters passed in the URL[](#curl-example-with-parameters-passed-in-the-url "Permalink") 在經過身份驗證的用戶的名稱空間下創建一個新項目： ``` curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects?name=foo" ``` #### Post data using cURL’s `--data`[](#post-data-using-curls---data "Permalink") 您可以使用 cURL 的`--data`選項，而不是使用`--request POST`并將參數附加到 URI. 下面的示例將在經過身份驗證的用戶的名稱空間下創建一個新項目`foo` . ``` curl --data "name=foo" --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects" ``` #### Post data using JSON content[](#post-data-using-json-content "Permalink") > **注意：**在此示例中，我們創建一個新組. 仔細觀察單引號和雙引號. ``` curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" --header "Content-Type: application/json" --data '{"path": "my-group", "name": "My group"}' https://gitlab.example.com/api/v4/groups ``` #### Post data using form-data[](#post-data-using-form-data "Permalink") 除了使用 JSON 或 urlencode 外，您還可以使用 multipart / form-data 來正確處理數據編碼： ``` curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" --form "title=ssh-key" --form "key=ssh-rsa AAAAB3NzaC1yc2EA..." https://gitlab.example.com/api/v4/users/25/keys ``` 上面的示例由管理員運行，并將向用戶帳戶添加名為`ssh-key`的 SSH 公共密鑰，其 ID 為 25. #### Escape special characters[](#escape-special-characters "Permalink") 空格或斜杠（ `/` ）有時可能會導致錯誤，因此建議在可能的情況下轉義它們. 在下面的示例中，我們創建了一個新問題，該問題的標題中包含空格. 觀察如何使用 ASCII 代碼對空格進行轉義. ``` curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/42/issues?title=Hello%20Dude" ``` 將`/`用作斜杠（ `/` ）. #### Pass arrays to API calls[](#pass-arrays-to-api-calls "Permalink") GitLab API 有時會接受字符串或整數數組. 例如，要在請求項目用戶列表時排除特定用戶，您可以執行以下操作： ``` curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" --data "skip_users[]=<user_id>" --data "skip_users[]=<user_id>" https://gitlab.example.com/api/v4/projects/<project_id>/users ```