MkDocs: 構建你自己的知識庫

目錄

• 1. 介紹
• 2. 文件布局
• 3. 索引頁: index.md
• 4. 配置頁面和導航
• 5. 主題
• 6. Configuration: 全部配置項
• 7. 插件
  • 7.1. Search
  • 7.2. mkdocs-localsearch
  • 7.3. awesome-pages-plugin: 簡化頁面順序配置
    • 7.3.1. 安裝
    • 7.3.2. 自定義導航
    • 7.3.3. Rest（剩余頁面）
    • 7.3.4. Titles
    • 7.3.5. Links
    • 7.3.6. 修改排序
    • 7.3.7. 隱藏子目錄
    • 7.3.8. 設置目錄標題
    • 7.3.9. 折疊子目錄
• 8. 生成靜態頁面
• 9. 部署

1. 介紹

github

homepage

MkDocs中文文檔

MkDocs是一個快速、簡單、華麗的靜態網站生成器，適用於構建項目文檔。文檔源文件以Markdown編寫，並使用一個YAML文件來進行配置。 MkDocs生成完全靜態的HTML網站，你可以將其部署到GitHub pages、Amzzon S3或你自己選擇的其它任意地方。

MkDocs有一堆很好看的主題。 官方內置了兩個主題： mkdocs 和readthedocs， 也可以從MkDocs wiki中選擇第三方主題， 或者自定義主題。

支持實時預覽你的網站: 當你編輯Md文件時，內置的開發服務可以幫助你預覽顯示效果。當文檔有改動時，甚至還可以自動載入並刷新你的瀏覽器。

運行：

mkdocs serve

2. 文件布局

docs

您的文檔來源應作為常規的Markdown文件編寫（請參見 下面的“使用Markdown編寫”），並將其放置在 document目錄中。默認情況下，此目錄將被命名docs，並將位於mkdocs.yml配置文件旁邊項目的頂層。

您可以創建的最簡單的項目如下所示：

mkdocs.yml
docs/
    index.md

按照約定，應為您的項目主頁命名index.md（有關詳細信息，請參見下面的索引頁面）。以下任何文件擴展名可用於您的Markdown源文件：markdown,mdown,mkdn,mkd,md。無論任何設置如何，文檔目錄中包括的所有Markdown文件都將在內置站點中呈現。

您還可以將Markdown文件包括在嵌套目錄中。

docs/
    index.md
    user-guide/getting-started.md
    user-guide/configuration-options.md
    license.md

3. 索引頁: index.md

默認情況下，請求目錄時，大多數Web服務器將返回index.html該目錄中包含的索引文件（通常名為）（如果存在）。因此，上面所有示例中的首頁都被命名為 index.md，MkDocs將index.html在構建網站時將其呈現到該首頁。

許多資源庫托管站點在瀏覽目錄內容時通過顯示README文件的內容來提供對README文件的特殊處理。因此，MkDocs將允許您將索引頁命名為 README.md而不是index.md。這樣，當用戶瀏覽您的源代碼時，資源庫主機可以顯示該目錄的索引頁，因為它是README文件。但是，當MkDocs渲染您的站點時，該文件將被重命名為，index.html以便服務器將其用作適當的索引文件。

如果在同一目錄中找到一個index.md文件和一個README.md文件，則index.md使用該README.md文件，而忽略該文件。

4. 配置頁面和導航

文件中的 nav 或 pages 定義了全局站點導航菜單中包含的頁面以及該菜單的結構。如果未提供，則將通過發現文檔目錄中的所有Markdown文件來自動創建導航。自動創建的導航配置將始終按文件名的字母數字順序進行排序（除非索引文件始終始終在子部分中列出）。如果您希望導航菜單的排序方式不同，則需要手動定義導航配置。

nav:
    - Home: 'index.md'
    - 'User Guide':
        - 'Writing your docs': 'writing-your-docs.md'
        - 'Styling your docs': 'styling-your-docs.md'
    - About:
        - 'License': 'license.md'
        - 'Release Notes': 'release-notes.md'

5. 主題

homepage

Sets the theme and theme specific configuration of your documentation site. May be either a string or a set of key/value pairs.

If a string, it must be the string name of a known installed theme. For a list of available themes visit styling your docs.

