MkDocs & MarkDown 入門

---

建制開發環境

安裝Python

• 安裝Python
  

Note

Stable ReleasesPre-releases

穩定版發行版(建議安裝)
通常已經用於生產且經過測試並修復已知的BUG

還在開發中的版本
可能包含新功能,但也可能包含錯誤或不穩定的代碼

下載完後檢查版本 在終端機輸入

pythonpython3

python --version

python3 --version

如果使用python出現如下錯誤 請使用python3

不想多打一個3的話需要利用終端機執行下列命令將 python 指向 python3 的符號鏈接

sudo ln -s $(which python3) /usr/local/bin/python #需要用管理員密碼  

安裝MkDocs 及 Material樣式

透過pip安裝MkDocs -> 採用Material 的樣式與功能 -> 確認版本

pip install mkdocs 

python pip install material

mkdocs --version

實作

新增專案

新增專案名稱為 my-project

mkdocs new my-project

新增後會生成這樣的檔案

my-project #專案資料夾

docs #

index.md #主畫面

mkdocs.yml #配置檔

• 啟動服務

  mkdocs serve        
  

  會看到預設頁面

• 修改mkdocs.yml(配置檔)

配置檔

site_name:標題title
nav:在左邊側欄增加頁面
theme:
- name:主題樣式

site_name: 'Angular Courses 2024' 
    site_dir: public
    nav:
        - Home: index.md 
    theme:
        name: material 

• 修改後會如下圖

• 新增子頁

  使用touch指令在專案中建立子頁面(需與docs建立在相同目錄下 )
  

  touch docs/home.md       
  touch docs/about.md        
  touch docs/contact.md     
  

  在mkdocs.yml中新增nav

  nav :
      - Home: home.md # (1)!
      - About: about.md
      - Contact: contact.md
  

  1. Home 為頁面顯示的文字 : home.md為路徑

頁面顯示 Home , About , Contact 路徑

---

• 以上是環境建置概略說明