使用 MkDocs 快速搭建文档系统

MkDocs 是快速，简单和华丽的静态网站生成器，可以构建项目文档。文档源文件在 Markdown 编写，使用单个 YAML 配置文件配置。

MkDocs 基于 python，但只需编写 Markdown 就可构建最简单的文档页面

安装

使用 pip 安装 MkDocs

代码语言：javascript复制

pip install mkdocs-material

创建项目

使用如下指令创建一个名为 name 的项目

代码语言：javascript复制

mkdocs new name

生成的项目结构

代码语言：javascript复制

1
2
3
4
name
├─ docs/
│  └─ index.md
└─ mkdocs.yml
 复制

配置项目属性

找到项目中的mkdocs.yml，根据官方文档进行合适的配置

这是我使用的配置，可供参考

代码语言：javascript复制

site_name: XXX 使用文档
theme:
  name: material
  language: zh
  # 网站左上角显示的logo
  logo: images/logo.jpg
  # 网站图标
  favicon: images/favicon.ico
  features:
    - navigation.instant
    - navigation.tabs
    - navigation.sections
    - navigation.expand
    - navigation.top
  palette:
    - media: "(prefers-color-scheme: light)"
      scheme: default
      primary: indigo
      accent: red
      toggle:
        icon: material/toggle-switch-off-outline
        name: Switch to dark mode
    # 深色模式
    - media: "(prefers-color-scheme: dark)"
      scheme: slate
      primary: deep orange
      accent: red
      toggle:
        icon: material/toggle-switch
        name: Switch to light mode
extra_css:
  - stylesheets/extra.css
markdown_extensions:
  - attr_list
copyright: Copyright © 2021 XXX
extra:
  # 右下角的超链接
  social:
    - icon: fontawesome/brands/github
      link: #
      name: github
 复制

编写 Markdown 并构建网页

编写前可以创建一个实时预览的服务器

代码语言：javascript复制

mkdocs serve

在docs/中创建的md文件将会实时同步到预览服务器 完成编辑后使用

代码语言：javascript复制

mkdocs build

即可生成静态网页文件，可以部署到github pages或者你的个人服务器上

markdown

0 人点赞