使用 MkDocs 快速搭建文档系统

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

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

安装

使用 pip 安装 MkDocs

pip install mkdocs-material

创建项目

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

mkdocs new name

生成的项目结构

name
├─ docs/
│  └─ index.md
└─ mkdocs.yml

配置项目属性

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

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

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 并构建网页

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

mkdocs serve

docs/中创建的md文件将会实时同步到预览服务器

完成编辑后使用

mkdocs build

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

 

例:https://docs.bluesdawn.top/BDbot/

官方文档:https://squidfunk.github.io/mkdocs-material/

点赞
  1. avatar 纯之说道:
    Google Chrome Android 10

    咕咕咕?终于更新辣! :taikaixin: 这个东西确实挺方便的 :huaji14:

    1. avatar BluesDawn说道:
      Google Chrome Windows 10

      确实 :huaji9:

  2. avatar Yusorai说道:
    Google Chrome Windows 10

    看起来挺不错的亚子,不过好像暂且没有写文档的需求哈哈哈

发表评论

电子邮件地址不会被公开。必填项已用 * 标注