KEMBAR78
你一定不能不知道的 Markdown 寫作技巧 | PPTX
基礎語法、驗證規則、應用技巧
你一定不能不知道的 Markdown 寫作技巧
多奇數位創意有限公司
技術總監 黃保翕(Will 保哥)
https://blog.miniasp.com
基礎語法
Basic Syntax
段落、換行與標題
• 段落
- 每個段落中間多空一行就對了!
• 換行
- 想要多空一行請輸入 <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
清單、檢查清單
• 項目清單、編號清單
* 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
多行清單
• 正常行距的多行清單
* 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
粗體、斜體、刪除線
• 粗體
**TEXT**
• 斜體
*TEXT*
_TEXT_
• 刪除線
~~TEXT~~
6
• 粗體+斜體
**_OK_**
• 粗體+斜體+刪除線
**_~~TEXT~~_**
• 粗體+刪除線
**~~TEXT~~**
• 斜體+刪除線
*~~TEXT~~*
_~~TEXT~~_
分隔線、引言、行內程式碼
• 分隔線
*** * * * --- - - - ----------------
• 引言 (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
文字區塊與程式碼區塊
• 直接縮排就會產生文字區塊
public void Run() {}
• 使用 ``` 產生程式碼區塊
```cs
public void Run() {}
```
```sql
SELECT @@VERSION
```
8
```csharp
public void Run() {}
```
```ps1
Get-ChildItem
```
```sh
ssh-keygen
```
超連結與圖片
• 一般文字超連結
[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
表格
• 基本表格
| 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
註解
• 直接使用 HTML 的註解語法
<!-- COMMENTS -->
11
跳脫字元
• 以下符號都可以透過  (反斜線) 跳脫
 反斜線
` 反引號
* 星號
_ 底線
{} 大括號
[] 方括號
() 括號
# 井字號
+ 加號
- 減號
. 英文句點
! 驚嘆號
12
Azure DevOps Wiki 專屬 Markdown 語法
Syntax guidance for Markdown usage in Wiki
文件大綱 (Table of contents) (TOC)
• Azure DevOps 的 Wiki 可使用以下代碼自動產生文件大綱
• 基本語法
[[_TOC_]]
14
Mermaid diagrams
• Azure DevOps 的 Wiki 僅支援以下三種 Mermaid 圖表類型
• 循序圖 ▶ Sequence diagrams
• 甘特圖 ▶ Gantt Charts
• 流程圖 ▶ Flowcharts
• 基本語法
::: mermaid
<mermaid diagram syntax>
:::
15
這裡記得要加一個空白字元
內嵌影片
• 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
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
---
工作項目的查詢結果顯示
• Azure DevOps 的 Wiki 支援 查詢結果 顯示
• 基本 YAML 語法
::: query-table <queryid>
:::
18
提及群組或個人
• Azure DevOps 的 Wiki 可以用 @ 提及特定人或群組
- 儲存之後對方會收到 E-mail 通知
• 基本 YAML 語法
@<成員姓名>
19
連結工作項目 (Link to work item)
• Azure DevOps 的 Wiki 可以用 @ 提及特定人或群組
- 儲存之後對方會收到 E-mail 通知
• 基本 YAML 語法
#WorkItemID
20
驗證規則
markdownlint
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
認識幾條重要的 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
應用技巧
Tips
Markdown Extension Pack
• markdownlint
• Markdown All in One
• Markdown Table Prettifier
• Markdown Paste Image
• Excel to Markdown table
• Copy Markdown as HTML
25
必須記得的好用快速鍵
• 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
插入超連結的兩種作法
• 快速鍵:Ctrl + V (直接貼上超連結)
- 複製超連結
- 選取文字
- 貼上連結位址
• 快速鍵:Ctrl + K (手動輸入超連結)
- 選取文字
- 按下 Ctrl + K
- 輸入連結位址
27
.markdownlint.json
{
"MD001": false,
"MD012": false,
"MD013": false,
"MD028": false,
"MD034": false,
"MD041": false,
"MD044": false,
"MD029": {
"style": "ordered"
}
}
28
.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
相關連結
• 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
聯絡資訊
• The Will Will Web
記載著 Will 在網路世界的學習心得與技術分享
- http://blog.miniasp.com/
• Will 保哥的技術交流中心 (臉書粉絲專頁)
- http://www.facebook.com/will.fans
• Will 保哥的推特
- https://twitter.com/Will_Huang
31

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

  • 1.
  • 2.
  • 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.
    清單、檢查清單 • 項目清單、編號清單 * 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.
    多行清單 • 正常行距的多行清單 * Loremipsum 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.
    粗體、斜體、刪除線 • 粗體 **TEXT** • 斜體 *TEXT* _TEXT_ •刪除線 ~~TEXT~~ 6 • 粗體+斜體 **_OK_** • 粗體+斜體+刪除線 **_~~TEXT~~_** • 粗體+刪除線 **~~TEXT~~** • 斜體+刪除線 *~~TEXT~~* _~~TEXT~~_
  • 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.
    文字區塊與程式碼區塊 • 直接縮排就會產生文字區塊 public voidRun() {} • 使用 ``` 產生程式碼區塊 ```cs public void Run() {} ``` ```sql SELECT @@VERSION ``` 8 ```csharp public void Run() {} ``` ```ps1 Get-ChildItem ``` ```sh ssh-keygen ```
  • 9.
    超連結與圖片 • 一般文字超連結 [Link Text](LinkURL) • 載入圖片 ![Image Alt Text](Image URL) • 載入圖片並指定大小 (Azure DevOps) ![Image Alt Text](IMAGE_URL =WIDTHxHEIGHT) • 載入圖片並指定大小 (GitHub) <img src="IMAGE_URL" width="100" height="100"> 9
  • 10.
    表格 • 基本表格 | Heading1 | 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.
    註解 • 直接使用 HTML的註解語法 <!-- COMMENTS --> 11
  • 12.
    跳脫字元 • 以下符號都可以透過 (反斜線) 跳脫 反斜線 ` 反引號 * 星號 _ 底線 {} 大括號 [] 方括號 () 括號 # 井字號 + 加號 - 減號 . 英文句點 ! 驚嘆號 12
  • 13.
    Azure DevOps Wiki專屬 Markdown 語法 Syntax guidance for Markdown usage in Wiki
  • 14.
    文件大綱 (Table ofcontents) (TOC) • Azure DevOps 的 Wiki 可使用以下代碼自動產生文件大綱 • 基本語法 [[_TOC_]] 14
  • 15.
    Mermaid diagrams • AzureDevOps 的 Wiki 僅支援以下三種 Mermaid 圖表類型 • 循序圖 ▶ Sequence diagrams • 甘特圖 ▶ Gantt Charts • 流程圖 ▶ Flowcharts • 基本語法 ::: mermaid <mermaid diagram syntax> ::: 15 這裡記得要加一個空白字元
  • 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.
    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.
    工作項目的查詢結果顯示 • Azure DevOps的 Wiki 支援 查詢結果 顯示 • 基本 YAML 語法 ::: query-table <queryid> ::: 18
  • 19.
    提及群組或個人 • Azure DevOps的 Wiki 可以用 @ 提及特定人或群組 - 儲存之後對方會收到 E-mail 通知 • 基本 YAML 語法 @<成員姓名> 19
  • 20.
    連結工作項目 (Link towork item) • Azure DevOps 的 Wiki 可以用 @ 提及特定人或群組 - 儲存之後對方會收到 E-mail 通知 • 基本 YAML 語法 #WorkItemID 20
  • 21.
  • 22.
    markdownlint • 簡介 - ANode.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.
    認識幾條重要的 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.
  • 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.
    必須記得的好用快速鍵 • 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.
    插入超連結的兩種作法 • 快速鍵:Ctrl +V (直接貼上超連結) - 複製超連結 - 選取文字 - 貼上連結位址 • 快速鍵:Ctrl + K (手動輸入超連結) - 選取文字 - 按下 Ctrl + K - 輸入連結位址 27
  • 28.
    .markdownlint.json { "MD001": false, "MD012": false, "MD013":false, "MD028": false, "MD034": false, "MD041": false, "MD044": false, "MD029": { "style": "ordered" } } 28
  • 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.
    相關連結 • 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.
    聯絡資訊 • The WillWill Web 記載著 Will 在網路世界的學習心得與技術分享 - http://blog.miniasp.com/ • Will 保哥的技術交流中心 (臉書粉絲專頁) - http://www.facebook.com/will.fans • Will 保哥的推特 - https://twitter.com/Will_Huang 31

Editor's Notes

  • #4  getHeroes (): Observable<Hero[]> { return this.http.get(this.heroesUrl) .catch(this.handleError); } 擷取資料 private extractData(res: Response) { let body = res.json(); return body.data || { }; }