MkDocs - 安装，配置

版本

MkDocs 1.6.1 / mkdocs-material 9.7.6

mkdocs-material 不建议使用 MkDocs 2.x，因此安装了稳定的 1.x 版本。
官方文档：https://squidfunk.github.io/mkdocs-material/getting-started/

安装

终端使用 Git Bash。

python -m venv venv
source venv/Scripts/activate
pip install mkdocs==1.6.1 mkdocs-material

常用命令

mkdocs new .          # 将当前目录设为文档目录
mkdocs serve          # 启动本地服务 http://127.0.0.1:8000
mkdocs build          # 编译静态文件
mkdocs build --clean  # 编译并清除旧文件

配置（mkdocs.yml）

site_name: 蓝天白云
site_dir: /var/www/myblog
theme:
  name: material
  language: zh
  font:
    text: Noto Sans SC
    code: JetBrains Mono
  palette:
    - scheme: default
      toggle:
        icon: material/brightness-7
    - scheme: slate
      toggle:
        icon: material/brightness-4
  features:
    - navigation.top
    - search.suggest
    - content.code.copy
plugins:
  - search
  - tags
markdown_extensions:
  - nl2br
  - admonition
  - pymdownx.superfences
  - pymdownx.highlight:
      anchor_linenums: true
  - toc:
      permalink: true

VSCode 配置

图片粘贴路径及预览换行设置（截图粘贴后图片保存至 ./assets/ 目录）：

"markdown.copyFiles.destination": {
    "**/*": "${documentDirName}/assets/img-${unixTime}.${fileExtName}"
},
"markdown.preview.breaks": true

markdown.preview.breaks 与 nl2br 扩展对应，使普通换行在 VSCode 预览和网页中均按换行显示。

服务器部署

服务器需安装 Git 和 Python。

首次部署：

pip install mkdocs==1.6.1 mkdocs-material
git clone https://github.com/yongirl320/mkdocs
cd mkdocs
mkdocs build
chown -R www-data:www-data /var/www/myblog

Nginx 配置：

server {
    listen 80;
    server_name docs.myserver.com;
    root /var/www/myblog;
    index index.html;
    location / {
        try_files $uri $uri/ =404;
    }
}

更新部署脚本（deploy.sh）：

#!/bin/bash
cd /root/mkdocs
git pull origin master
mkdocs build --clean
chown -R www-data:www-data /var/www/myblog
echo "deploy ok"