安装python和pip以及mkdocs-material

摘要: MkDocs 已停止更新,Zensical 是官方推荐的新一代;安装python和pip以及mkdocs-material


安装python和pip

写在前面

MkDocs 已停止更新,Zensical 是官方推荐的新一代

Zensical 中文教程: https://wcowin.work/Zensical-Chinese-Tutorial/

安装绿色版python

下载绿色安装包Windows embeddable package (64-bit)

https://www.python.org/ftp/python/3.13.5/python-3.13.5-embed-amd64.zip

解压缩到D:\dev_software\python-3.13.5-embed-amd64

没有git则安装git https://git-scm.com/

添加环境变量

win11->系统->系统信息->高级系统设置->环境变量

系统变量里找到path->编辑->编辑文本

检查末尾是否有;没有则添加

在末尾添加D:\dev_software\python-3.13.5-embed-amd64

检查是否安装成功

需要重新打开git base

在任意目录右键-> open git base here

1
python --version

正确输出版本号则安装成功

安装pip

下载安装脚本https://bootstrap.pypa.io/get-pip.py

复制下载的脚本get-pip.py到D:\dev_software\python-3.13.5-embed-amd64

打开D:\dev_software\python-3.13.5-embed-amd64目录

右键-> open git base here

输入命令

1
python get-pip.py

等待安装成功

之后编辑这个目录下的python313._pth文件

将#import site改为import site (去掉#注释)

添加环境变量

将D:\dev_software\python-3.13.5-embed-amd64\Scripts也添加到环境变量中和上边一样

检查

需要重新打开git base

1
2
3
4
pip --version

更新pip
python -m pip install --upgrade pip

输出版本号则安装成功

安装mkdocs

安装mkdocs和插件

1
2
pip install mkdocs
pip install --upgrade setuptools

安装mkdocs-material主题和插件

1
2
3
pip install mkdocs-material
pip install mkdocs-minify-plugin
pip install mkdocs-rss-plugin

创建mkdocs

1
2
3
在任意目录
mkdocs new my-project

更换主题

1
2
3
将以下行添加到 mkdocs.yml
theme:
name: material

目录

1
docs\blog\posts   博客目录

开发启动

1
mkdocs serve

打开http://127.0.0.1:8000/

部署到cloudflare

根目录添加文件requirements.txt文件内容如下

1
2
3
4
5
6
7
8
9
10
11
12
13
# vercel
setuptools
mkdocs
mkdocs-minify-plugin
cairosvg
mkdocs-blog-plugin
mkdocs-rss-plugin
mkdocs-material
mkdocs-material[imaging]
python-markdown-math
fontawesome_markdown
mdx_unimoji
pymdown-extensions

构建命令和输出目录

1
2
mkdocs build -d public
输出目录public

Mkdocs-Wcowin搭建

https://github.com/Wcowin/Mkdocs-Wcowin

安装环境

1
2
3
4
5
6
7
8
9
10
安装插件
pip install mkdocs-git-committers-plugin-2
pip install mkdocs-git-revision-date-localized-plugin
pip install mkdocs-rss-plugin
AI插件ai-summary
pip install mkdocs-ai-summary-wcowin -i https://pypi.org/simple
pip install --upgrade mkdocs-ai-summary-wcowin -i https://pypi.org/simple

本地启动
mkdocs serve

部署

Mkdocs-Wcowin是通过github action自动部署到gh-pages分支

在Cloudflare pages 或者Vercel等平台则直接使用纯静态的gh-pages分支即可 无需构建 直接部署

建议通过这种方式部署 兼容性好!!!

配置

调整mkdocs.yml下的配置

调整网站字体

参考https://wcowin.work/Mkdocs-Wcowin/blog/websitebeauty/mkdocsfont/#mkdocs

1
2
3
4
5
6
@import url('https://static.zeoseven.com/zsft/292/main/result.css');

body {
font-family: "Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'", monospace, Arial, sans-serif;
font-weight: normal;/* lighter*/
}

记得去掉配置中的这个css

1
https://cdn.jsdelivr.net/gh/Wcowin/Mkdocs-Wcowin@main/docs/stylesheets/ziti.css

评论系统giscus参数调整

https://wcowin.work/Mkdocs-Wcowin/blog/websitebeauty/mkcomments.html

\docs\overrides\partials\comments.html

将文件里的参数改为自己的参数即可

mkdocs.yml配置文件有docs/overrides/hooks/comments.py 可以注释掉 互相影响

1
2
3
4
5
6
7
如何禁用
comments: false ----一般用这个
或者
comment:
enable: false
或者
comment: false

其他插件

1
2
3
4
pip install mkdocs-authors-plugin
pip install mkdocs-gen-files
pip install pypinyin
pip install pyyaml