Ce diaporama a bien été signalé.
Le téléchargement de votre SlideShare est en cours. ×

你一定不能不知道的 Markdown 寫作技巧

你一定不能不知道的 Markdown 寫作技巧

上一代的工程師用 Word 寫文件,現代的工程師用 Markdown 寫文件。雖然 Markdown 語法「看起來」很簡單、很好上手,但卻導致一堆人太過隨心所欲的去寫,導致排版亂七八糟,不然就是團隊之間的 Markdown 撰寫風格迥異,不好維護,可讀性也大幅降低。
沒有人告訴我們怎樣寫 Markdown 才是正確的,針對一些特殊的排版風格也非常不好編排,這場直播,我將分享多年來的 Markdown 撰寫習慣,以及分享各種好用的 Markdown 工具與應用技巧,歡迎大家踴躍參加,一起打造更好的工程文件!

上一代的工程師用 Word 寫文件,現代的工程師用 Markdown 寫文件。雖然 Markdown 語法「看起來」很簡單、很好上手,但卻導致一堆人太過隨心所欲的去寫,導致排版亂七八糟,不然就是團隊之間的 Markdown 撰寫風格迥異,不好維護,可讀性也大幅降低。
沒有人告訴我們怎樣寫 Markdown 才是正確的,針對一些特殊的排版風格也非常不好編排,這場直播,我將分享多年來的 Markdown 撰寫習慣,以及分享各種好用的 Markdown 工具與應用技巧,歡迎大家踴躍參加,一起打造更好的工程文件!

Plus De Contenu Connexe