An example set of key/value pairs might look something like this:

theme:
    name: mkdocs
    custom_dir: my_theme_customizations/
    static_templates:
        - sitemap.html
    include_sidebar: false

6. Configuration: 全部配置項

homepage

7. 插件

homepage

7.1. Search

A search plugin is provided by default with MkDocs which uses lunr.js as a search engine. The following config options are available to alter the behavior of the search plugin:

separator默認值: '[\s\-]+'

A regular expression which matches the characters used as word separators when building the index. By default whitespace and the hyphen (-) are used. To add the dot (.) as a word separator you might do this:

plugins:
    - search:
        separator: '[\s\-\.]+'

7.2. mkdocs-localsearch

gihub

注意：此插件僅適用於Material for MkDocs主題（且mkdocs_material版本要求>=5.0）。如果您需要其他主題的支持，請隨時創建請求請求。

7.3. awesome-pages-plugin: 簡化頁面順序配置

github

7.3.1. 安裝

Install the package with pip:

pip install mkdocs-awesome-pages-plugin

Enable the plugin in your mkdocs.yml:

plugins:
    - search
    - awesome-pages

7.3.2. 自定義導航

Create a YAML file named .pages in a directory and use the nav attribute to customize the navigation on that level. List the files and subdirectories in the order that they should appear in the navigation.

nav:
    - subdirectory
    - page1.md
    - page2.md

7.3.3. Rest（剩余頁面）

nav:
    - introduction.md
    - ...
    - summary.md

7.3.4. Titles

nav:
    - ...
    - First page: page1.md

7.3.5. Links

nav:
    - ...
    - Link Title: https://lukasgeiter.com

7.3.6. 修改排序

可單獨在子目錄中創建 .pages 文件並如下配置：

order: desc

7.3.7. 隱藏子目錄

可單獨在子目錄中創建 .pages 文件並如下配置：

hide: true

7.3.8. 設置目錄標題

可單獨在子目錄中創建 .pages 文件並如下配置：

title: Page Title

7.3.9. 折疊子目錄

例如，如果您具有以下文件結構：

文檔/
├─SECTION1 /
│ ├─IMG /
│ │ ├─image1.png
│ │ └─image2.png
│ └─index.md ＃第一節
└─SECTION2 /
  └─index.md ＃第2節

這些頁面將在根目錄中顯示在導航中：

• 第一節
• 第二節

而不是MkDocs默認顯示它們的方式：

• 第一節
  • 指數
• 第二節
  • 指數

配置方式

• For all pages

  Collapsing can be enabled globally using the collapse_single_pages option in mkdocs.yml .

• For a sub-section

  如下配置，將遞歸影響子目錄：

  collapse_single_pages: true
  

• For a single page

  如果要啟用或禁用單個頁面的折疊而不進行遞歸應用設置，在目錄中創建一個名為 .pages 的YAML文件，並將其設置collapse為true或false：

  collapse: true
  

8. 生成靜態頁面

首先生成文檔：

mkdocs build

這將創建一個名為site的新目錄。 看一下該目錄的情況：

$ ls site
about  fonts  index.html  license  search.html
css    img    js          mkdocs   sitemap.xml

請注意，你的源文檔已輸出為兩個名為 index.html 和 about/index.html 的HTML文件。同時各種其他媒體文件也已被復制到site目錄中作為文檔主題的一部分。另外還有一個sitemap.xml文件和mkdocs/search_index.json。

如果你正在使用版本控制軟件，例如git，你可能不希望將生成的文件包含到存儲庫中。只需要在.gitignore文件中添加一行site/即可。

echo "site/" >> .gitignore

如果你正在使用其他版本控制工具，請你自行查閱相關文檔，了解如何忽略特定目錄。

一段時間后，文件可能會從文檔中刪除，但它們仍將駐留在site目錄中。 要刪除那些陳舊的文件，只需在運行mkdocs命令時帶上--clean參數即可。

mkdocs build --clean

9. 部署

剛剛生成的文檔站點僅使用靜態文件，因此你幾乎可以在任何地方托管它。GitHub project pages 和 Amazon S3 是個很不錯的托管地方，具體取決於你的需求。將整個site目錄的內容上傳到你托管網站的地方，然后就完成了。