MkDocs 部署安裝教程

MkDocs 簡介

MkDocs 是一個基于 Python 的 Markdown 的靜態網站生成工具，常用于快速搭建項目文檔網站。
它界面簡潔大方，配置簡單，生成速度快，特別適合技術手冊、內部知識庫等場景，并可部署到 Github Pages，因此深受開發者喜愛。
MkDocs 使用 Python-Markdown 庫將 Markdown 文檔渲染為 HTML。
MkDocs 中文官網：mkdocs.org.cn
接下來，筆者將在 Ubuntu 24.04 LTS 上搭建 MkDocs。

本博客已假定讀者了解 Markdown，并會使用 Python 包管理器 pip、虛擬環境管理器 venv ，Linux 基礎命令，以及 yml 格式配置文件的編寫。若不了解，請自行 Google，本博客不會講解其他內容的原理。

MkDocs 部署

基礎環境安裝

MkDocs 建議 Python>=3.9，使用python3 --version查看 Python 版本。

創建項目文件夾

創建 MkDocs 項目根目錄并進入：

mkdir mkdocs && cd mkdocs

創建虛擬環境(推薦)

這一步是極其推薦的，確保不污染全局 Python 環境。

python3 -m venv venv
source venv/bin/activate

每次運行時都需使用 source venv/bin/activate 加載此虛擬環境。

安裝 MkDocs

MkDocs 本體及其大多數擴展都是以 Python 庫形式發布的，使用 pip 安裝即可：

pip install mkdocs

初始化文檔項目

在根目錄下初始化 MkDocs 項目：

mkdocs new .

這時會生成一個 mkdocs.yml 配置文件和 docs/ 文件夾，MkDocs 的目錄結構如下：

mkdocs/
├── mkdocs.yml        # 配置文件
└── docs/             # 默認文檔目錄
    └── index.md      # 首頁文檔

其中 docs 目錄為默認文檔目錄，其可通過配置文件的 docs_dir 選項調整。

初步運行

MkDocs 內置了一個支持熱重載的開發服務器，在項目根目錄下使用以下命令啟動服務器：

mkdocs serve

此時服務器開始嘗試啟動，并在控制臺輸出啟動日志，若出錯則會顯示錯誤原因。請注意日志中 Serving on: 一行，其指定了服務器 IP 及監聽的端口號，通常為 http://127.0.0.1:8000，訪問此 URL 即可查看網站。

注：若在 mkdocs.yml 中設置的 site_url 的首頁目錄不為根目錄，則首頁目錄將被覆蓋。

在這里插入圖片描述
至此，已成功在本地運行起了一個最小可用版的MkDocs。

配置文件：mkdocs.yml (核心步驟)

MkDocs 所有配置均通過此文件調整。

設置站點標題

在 mkdocs.yml 中編寫：

site_name: Blogs

配置文件中的 site_name 是必選項。

設置站點圖標

在 docs 目錄下創建子目錄 img，并將 favicon.ico 放置在 img 目錄下。

添加頁面

MkDocs 默認將 docs 下所有的 .md 文件加入到網站頁面中，因此無需手動添加。
網站首頁即為 index.md，URL 為根目錄 /，其他文件的 URL 即為該文件的相對路徑位置。

注意：不推薦使用中文命名的文件，這會導致 URL 中出現中文，這是不推薦的做法，在SEO中將使搜索引擎難以解析。

頁面默認標題為 .md 文件中的首個一級標題。

設置導航欄菜單

方法是在 mkdocs.yml 中編寫 nav 配置，網站菜單將按此配置定義的順序排布。注意所用到的文件均為相對于 docs 的路徑。

nav:
  - index.md
  - about.md

注：

以 . 開頭的文件將被 MkDocs 所忽略。

nav 配置僅決定菜單順序，而不決定文件的 URL。URL 始終為該文件相對于 docs 的路徑。

頁面默認標題為 .md 文件中的首個一級標題，也可手動指定頁面標題，方法為標題: 文件：

標題編寫規范：一般地，頁面應該有且僅有一個語義明確的一級標題，用來表示頁面主題。其余標題作為主標題下的小節，應從二級標題開始。

nav:
  - 首頁: index.md
  - 關于: about.md

也可設置多級菜單：

nav:
  - 首頁: index.md        # 一級菜單
  - 政策:                 # 二級菜單
  		- 關于: about.md
  		- 用戶支持:          # 三級菜單
  			- 手冊: guide.md
  			- 聯系: contact.md

主題

Mkdocs支持若干主題，其包含兩個內置主題 mkdocs(默認主題) 和 readthedocs，也支持其他若干第三方主題。切換主題方法是在 mkdocs.yml 中添加 theme 配置，如：

theme: readthedocs

在這里插入圖片描述
本文將使用第三方主題 material，它是排名第一的第三方主題，被大量廣泛使用。在終端執行如下命令安裝：

pip install mkdocs-material

添加至 mkdocs.yml：

theme: material

在這里插入圖片描述

完整配置文件(可照搬)

以下即為博主本人站點的完整配置，開啟了大多數特性及功能，可參考并合理修改。

site_name: 椰蘿Yerosius的博客
site_description: 椰蘿Yerosius，主修計算機科學，主要記錄技術文檔、隨筆、感悟等。
site_url: https://yerosius.github.io/blogs
site_author: 椰蘿Yerosius
strict: false

