安装和配置 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>/bin/pip install --upgrade pip setuptools

<path>/bin/pip install mkdocs-material

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

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

配置

新建站点

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

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

<path>/mkdocs new .

配置站点

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

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

site_name: "Cat Tom's Blog" # 站点名称
site_url: https://blog.cattom.site # 站点链接
site_author: Cat Tom # 作者
# 版权信息
copyright: Copyright &copy; 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
  - "MkDocs 参考": examples/index.md

plugins:
  - search
  - glightbox

生成静态网页

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

<path>/mkdocs build

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

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

3.3 KiB Raw Blame History

安装和配置 Material for MkDocs

安装

配置

新建站点

配置站点

生成静态网页

3.3 KiB

Raw Blame History