Skip to content

Latest commit

 

History

History
226 lines (146 loc) · 21.6 KB

gitlab-wiki.md

File metadata and controls

226 lines (146 loc) · 21.6 KB
title
GitLab / Wiki

GitLab / Wiki

Markdown ??

  • Transitioning to CommonMark - Markdown | GitLab #ril
    • GitLab uses “GitLab Flavored Markdown” (GFM). It extends the CommonMark specification (which is based on standard Markdown) in a few significant ways to ADD some useful functionality. It was inspired by GitHub Flavored Markdown. 注意 GFM (GitLab) 與 GFM (GitHub) 不一樣，GitLab GFM 是基於 CommonMark，而 CommonMark 又基於標準的 Markdown，所以是相對嚴格的，沒有 GitHub GFM 那些彈性，但加了一些 GitLab 自己的東西。
    • For the best result, we encourage you to check this document out as rendered by GitLab itself: markdown.md 比較保險的寫法都在裡面 #ril
    • GitLab uses (as of 11.1) the CommonMark Ruby Library for Markdown processing of all new issues, merge requests, comments, and other Markdown content in the GitLab system. As of 11.3, wiki pages and Markdown files (.md) in the repositories are also processed with CommonMark. Older content in issues/comments are still processed using the Redcarpet Ruby library. 看來都往 CommonMark 靠攏了。
    • Since CommonMark uses a slightly stricter syntax, these documents may now display a little strangely since we’ve transitioned to CommonMark. Numbered lists with NESTED LISTS in particular can be displayed incorrectly. 如果暫時要看舊寫法的文件，URL 後面加 ?legacy_render=1 參數即可。如果有許多檔案要調整的話，可以用 diff_redcarpet_cmark 找出需要修改的檔案。

頁面如何命名?

  • 正確的說法是 page slug，而非 page name。
  • 建議全部小寫，單字間用 - 分隔，例如 quick-start 而非 quick_start 或 QuickStart。

參考資料：

  • 在 web editor 新增頁面時，出現 Page slug 的提示 - how-to-setup。
  • 用 how-to-setup 與 how_to_setup 的結果不同，前者在 TOC 裡會表現為 How to setup，但後者則會表現為 How_to_setup，顯然在 GitLab 內部 - 與單字間的空白是有對應關係的。

指向 header 的連結 ??

  • Header ID 從 header 的內容自動產生，無法自訂，但中文產生的 URL 有點醜。
  • 若手動宣告 <a id="custom-id" />，雖然可行，但使用者無法在閱讀文件時直接拿到，反而造成混淆?

參考資料：

TOC (Table Of Contents)

在需要有 TOC 的地方放 [[_TOC_]] 即可。

參考資料：

Math

官方只說用 LaTeX 寫，要怎麼寫 LaTeX 要另外學。

參考資料：

  • Math - GitLab Markdown | GitLab

    • It is possible to have math written with the LaTeX syntax rendered using KaTeX. Math written inside $``$ will be rendered inline with the text.

      This math is inline $`a^2+b^2=c^2`$.

    • Math written inside triple back quotes, with the language declared as math, will be rendered on a separate line.

      This is on a separate line
```math
a^2+b^2=c^2
```

    • Be advised that KaTeX only supports a subset of LaTeX. 如果只拿來寫數學運算式，應該沒什麼問題吧?

如何要求提供有意義的 Commit Message?

  • 預設的 commit message 是 "Update "，填空白也可以 (GitLab CE 10.4.0 上觀察到)，這會讓 page history 變得沒有意義。
  • 有些人建議 commit message 應該預設要留白且設為必填，否則很常忘記改讓 page history 沒有太大的用處，但不知為何 GitLab 開發團隊就是不予採納。目前只好用工具檢查 commit message 為 "Update " 時，跟使用者提示為什麼這樣做不好。

參考資料：

