MkDocs

简介

MkDocs 是一个简单且快速的静态网站生成器，专门用于项目文档。它使用Markdown文件作为内容源，基于Python构建，易于配置和使用。

主要特性

• 易于安装和使用：通过Python包管理器安装，配置简单。
• 主题支持：提供多种主题，支持自定义。
• 自动生成导航：根据Markdown文件自动生成站点导航。
• 内置开发服务器：实时预览文档修改。
• 插件扩展：支持插件机制，增加额外功能。

安装

创建Python虚拟环境

更新包列表
sudo apt update安装python环境
sudo apt install python3 python3-pip python3-venv -ypython虚拟环境
python3 -m venv .python-venv/激活python虚拟环境
source .python-venv/bin/activate更新虚拟环境的 pip
.python-venv/bin/pip install --upgrade pip

squidfunk版本

squidfunk 的网站

pip（先创建Python虚拟环境）

pip install mkdocs-material

Docker

git clone https://github.com/squidfunk/mkdocs-material.git
pip install -e mkdocs-material

Github

docker pull squidfunk/mkdocs-material

!!! info "适用 Debian/Ubuntu 系统"

‍

官方版本

MkDocs、插件、主题

pip install mkdocs -U
pip install "mkdocstrings[python]" -U
pip install mkdocs-material -U

‍

验证安装

mkdocs --version

配置示例

在mkdocs.yml​文件中添加基本配置：

site_name: My Docstheme:name: material

目录结构示例

my-project/mkdocs.yml    # 配置文件docs/index.md  # 首页内容guide.md  # 指南内容

‍

---

以下网站使用MkDocs构建

教程

• Material for MkDocs (squidfunk.github.io)
• Material for MkDocs - Material for MkDocs 中文文档 (llango.com)
• Material for MkDocs 的美化 - Charles Le's Notebook (charleschile.com)
• mkdocs 文档生成,Python自文档快速入门 - 271374667 - 博客园 (cnblogs.com)

排版

• Documentation - Home Assistant (home-assistant.io)

• Godot Docs – master branch — Godot Engine (latest) documentation in English

• 未央学习 (weyoung-learn.github.io)

• Python Packaging User Guide

• Packaging Python Projects - Python Packaging User Guide

• Introduction - OpenFaaS

• Debezium Documentation

---

可以从这些网站学习的排版。这几天看过了搜到的所有教程，我推荐您只看Material for MkDocs (squidfunk.github.io)和 视频参考 就够了。

‍

‍