跳轉到

新增頁面

在 MkDocs 中,新增頁面就是新增一個 .md 的檔案,檔案需要將放在 docs 中,如果希望顯示在網站選單中,則需要同步在 yml 檔案中添加相對應的路徑。

檔案結構

一個標準的 MkDocs 專案結構如下所示,所有的原始內容都必須放在 docs 資料夾內,舉例而言,我要新增一個 new-page 的頁面,則我在 docs/ 中新增一個 new-page.md 的頁面。

單層導航設定

my-notes/
├── mkdocs.yml       # 全域設定檔
└── docs/            # 存放內容的目錄
    ├── index.md     # ➕網站首頁 --> http://127.0.0.1:8000/
    └── new-page.md  # ➕新增一個頁面 --> http://127.0.0.1:8000/new-page/

當然也可以透過資料夾的方式讓呈現更完整,例如:

多層級選單設定

my-notes/
├── mkdocs.yml           # 全域設定檔
└── docs/                # 存放內容的目錄
    ├── index.md         # ➕網站首頁 --> http://127.0.0.1:8000/
    ├── python/          # ➕新增一個主題
    |   ├── intro.md     # ➕新增該主題的其中一個頁面 --> http://127.0.0.1:8000/python/intro/
    |   ├── install.md   # ➕新增該主題的其中一個頁面 --> http://127.0.0.1:8000/python/install/
    |   ...
    └── mkdocs/          # ➕新增一個主題
        ├── intro.md     # ➕新增該主題的其中一個頁面 --> http://127.0.0.1:8000/mkdocs/intro/
        ├── install.md   # ➕新增該主題的其中一個頁面 --> http://127.0.0.1:8000/mkdocs/install/
        ... 

設定導航

MkDocs 使用 YAML 語法來管理導航欄。你需要編輯根目錄下的 mkdocs.yml,並在 nav 的區塊下新增docs 資料夾內的相對路徑。

單層導航設定

site_name: 我的技術筆記

nav:
- 首頁: index.md
- 新頁面: new-page.md

多層級選單設定

nav:
- 首頁: index.md
- python:
    - 介紹: python/intro.md
    - 安裝: python/install.md
- mkdocs:
    - 介紹: mkdocs/intro.md
    - 安裝: mkdocs/install.md