【详细】使用MkDocs搭建个人博客网站

使用MkDocs搭建个人博客网站

0. 安装python3.7

注意：可以在个人用户下安装，不要覆盖系统原有python

#下载Python依赖环境
yum install gcc patch libffi-devel python-devel zlib-devel bzip2-devel openssl-devel ncurses-devel sqlite-devel readline-devel tk-devel gdbm-devel db4-devel libpcap-devel xz-devel -y

#没有wget需要安装
yum install wget -y   

#下载安装包
wget https://www.python.org/ftp/python/3.7.13/Python-3.7.13.tgz

#解压
tar -zxvf Python-3.7.13.tgz

#编译安装
cd Python-3.7.13
./configure --prefix=/home/mkdocs/python3
make && make install

#配置环境变量
vi ~/.bash_profile 
#添加此配置
PATH=$PATH:/home/mkdocs/python3/bin

source ~/.bash_profile

#软连接
sudo ln -sf /home/mkdocs/python3/bin/python3.7 /usr/bin/python3
sudo ln -sf  /home/mkdocs/python3/bin/pip3.7 /usr/bin/pip3

#验证
python3 --version
pip3 --version


1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33

1. 安装mkdocs

1、确保已经安装python3环境，以及Python包管理器pip

2、 安装 MkDocs

pip3 install mkdocs
1

3、创建文档项目，docs 是自定义文件目录

mkdocs new docs
1

4、切换到 mysite 目录下，并运行

mkdocs serve -a ip:port
1

浏览器输入 ip:port就预览到我们建设的文档站点了

2. 安装插件

安装主题插件：

pip3 install mkdocs-material -i https://pypi.tuna.tsinghua.edu.cn/simple

1
2

安装版本管理插件：

pip3 install mike
1

安装生成pdf插件：

pip3 install mkdocs-with-pdf
1

安装qrcode：

pip3 install qrcode
1

安装weasyprint，版本需要指定52.5：

pip3 install weasyprint==52.5
1

3. 配置

配置mkdocs.yml

#站点配置说明
site_name: Docs #站点名称
docs_dir: docs #文档地址
#主题配置
theme:
  name: material #指定主题
  custom_dir: overrides #定制目录，同名覆盖
  palette: #颜色配置
    primary: indigo #主题颜色
    accent: deep orange #强调文字颜色
  language: zh #语言
  features:
    - navigation.top #tab页展示方式 顶部 
    - header.autohide #表头自动隐藏

#版本控制
extra: 
  version:            
    provider: mike

#with-pdf配置说明：
plugins:
  - search #添加搜索框
  - with-pdf: #生成pdf配置
      copyright: copyright @ 2022#设置作者文本
      cover_subtitle: v1.1.0 #子标题
      author: author #作者
      cover: true #封面
      back_cover: true #底面
      output_path: pdf/文件名称.pdf #输出路径
      

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32

4. 开发

1、把创建好的文档项目，提交到git远程仓库

2、在windows端，拉取git文档项目到本地，通过idea打开，选定一个分支，在docs目录下，添加md文档，进行编写文档即可

4、编写完成，提交到git远程，linux端拉取文档

5、linux端拉取到最新文档， 执行命令

mkdocs build
mike deploy [version]
mkdocs serve -a ip:port
1
2
3

6、浏览器访问ip:port，即可看到最新页面

5.项目放到Nginx中

1、复制site文件夹到Nginx

2、进行Nginx相关配置

3、访问网站

附录：

mkdocs中文文档：

https://mkdocs.zimoapps.com/#_14

插件商店可参考：

https://github.com/mkdocs/mkdocs/wiki/MkDocs-Plugins#pdf–site-conversion

mike配置可参考：

https://github.com/jimporter/mike/tree/v1.1.2

theme配置可参考：

https://squidfunk.github.io/mkdocs-material/setup/changing-the-colors/

with-pdf配置：

https://github.com/orzih/mkdocs-with-pdf