圖片存放的位置 ??

  • 把圖片拖拉進 editor 就會上傳並填上 ![{filename}](/uploads/{hash}/{filename})，很方便但會導致在 local 無法預覽圖片；它不在 wiki repo 裡，在 Settings > Export project 裡有提到 "Project uploads"。
  • 若把圖放在 project repo 呢? 有 web UI 可以上傳檔案、取得 URL，只是在 wiki repo 裡引用時要寫完整的 URL，例如 ![Text](http://gitlab.example.com/group/project/.../image.png) (之後換位置可以大量取代，問題不大)；雖然離線時會看不到圖，但有網路時只要能預覽的 editor 都沒問題，就像把圖放在 imgur 一樣，好處是能造訪 project repo 與 wiki repo 的人有一樣的限制。
  • 使用 web editor 編輯時，把本地端的檔案直接拖拉進編輯區就會自動上傳並插入圖片 (或是直接把系統剪貼簿的圖片直接貼上)，雖然檔案不會出現在 wiki repo 裡，但這會大大降低進入的門檻，提高大家用 wiki 撰寫文件的意願，對於非技術人員也比較友善。
  • 把圖放 wiki repo 也是一個方式，不過這對非技術人員的門檻太高。

參考資料：

如何建立文件階層?

  • GitLab 確實支持文件階層結構，但為了方便 page 之間相互引用，建議不要有階層，把全部的 page 都放在同一層。
  • 另一個考量是，將來 page 重新命名，可以大量取代 [Text](page-old) 為 [Text](page-new)，不用考量相對位置的變動。
  • 這會衍生出一個問題，該如何解決命名衝突? 可以從 prefix- 或 -suffix 兩方面來著手，例如 versioning、jenkins、jenkins-setup。
  • 這中間涉及文件的演進，可能一開始 Jenkins 的 setup 寫在 jenkins#setup (其中一節)，但之後可能拉出來成為獨立的 page，這時候只要大量將 jenkins#setup 取代為 jenkins-setup 即可。

參考資料：

如何比對不同版本的差異?

參考資料：

如何將 Wiki 的異動通知到 Slack?

  • 最根本的問題是 Wiki Page event 裡不帶 commit，只好求助 custom hook 或是定期 pull 並找出新的 commit。
  • Custom hook 在 CE 裡只能透過 admin 把 hook file 擺到適當的位置，若 project 數量多的話，要一直請 admin 幫忙也很麻煩，所以後者 "定期 pull 並找出新的 commit" 似乎比較可行。

參考資料：

  • 方向上是整合 Wiki Event 與 Slack 沒錯，但目前往 Slack 的訊息是整份 wiki 文件內容，看不出改了什麼?
  • 若能在 Slack 訊息裡提供 diff，或者附上 Gitweb 連結，方便查看任意兩個版本間的差異... 因為目前 GitLab Wiki 還不提供這項功能。前者 diff 可能相對單純，但後者若需要做權限控制就會比較麻煩，而且也涉及要同步兩個 repo。
  • Custom Git Hooks - GitLab Documentation https://docs.gitlab.com/ee/administration/custom_hooks.html Hook 設定在 filesystem，要 GitLab server 管理者才能做，也只有 GitLab Enterprise Edition 才有 UI 供一般使用者設定 #ril
  • Webhooks - GitLab Documentation https://docs.gitlab.com/ce/user/project/integrations/webhooks.html#wiki-page-events Wiki Page events 並不帶有 commit，只能從 object_attributes.slug 取得最新的 commit? 若一個 commit 修改多個 wiki page 會觸發多個 event?
  • 若是將 Wiki Event 往 Jenkins 打，由 Jenkins 搭配 Slack Notification plugin 送出 diff 呢?
  • Jenkins 裝了 GitLab Plugin 之後，發現 Enabled GitLab triggers 裡並不支援 Wiki Page event
  • Jenkins Plugins https://plugins.jenkins.io/generic-webhook-trigger 可以用來接 Wiki Page event? 似乎所有的 job 都共用 http://JENKINS_URL/generic-webhook-trigger/invoke? 何不用 GitLab CI 自己來接?
  • nazrhyn/gitlab-slack: A service that receives hook notifications from GitLab and posts information to an incoming webhook on Slack. https://github.com/nazrhyn/gitlab-slack Wiki page 只會通知有異動，還是沒有 diff。
  • How can you track or be notified of changes to GitHub wikis? - Stack Overflow https://stackoverflow.com/questions/8407917/ 分為 Push approach 與 JSON-based pull approach；或許定時處理也是個方式?
  • 確定 git@.../wiki.git 可以透過 deploy key 拿到 source code；走 Build Triggers > Trigger builds remotely 就可以觸發 (要啟用 Global Security 才看得到這個選項)
  • 如果用 ansi2html 轉換成 HTML，並存成 Jenkins 的 artifact 供其他人開啟瀏覽? 或許直接用 nginx 的 upload module 也不錯?

如何用文字來表現不同的圖形?

Wiki Link

  • 明確前置 ./、../ 或 / 的寫法很明確是相對於 current wiki page 或是從 wiki root 起算，這時候寫與不寫 wiki page 的副檔名，結果並無差別。
  • 否則會因有沒有副檔名而有不同的解讀 -- 無副檔名時視為相對於 wiki root，有副檔名時則是相對於 current wiki page。

參考資料：

  • Wiki-specific Markdown - GitLab Markdown | GitLab

    • A link which just includes the slug for a page will point to that page (沒有副檔名而言), at the BASE LEVEL of the wiki. This snippet would link to a documentation page at the ROOT of your wiki:

      [Link to Documentation](documentation)

    • Links with a FILE EXTENSION point to that file, RELATIVE to the CURRENT PAGE. If this snippet was placed on a page at <your_wiki>/documentation/related, it would link to <your_wiki>/documentation/file.md:

      [Link to File](file.md)

    • A link can be constructed RELATIVE to the CURRENT WIKI PAGE using ./<page>, ../<page>, etc.

      • If this snippet was placed on a page at <your_wiki>/documentation/main, it would link to <your_wiki>/documentation/related: [Link to Related Page](./related)
      • If this snippet was placed on a page at <your_wiki>/documentation/related/content, it would link to <your_wiki>/documentation/main: [Link to Related Page](../main)
      • If this snippet was placed on a page at <your_wiki>/documentation/main, it would link to <your_wiki>/documentation/related.md: [Link to Related Page](./related.md) 看似跟第一個例子沒有差別? 其實是有副檔名的狀況，也間接說明了要連到其他 wiki page，副檔名可以省略。
      • If this snippet was placed on a page at <your_wiki>/documentation/related/content, it would link to <your_wiki>/documentation/main.md: [Link to Related Page](../main.md)

    • A link starting with a / is RELATIVE to the WIKI ROOT.

      • This snippet links to <wiki_root>/documentation: [Link to Related Page](/documentation) 搭配上面 "A link which just includes the slug for a page" 的說法，在沒有副檔名的情況下，前面的 / 其實是可以省略的。
      • This snippet links to <wiki_root>/miscellaneous.md: [Link to Related Page](/miscellaneous.md)

自訂 Sidebar {: #customizing-sidebar }

  • 預設的 sidebar 會無腦地列出所有的 wiki page，它的的存在會讓人忽視頁面間連結的重要性。
  • 用 /_sidebar.md 可以自訂 sidebar，但原本 sidebar 下方 More Pages 的按鈕/連結還是會在。

參考資料：

參考資料 {: #reference }

文件：

相關：

  • 數學等式的語法採 LaTeX，透過 KaTeX 在前端表現出來。