repo_name: 'Yerosius/blogs'
repo_url: 'https://github.com/Yerosius/blogs'
edit_uri: edit/main/docs/

copyright: Copyright &copy; 2025 椰蘿Yerosius All Rights Reserved. <br/> 版權所有，轉載需獲得許可，附加條款亦可能應用。本站全部內容禁止商業使用。

theme:
  name: material
  language: zh
  custom_dir: docs/overrides
  logo: assets/logo.png
  favicon: assets/images/favicon.ico
  icon: 
    repo: fontawesome/brands/github
  repo_stats: true

  include_search_page: false
  search_index_only: true

  font: 
    code: 'Fira Mono'

  palette:
    - media: "(prefers-color-scheme)"
      toggle:
        icon: material/brightness-auto
        name: 切換日間
    - media: "(prefers-color-scheme: light)"
      scheme: default
      primary: white
      accent: red
      toggle:
        icon: material/weather-sunny
        name: 切換夜間
    - media: "(prefers-color-scheme: dark)"
      scheme: slate
      primary: black
      accent: teal
      toggle:
        icon: material/weather-night
        name: 跟隨系統

  features:
    - announce.dismiss
    - content.action
    - content.action.edit
    - content.action.view
    - content.code.annotate
    - content.code.select
    - content.code.copy
    - content.tooltips
    - content.footnote.tooltips
    - navigation.footer
    - navigation.indexes
    - navigation.instant
    - navigation.instant.prefetch
    - navigation.instant.progress
    - navigation.prune
    - navigation.tracking
    - navigation.tabs
    - navigation.top
    - navigation.back_to_top
    - navigation.sections
    - navigation.path
    - search.suggest
    - search.highlight
    - search.share
    - content.tabs.link
    - toc.follow

markdown_extensions:
  - abbr
  - admonition
  - attr_list
  - def_list
  - footnotes
  - md_in_html
  - meta
  - toc:
      permalink: true
  - tables
  - pymdownx.arithmatex:
      generic: true
  - pymdownx.caret
  - pymdownx.critic
  - pymdownx.details
  - pymdownx.emoji:
      emoji_index: !!python/name:material.extensions.emoji.twemoji
      emoji_generator: !!python/name:material.extensions.emoji.to_svg
  - pymdownx.inlinehilite
  - pymdownx.keys
  - pymdownx.magiclink:
      normalize_issue_symbols: true
      repo_url_shorthand: true
      user: squidfunk
      repo: mkdocs-material
  - pymdownx.mark
  - pymdownx.smartsymbols
  - pymdownx.snippets:
      auto_append:
        - includes/mkdocs.md
  - pymdownx.superfences:
      custom_fences:
        - name: mermaid
          class: mermaid
          format: !!python/name:pymdownx.superfences.fence_code_format
        - name: math
          class: arithmatex
          format: !!python/name:pymdownx.arithmatex.fence_mathjax_format
  - pymdownx.tabbed:
      alternate_style: true
      combine_header_slug: true
      slugify: !!python/object/apply:pymdownx.slugs.slugify
        kwds:
          case: lower
  - pymdownx.tasklist:
      custom_checkbox: true
  - pymdownx.tilde 
  - pymdownx.highlight:
      linenums: true
      anchor_linenums: true
      line_spans: __span
      pygments_lang_class: true

plugins:
  - git-revision-date-localized:
      type: datetime
      fallback_to_build_date: true
      enable_creation_date: true
      timezone: Asia/Shanghai
  - tags
  - search:
      lang:
        - en
        - zh
      separator: '[\s\u200b\-]'
  - mermaid2
  - glightbox
  - minify:
      minify_html: true
  - awesome-pages
  - toggle-sidebar: 
      theme: material
      toggle_button: all
  - git-authors
  - git-committers:
      repository: yerosius/blogs
      branch: main
  - offline
  - encryptcontent:
      search_index: 'dynamically'
      title_prefix: "[加密]"
      summary: "?? 加密內容"
      placeholder: "請輸入密碼(按回車提交)"
      password_button_text: "提交"
      decryption_failure_message: "密碼錯誤"
      encryption_info_message: "本頁內容已加密，請輸入密碼后解鎖。若需申請訪問，請使用郵件聯系管理員。"

extra:
  comments:
    enabled: true
  consent:
    title: 隱私提示
    description: >- 
      本站使用 Google Analytics 收集和分析用戶訪問數據，以幫助我們優化網站內容和服務。Google Analytics 可能會收集您的 IP 地址、設備信息、瀏覽器類型、訪問時間及訪問頁面等非個人身份信息。我們不會將收集到的數據與您的個人身份信息進行關聯。繼續使用本網站即表示您同意 Google Analytics 的數據收集與使用。
  status:
    new: 新內容
    deprecated: 已棄用
    draft: 草稿
  pagetime: 'on'
  githash: ''
  analytics:
    provider: google
    property: G-Y227H1980C

extra_javascript:
  - https://polyfill.io/v3/polyfill.min.js?features=es6
  - https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js

extra_css:
  - stylesheets/extra.css

site_dir: site

posted @ 2025-10-18 18:19 椰蘿Yerosius 閱讀(19) 評論(0) 收藏舉報

刷新頁面返回頂部

椰蘿Yerosius的博客