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

注：

1. 以 . 开头的文件将被 MkDocs 所忽略。
2. 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