安装和配置 Material for MkDocs

安装

以下内容基于 Ubuntu 24.04 完成。

我们将通过创建一个 Python 虚拟环境以安装 Material for MkDocs。

sudo apt -y install python3 python3-full python3-pip python3.12-venv

python3 -m venv <path> # (1)

<path>/pip install --upgrade pip setuptools

<path>/pip install mkdocs-material

1. 本文所有命令中的 <path> 请替换为 MkDocs 安装目录的绝对路径。

这将自动安装所有依赖项的兼容版本： MkDocs、Markdown、Pygments 和 Python Markdown 扩展。

配置

新建站点

安装 Material for MkDocs 后，就可以使用 mkdocs 命令新建站点。

切换到你希望项目所在的目录，然后输入：

<path>/mkdocs new .

配置站点

在 mkdocs.yml 中修改你的站点配置。

下面提供我的配置文件，供大家参考：

mkdocs.yml

site_name: "Cat Tom's Blog" # 站点名称
site_url: https://blog.cattom.site # 站点链接
site_author: Cat Tom # 作者
# 代码仓库信息
repo_name: cattom/blog
repo_url: http://cattomserver3-1.tail184fc.ts.net:84/cattom/blog.git
# 版权信息
copyright: Copyright © 2024 | Cat Tom

theme:
  name: material
  language: zh
  logo: https://static.cattom.site/image/icon/40.png
  favicon: https://static.cattom.site/image/icon/favicon-32x32.png
  features:
    - navigation.tabs
    - navigation.instant
    - navigation.instant.prefetch
    - navigation.tracking
    - navigation.top
    - navigation.indexes
    - search.suggest
    - search.highlight
    - content.code.copy
    - content.code.annotate
    - content.tabs.link
  palette:
    primary: blue grey
    accent: light blue

markdown_extensions:
  # Python Markdown
  - abbr
  - tables
  - admonition
  - attr_list
  - def_list
  - footnotes
  - md_in_html
  - toc:
      permalink: true
  # Python Markdown Extensions
  - pymdownx.critic
  - pymdownx.arithmatex:
      generic: true
  - pymdownx.betterem:
      smart_enable: all
  - pymdownx.caret
  - pymdownx.details
  - pymdownx.emoji:
      emoji_index: !!python/name:material.extensions.emoji.twemoji
      emoji_generator: !!python/name:material.extensions.emoji.to_svg
  - pymdownx.highlight: 
      anchor_linenums: true
      line_spans: __span
      pygments_lang_class: true
  - pymdownx.inlinehilite
  - pymdownx.keys
  - pymdownx.mark
  - pymdownx.smartsymbols
  - pymdownx.superfences: 
      custom_fences:
        - name: mermaid
          class: mermaid
          format: !!python/name:pymdownx.superfences.fence_code_format
  - pymdownx.snippets
  - pymdownx.tabbed:
      alternate_style: true
  - pymdownx.tasklist:
      custom_checkbox: true
  - pymdownx.tilde

nav:
  - "主页": index.md
  - "生活": 
      - life/index.md
      - "原发免疫性血小板减少症 (ITP)": life/ITP.md
  - "技术": 
      - tech/index.md
      - "Mi 6 (sagit)": tech/Mi6(sagit).md
      - "极1S (HC5661)": tech/HC5661.md
      - "Git: 覆盖本地修改": tech/Git-overwriting-local-changes.md
      - "Redmi 4X (santoni)": tech/Redmi4X(santoni).md
      - "手把手教你备份和还原 Docker 卷": tech/Backup-and-Restore-of-Docker-Volumes-A-Step-by-Step-Guide.md
      - "在 Ubuntu 24.04 上添加交换空间": tech/How-to-Add-Swap-Space-on-Ubuntu-2404.md
      - "Docker Compose: 限制容器的资源使用": tech/Docker-Compose-Limiting-container-resource-usage.md
      - "创建和管理 Linux 服务器用于身份验证的 SSH 密钥": tech/Creating-and-Managing-SSH-Keys-for-Authentication-on-Linux-Servers.md
      - "将已经失效的 Onedrive 账户从资源管理器边侧栏去除": tech/Remove-deactivated-Onedrive-accounts-from-Explorer-sidebar.md
  - "MkDocs 参考": examples/index.md

plugins:
  - search
  - glightbox

生成静态网页

编辑完成后，您可以使用 Markdown 文件构建静态网站：

<path>/mkdocs build

这将会在你的项目目录中生成 site 文件夹，里面包含了站点的所有静态文件。

你可以将 site 文件夹上传至云服务器或者 S3 存储以向公开你的站点。当然，你也可以参考官方文档，利用 Github Pages 托管你的网站。