你一定不能不知道的 Markdown 寫作技巧

  1. 1. 基礎語法、驗證規則、應用技巧 你一定不能不知道的 Markdown 寫作技巧 多奇數位創意有限公司 技術總監 黃保翕(Will 保哥) https://blog.miniasp.com
  2. 2. 基礎語法 Basic Syntax
  3. 3. 段落、換行與標題 • 段落 - 每個段落中間多空一行就對了! • 換行 - 想要多空一行請輸入 <br /> 或加入反斜線 ( ) 在行尾 • 標題 # This is a H1 header ## This is a H2 header ### This is a H3 header #### This is a H4 header ##### This is a H5 header 3
  4. 4. 清單、檢查清單 • 項目清單、編號清單 * Red * Green * Blue • 檢查清單 - [ ] A - [ ] B - [ ] C - [x] A - [x] B - [x] C 4 - Red - Green - Blue + Red + Green + Blue 1. Red 2. Green 3. Blue 1. Red 1. Green 1. Blue
  5. 5. 多行清單 • 正常行距的多行清單 * Lorem ipsum dolor sit amet, consectetuer. Aliquam hendrerit mi posuere lectus. Vestibulum enim wisi, * Donec sit amet nisl. Aliquam semper ipsum sit amet velit. Suspendisse id sem consectetuer libero luctus adipiscing. • 加大行距的多行清單 * Lorem ipsum dolor sit amet, consectetuer. Aliquam hendrerit mi posuere lectus. Vestibulum enim wisi, * Donec sit amet nisl. Aliquam semper ipsum sit amet velit. Suspendisse id sem consectetuer libero luctus adipiscing. 5
  6. 6. 粗體、斜體、刪除線 • 粗體 **TEXT** • 斜體 *TEXT* _TEXT_ • 刪除線 ~~TEXT~~ 6 • 粗體+斜體 **_OK_** • 粗體+斜體+刪除線 **_~~TEXT~~_** • 粗體+刪除線 **~~TEXT~~** • 斜體+刪除線 *~~TEXT~~* _~~TEXT~~_
  7. 7. 分隔線、引言、行內程式碼 • 分隔線 *** * * * --- - - - ---------------- • 引言 (blockquote) > ## This is a header. > > 1. This is the first list item. > 2. This is the second list item. • 行內程式碼 This is `ASP.NET Core 5.0`. 7
  8. 8. 文字區塊與程式碼區塊 • 直接縮排就會產生文字區塊 public void Run() {} • 使用 ``` 產生程式碼區塊 ```cs public void Run() {} ``` ```sql SELECT @@VERSION ``` 8 ```csharp public void Run() {} ``` ```ps1 Get-ChildItem ``` ```sh ssh-keygen ```
  9. 9. 超連結與圖片 • 一般文字超連結 [Link Text](Link URL) • 載入圖片 ![Image Alt Text](Image URL) • 載入圖片並指定大小 (Azure DevOps) ![Image Alt Text](IMAGE_URL =WIDTHxHEIGHT) • 載入圖片並指定大小 (GitHub) <img src="IMAGE_URL" width="100" height="100"> 9
  10. 10. 表格 • 基本表格 | Heading 1 | Heading 2 | Heading 3 | |-----------|-----------|---------------------------------| | Cell A1 | Cell A2 | Cell A3 | | Cell B1 | Cell B2 | Cell B3<br/>second line of text | • 對齊的儲存格 | 靠左對齊 | 置中對齊 | 靠右對齊 | |-----------|:-----------:|--------------------------------:| | Cell A1 | Cell A2 | Cell A3 | | Cell B1 | Cell B2 | Cell B3<br/>second line of text | 10
  11. 11. 註解 • 直接使用 HTML 的註解語法 <!-- COMMENTS --> 11
  12. 12. 跳脫字元 • 以下符號都可以透過 (反斜線) 跳脫 反斜線 ` 反引號 * 星號 _ 底線 {} 大括號 [] 方括號 () 括號 # 井字號 + 加號 - 減號 . 英文句點 ! 驚嘆號 12
  13. 13. Azure DevOps Wiki 專屬 Markdown 語法 Syntax guidance for Markdown usage in Wiki
  14. 14. 文件大綱 (Table of contents) (TOC) • Azure DevOps 的 Wiki 可使用以下代碼自動產生文件大綱 • 基本語法 [[_TOC_]] 14
  15. 15. Mermaid diagrams • Azure DevOps 的 Wiki 僅支援以下三種 Mermaid 圖表類型 • 循序圖 ▶ Sequence diagrams • 甘特圖 ▶ Gantt Charts • 流程圖 ▶ Flowcharts • 基本語法 ::: mermaid <mermaid diagram syntax> ::: 15 這裡記得要加一個空白字元
  16. 16. 內嵌影片 • Azure DevOps 的 Wiki 支援內嵌影片語法(透過 iframe 內嵌) • 基本語法 ::: video <iframe width="560" height="315" src="https://www.youtube.com/embed/OtqFyBA6Dbk" frameborder="0" allow="autoplay; encrypted-media" allowfullscreen></iframe> ::: 16
  17. 17. YAML 標籤 (Tags) • Azure DevOps 的 Wiki 支援 YAML 標籤顯示 - 文件最前面有插入 YAML 專屬語法的話,就會自動以表格來呈現文件屬性 • 基本 YAML 語法 --- tag: post title: Hello world --- 17 • 其他 YAML 範例 (Tags with list) --- tags: - post - code - web title: Hello world ---
  18. 18. 工作項目的查詢結果顯示 • Azure DevOps 的 Wiki 支援 查詢結果 顯示 • 基本 YAML 語法 ::: query-table <queryid> ::: 18
  19. 19. 提及群組或個人 • Azure DevOps 的 Wiki 可以用 @ 提及特定人或群組 - 儲存之後對方會收到 E-mail 通知 • 基本 YAML 語法 @<成員姓名> 19
  20. 20. 連結工作項目 (Link to work item) • Azure DevOps 的 Wiki 可以用 @ 提及特定人或群組 - 儲存之後對方會收到 E-mail 通知 • 基本 YAML 語法 #WorkItemID 20
  21. 21. 驗證規則 markdownlint
  22. 22. markdownlint • 簡介 - A Node.js style checker and lint tool for Markdown/CommonMark files. • 為什麼要 Lint 你寫的 Markdown 文件? - CommonMark 是一份 Markdown 的共同標準規格(主要給 Parser 用的) - 由於 Markdown 主打彈性好上手,所以對使用者的規範並不多 - 沒有規範的 Markdown 文件,會有可讀性問題,也會有維護性問題 • 點檔案 (dot files) - 專案中加入 .markdownlint.json 可以設定工具該如何驗證 Markdown 文件 - 請安裝 Visual Studio Code 的 markdownlint 擴充套件 22
  23. 23. 認識幾條重要的 MarkdownLint Rules • MarkdownLint Rules - https://github.com/DavidAnson/markdownlint/blob/main/doc/Rules.md • Rules - MD001 - Heading levels should only increment by one level at a time - MD012 - Multiple consecutive blank lines - MD013 - Line length - MD028 - Blank line inside blockquote - MD029 - Ordered list item prefix - MD034 - Bare URL used - MD041 - First line in a file should be a top-level heading - MD044 - Proper names should have the correct capitalization 23
  24. 24. 應用技巧 Tips
  25. 25. Markdown Extension Pack • markdownlint • Markdown All in One • Markdown Table Prettifier • Markdown Paste Image • Excel to Markdown table • Copy Markdown as HTML 25
  26. 26. 必須記得的好用快速鍵 • Ctrl + B 切換粗體 (Toggle Bold) • Ctrl + I 切換斜體 (Toggle Italic) • Alt + S 切換刪除線 (Toggle Strikethrough) • Alt + C 核取工作清單項目 (Check/Uncheck item) • Ctrl + Alt + V 貼上圖片 ( res/... ) • Shift + Alt + V 貼上從 Excel 複製的剪貼簿內容 • Ctrl + Shift + V 從第二編輯器進行 Markdown 預覽 • Ctrl + . 快速修正違規 (Quick Fix) • Alt + Shift + . 自動修正所有違規 • Alt + Shift + F 自動格式化文件(含表格) • Ctrl + Alt + Shift + F 強迫格式化文件(自動修正所有格式) (需安裝 Prettier - Code formatter 才有此功能) 26
  27. 27. 插入超連結的兩種作法 • 快速鍵:Ctrl + V (直接貼上超連結) - 複製超連結 - 選取文字 - 貼上連結位址 • 快速鍵:Ctrl + K (手動輸入超連結) - 選取文字 - 按下 Ctrl + K - 輸入連結位址 27
  28. 28. .markdownlint.json { "MD001": false, "MD012": false, "MD013": false, "MD028": false, "MD034": false, "MD041": false, "MD044": false, "MD029": { "style": "ordered" } } 28
  29. 29. .editorconfig root = true [*] indent_style = space indent_size = 4 end_of_line = crlf charset = utf-8 trim_trailing_whitespace = true insert_final_newline = false [*.md] indent_size = 2 29
  30. 30. 相關連結 • Markdown 語法說明 ( https://markdown.tw ) • Azure DevOps - Syntax guidance for basic Markdown usage - Syntax guidance for Markdown usage in Wiki - Keyboard shortcuts for managing Wiki pages • GitHub - Mastering Markdown • Visual Studio Code - Markdown and Visual Studio Code - Markdown Extension Pack extension 👍 30
  31. 31. 聯絡資訊 • The Will Will Web 記載著 Will 在網路世界的學習心得與技術分享 - http://blog.miniasp.com/ • Will 保哥的技術交流中心 (臉書粉絲專頁) - http://www.facebook.com/will.fans • Will 保哥的推特 - https://twitter.com/Will_Huang 31

Notes de l'éditeur


  • getHeroes (): Observable<Hero[]> {
    return this.http.get(this.heroesUrl)
    .catch(this.handleError);
    }

    擷取資料
    private extractData(res: Response) {
    let body = res.json();
    return body.data || { };
    }

×