Table of Contents
MarkDown ↵
Markdown & MkDocs 簡介
文件格式採用 Markdown,並以 MkDocs 格式呈現,這樣的配置具有多項好處,使文件的管理和發佈更加高效和便捷。
MkDocs 的優勢
Markdown 文字格式的優點
-
- 簡單易用:
- Markdown 語法簡潔明瞭,易於學習和使用。這使得撰寫和維護文檔變得更加輕鬆,即便是非技術人員也能快速上手。
-
- 版本控制:
- 使用 Git 進行版本控制,可以輕鬆跟蹤文檔的變更歷史,進行回溯和比較。這對於大型文檔專案尤為重要,能夠確保每次變更都有跡可循。
-
- 多人協作:
- 支持多人同時編輯,透過 Git 進行協同作業,避免版本衝突。每個人都可以在自己的分支上工作,最終合併到主分支,確保文檔內容一致。
-
- 生成式 AI 支援:
- Markdown 文件格式與生成式 AI 工具(如 ChatGPT 和 GitHub Copilot)相容性良好,可以獲得智能輔助。這些工具能夠提供即時建議、自動補全和範例代碼,大大提升編輯效率。
輸出 PDF
- MkDocs 支援將 Markdown 文件輸出為 PDF 檔案,方便打印和離線閱讀。這使得我們可以在維持線上文件的同時,也能生成高品質的打印版文檔,滿足不同使用場景的需求。
靜態網站生成與 CI/CD 集成
- MkDocs 可以生成靜態網站,搭配 CI/CD 管道,可以實現自動化部署。每當文件更新後,系統能自動生成並發布最新版本的網站,確保文件內容的即時性和準確性。例如,我們可以配置 GitHub Actions 或 Azure DevOps Pipeline 來實現這一功能,使文檔管理更高效。
即時更新
- 透過 MkDocs,我們可以將文件變更即時反映到網站上。這意味著,無論是修正錯誤、添加新內容,還是進行其他更新,都可以迅速地部署到生產環境,讓使用者始終訪問到最新的文檔內容。
支援 Mermaid 圖表
- MkDocs 支援 Mermaid 插件,可以方便地繪製各種圖表,包括系統分析常用的 UML 圖表。這對於系統設計和分析文檔尤為重要,因為我們可以直接在 Markdown 文件中嵌入 UML 圖,提升文檔的專業性和可讀性。
搜尋功能
- MkDocs 提供強大的搜尋功能,能夠快速定位到所需的文檔內容。即使文件內容龐大,使用者也可以通過搜尋框迅速找到所需的信息,提升工作效率。
客製化與擴展性
- MkDocs 支援多種主題和插件,可以根據需求進行客製化配置。例如,我們可以使用自定義的 CSS 和 JavaScript 文件來改變網站的外觀和行為,或者引入第三方插件來增加功能,如表格讀取、圖片放大等。
結論
- 使用 MkDocs 來建立和管理 SA 文件,不僅提高了文檔的可讀性和專業性,還大大提升了文檔管理的效率。透過 Markdown 的簡潔格式、Git 版控、多人協作、生成式 AI 支援、PDF 輸出、靜態網站生成與自動化部署,以及豐富的圖表和搜尋功能,我們可以輕鬆地創建、更新和發布高品質的系統分析文檔。
Markdown基本指南
1. 介紹
Markdown 是一種輕量級標記語言,使用純文本格式來創建格式化的文檔。它被廣泛應用於撰寫 README 文件、文檔、博客文章等。Markdown 的設計目的是讓書寫和閱讀都非常簡單。
MkDocs 是一個靜態網站生成器,專為建立專案文檔而設計。它以 Markdown 文件為基礎,生成靜態網站,方便分享和發布專案的文檔。
使用VsCode編輯建議安裝 Markdown Preview Enhanced按下ctrl+k
後再按v
及時預覽編輯畫面
2. Markdown 語法
Markdown 語法簡單且易於使用,以下將詳細介紹其常見語法。
標題
Markdown 使用 #
來表示標題。使用的 #
越多,標題層級越低。
# 一級標題建議只用一次且必須在md檔案最上方
## 二級標題
### 三級標題
#### 四級標題
##### 五級標題
###### 六級標題
二級標題
三級標題
四級標題
五級標題
六級標題
段落和換行
段落由一個或多個連續的文本行組成,段落之間需要空一行來區分。
要插入換行符,可以在行末尾加上兩個或更多的空格,然後按 Enter。
換行方式在結尾按兩次空白鍵後按enter 像這樣
第一行
第二行
如果直接按enter換行即使在編輯時有換行但顯示出來還是在同一行 像這樣
第一行
第二行
換行方式在結尾按兩次空白鍵後按enter 像這樣
第一行
第二行
如果直接按enter換行即使在編輯時有換行但顯示出來還是在同一行 像這樣
第一行
第二行
強調
Markdown 提供了斜體和粗體兩種強調方式。因為我們文件並沒有使用斜體,所以有調整css將斜體改成雙框線
**粗體** 或 __粗體__
*雙框線* 或 _雙框線_
***粗雙框線*** 或 ___粗雙框線___
粗體 或 粗體
雙框線 或 雙框線
粗雙框線 或 粗雙框線
區塊引用
使用 >
來表示區塊引用,可以嵌套使用。
> 這是一個區塊引用。
> 這是另一個區塊引用。
>> 這是嵌套的區塊引用。
這是一個區塊引用。
這是另一個區塊引用。
這是嵌套的區塊引用。
列表
Markdown 支持有序和無序列表。
無序列表使用 -
、*
或 +
。
- 項目一
- 項目二
- 子項目一
- 子項目二
* 項目一
* 項目二
+ 項目一
+ 項目二
- 項目一
- 項目二
- 子項目一
- 子項目二
- 項目一
- 項目二
- 項目一
- 項目二
有序列表使用數字加句點。
1. 第一項
2. 第二項
1. 子項一
2. 子項二
- 第一項
- 第二項
- 子項一
- 子項二
連結
Markdown 使用方括號加括號內的 URL 來創建連結。
這是 [Google](https://www.google.com) 的連結。
這是 Google 的連結。
圖片
圖片語法與連結相似,但在前面加一個驚嘆號 !
。
![URL圖片](https://cdn.iconscout.com/icon/free/png-256/free-markdown-1-457956.png)
![本地圖片](images/free-markdown-1-457956.webp)
程式碼區塊
單行碼區塊使用反引號 `。
這是一段 `碼區塊` 範例。
碼區塊
範例。
程式碼區塊使用三個反引號 ```
```
這是一個程式碼區塊。
```
或四個空格
這是使用四個空格的程式碼區塊
可以指定語言來進行語法高亮顯示。
```python
def hello_world():
print("Hello, World!")
```
表格
表格使用 |
分隔列,使用 -
分隔表頭和其他行。
| 標題一置左 | 標題二置中 | 標題三置右 |
| :-------- | :------: | ------: |
| 單元格 1 | 單元格 2 | 單元格3 |
| 單元格 4 | 單元格 5 | 單元格6 |
標題一置左 | 標題二置中 | 標題三置右 |
---|---|---|
單元格 1 | 單元格 2 | 單元格3 |
單元格 4 | 單元格 5 | 單元格6 |
水平線
水平線使用三個或更多的 -
、*
或 _
。
---
***
___
逃脫字元
如果需要在 Markdown 中顯示 Markdown 語法符號,可以使用反斜杠 \
進行逃脫。
\*這不是斜體\*
\# 這不是標題
*這不是斜體*
# 這不是標題
其他語法
文字上色方式
效果 | 語法 |
---|---|
新增 | {++新增++ } |
{--刪除-- } |
|
{~~ 替換舊 ~> 替換新 ~~ } |
|
強調 | {== 強調 ==} |
雙框 | *雙框* |
粗體 | **粗體** |
Warning
為使用雙框,此文檔不能使用斜體
警告框
用法
!!! warning
為使用雙框,此文檔不能使用斜體
Note
以???
開頭可以將區塊變成可折疊
??? note
可折疊
Note
可折疊
???
+預設展開
???+ note
預設展開
Note
預設展開
Warning
內文需要縮排
增加標題方式
!!! abstract "增加標題方式"
!!! abstract ""
不要標題
不要標題
其他提示框
Tip
Success
Question
Warning
Failure
Danger
Bug
Example
Quote
選項卡
=== "步驟一"
- 內文一
=== "步驟二"
- 內文二
=== "注意事項 "
- 內文需要縮排
=== "使用時機"
- 如果有文件需要寫步驟可使用
效果
- 內文一
- 內文二
- 內文需要縮排
- 如果有文件需要寫步驟可使用
checkbox
- [ ] 集保admin
- [x] 集保主管
- [x] 集保經辦
- [ ] 集保理級
- [ ] 申請單位代號 admin
- [ ] 申請單位代號主管
- [ ] 申請單位代號經辦
- 集保admin
- 集保主管
- 集保經辦
- 集保理級
- 申請單位代號 admin
- 申請單位代號主管
- 申請單位代號經辦
Mermaid使用方式
使用Mermaid Live Edit編輯mermaid
- stateDiagram
```mermaid stateDiagram direction TB [*]--> 插入卡片 插入卡片 --> 讀取PIN碼: 讀卡 插入卡片 --> 退出卡片: 無效的卡片 讀取PIN碼 --> 選擇交易項目: 有效的PIN碼 讀取PIN碼 --> 退出卡片:無效的PIN碼 選擇交易項目 --> 退出卡片: 取消交易 選擇交易項目 --> 執行交易: 交易選擇 執行交易 --> 選擇交易項目: 其他交易 執行交易 --> 退出卡片: 結束交易 退出卡片 --> [*] ```
stateDiagram
direction TB
[*]--> 插入卡片
插入卡片 --> 讀取PIN碼: 讀卡
插入卡片 --> 退出卡片: 無效的卡片
讀取PIN碼 --> 選擇交易項目: 有效的PIN碼
讀取PIN碼 --> 退出卡片:無效的PIN碼
選擇交易項目 --> 退出卡片: 取消交易
選擇交易項目 --> 執行交易: 交易選擇
執行交易 --> 選擇交易項目: 其他交易
執行交易 --> 退出卡片: 結束交易
退出卡片 --> [*]
- sequenceDiagram
```mermaid sequenceDiagram actor User participant ATM participant Bank User->>ATM: 插入卡片 ATM->>User: 輸入密碼 User->>ATM: 輸入密碼 ATM->>Bank: 驗證密碼 Bank->>ATM: 密碼正確 ATM->>User: 顯示交易項目 User->>ATM: 選擇交易項目 ATM->>User: 顯示交易金額項目 User->>ATM: 選擇交易金額 ATM->>Bank: 交易進行 Bank->>ATM: 交易執行成功 ATM->>User: 配發現金 User->>ATM: 要求拿取現金 ATM->>User: 拿取現金 User->>ATM: 是否繼續交易 User->>ATM: 結束交易 ATM->>User: 顯示餘額 ```
sequenceDiagram
actor User
participant ATM
participant Bank
User->>ATM: 插入卡片
ATM->>User: 輸入密碼
User->>ATM: 輸入密碼
ATM->>Bank: 驗證密碼
Bank->>ATM: 密碼正確
ATM->>User: 顯示交易項目
User->>ATM: 選擇交易項目
ATM->>User: 顯示交易金額項目
User->>ATM: 選擇交易金額
ATM->>Bank: 交易進行
Bank->>ATM: 交易執行成功
ATM->>User: 配發現金
User->>ATM: 要求拿取現金
ATM->>User: 拿取現金
User->>ATM: 是否繼續交易
User->>ATM: 結束交易
ATM->>User: 顯示餘額
表格使用方式
| 姓名 | 年齡 | 職業 |
| :---- | :----: | ----: |
| 置左 | 置中 | 置右 |
| 張三 | 30 | 工程師 |
| 李四 | 25 | 設計師 |
| 王五 | 35 | 醫生 |
- 讀取excel表格
語法:
{{
read_csv('table/test.csv') }}
姓名 | 年齡 | 職業 |
---|---|---|
張三 | 30 | 工程師 |
李四 | 25 | 設計師 |
王五 | 35 | 醫生 |
{{
read_csv(('table/test.csv' ) , colalign=("left","center","right")) }}
對齊方式
colalign=("left","center","right")
有多個欄位想設定就填幾個
不填寫預設文字靠左數字靠右
姓名 | 年齡 | 職業 |
---|---|---|
張三 | 30 | 工程師 |
李四 | 25 | 設計師 |
王五 | 35 | 醫生 |
Warning
為了方便製作表格,使用CSV格式。存檔時選擇CSV UTF-8(逗號分隔) 若不選擇此格式會亂碼
- 在表格內要換行有兩種方式
- 使用br
姓名 | 年齡 | 性別 | 職業 | 城市 | 興趣 |
---|---|---|---|---|---|
李小華 | 34 | 女 | 設計師 | 台中 | 繪畫 登山 閱讀 音樂 |
張麗麗 | 22 | 女 | 學生 | 台南 | 閱讀 音樂 下棋 烹飪 |
陳大偉 | 45 | 男 | 醫生 | 高雄 | 下棋 瑜伽 烹飪 |
- 使用alt+enter(在excel格子內換行)
姓名 | 年齡 | 性別 | 職業 | 城市 | 興趣 |
---|---|---|---|---|---|
李小華 | 34 | 女 | 設計師 | 台中 | 繪畫 |
登山 | |||||
閱讀 | |||||
烹飪 | |||||
張麗麗 | 22 | 女 | 學生 | 台南 | 閱讀 |
音樂 | |||||
下棋 | |||||
烹飪 | |||||
陳大偉 | 45 | 男 | 醫生 | 高雄 | 下棋 |
瑜伽 | |||||
烹飪 |
使用與不使用差別
使用< br>標籤時在MD顯示會較為清楚,但在excel撰寫時可能會導致易讀性較差
在excel格子內換行的話撰寫易讀性較高,但在MD顯示會較不清楚。
待討論議題Icon
在想要放置icon的地方使用:material-chat-question:{ .question}
像這樣:material-chat-question:{ .question}
Ended: MarkDown
MkDocs基本指南
1. MkDocs 介紹
安裝 MkDocs
MkDocs 可以通過 Python 的 pip
安裝。
pip install mkdocs
創建專案
使用 MkDocs 創建新專案非常簡單。首先,打開命令行並運行以下命令:
mkdocs new my-project
cd my-project
這會創建一個新的 MkDocs 專案目錄結構。
設置和配置
專案創建後,可以通過編輯 mkdocs.yml
配置文件來設置網站。
site_name: MarkDown & MkDocs 簡介
nav:
- MarkDown:
- 簡介: index.md
- 基本語法 : 'pages/markdown/markdown1.md'
- 其他語法 : 'pages/markdown/markdown2.md'
- MkDocs : 'pages/mkdocs/mkdocs.md'
主題和擴展
MkDocs 提供了多種主題,可以在配置文件中設置主題。
theme:
name: readthedocs
可以通過安裝擴展來增強 MkDocs 的功能。例如,可以使用 mkdocs-material
主題:
pip install mkdocs-material
然後在配置文件中設置:
theme:
name: material
部署
完成設置和內容創建後,可以使用以下命令構建和部署網站:
mkdocs serve
這會在本地啟動一個開發服務器,預設情況下在 http://127.0.0.1:8000/
。
如果要開啟多個mkdocs使用
mkdocs serve -a 127.0.0.1:80xx
2. 注意事項和最佳實踐
- 保持簡潔:Markdown 的設計目的是保持文本的可讀性,避免過多的嵌套和複雜結構。
- 一致性:保持標題、列表和其他元素的格式一致性,提高文檔的可讀性和可維護性。
- 命名規則:對圖片、連結和文件使用有意義且一致的命名規則。
- 預覽:在編輯 Markdown 文檔時,經常使用預覽功能查看最終效果,確保格式正確。
- 版本控制:使用版本控制系統(如 Git)管理文檔變更,方便追溯和協作。
- 自動化:使用工具和腳本自動化構建和部署過程,提高效率和減少錯誤。
Markdown 和 MkDocs 是強大且靈活的工具,適合各種文檔撰寫和網站生成需求。掌握 Markdown 語法並善用 MkDocs 的功能,可以大大提升文檔編寫和管理的效率。在使用過程中,注意保持文檔的簡潔和一致性,並善用自動化工具來減少工作量。