跳转至

MkDocs搭建静态站点

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

MkDocs 中文文档 (markdown-docs-zh.readthedocs.io)

参考视频：Python版宝藏级静态站点生成器Material for MkDocs

1.安装Mkdocs

1.首先下载python，安装完成后在cmd输入python，如果出现下面字样，说明python安装成功

D:\>python
Python 3.11.1 (tags/v3.11.1:a7a450f, Dec  6 2022, 19:58:39) [MSC v.1934 64 bit (AMD64)] on win32
Type "help", "copyright", "credits" or "license" for more information.
>>>

2.下载mkdocs，命令为pip install mkdocs，使用命令mkdocs -V来看是否下载成功

PS C:\Users\李\OneDrive\桌面\mywiki> mkdocs -V
mkdocs, version 1.4.2 from D:\apps\python3.11.1\Lib\site-packages\mkdocs (Python 3.11)

3.切换到你的某个目录下，使用命令mkdocs new <创建的目录名>，创建站点目录

C:\Users\李\OneDrive\桌面>mkdocs new mywiki
INFO     -  Creating project directory: mywiki
INFO     -  Writing config file: mywiki\mkdocs.yml
INFO     -  Writing initial docs: mywiki\docs\index.md

目录结构为：

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

4.进入你的站点目录，并使用命令mkdocs serve，在本地端口运行网站

C:\Users\李\OneDrive\桌面>cd mywiki
C:\Users\李\OneDrive\桌面\mywiki>mkdocs serve
INFO     -  Building documentation...
INFO     -  Cleaning site directory
INFO     -  Documentation built in 0.36 seconds
INFO     -  [21:50:48] Watching paths for changes: 'docs', 'mkdocs.yml'
INFO     -  [21:50:48] Serving on http://127.0.0.1:8000/

5.访问端口http://127.0.0.1:8000/，原始页面如下：

image-20230113215258232

2.页面布局&主题更换

1.初始主题比较简陋，安装新主题：pip install mkdocs-material

2.主题配置需要在文件mkdocs.yml添加

site_name: My Docs

theme: # 添加主题
  name: material

image-20230113222401526

其他布局和主题参考官方文档：https://squidfunk.github.io/mkdocs-material/getting-started/

3.部署到github

1.首先在站点目录下使用git初始化目录

PS C:\Users\李\OneDrive\桌面\mywiki> git init
Initialized empty Git repository in C:/Users/李/OneDrive/桌面/mywiki/.git/

2.把所有目录下的文件提交到git暂存区并提交

PS C:\Users\李\OneDrive\桌面\mywiki> git add .
PS C:\Users\李\OneDrive\桌面\mywiki> git commit -m "update"
[master (root-commit) f9a5a66] update
 2 files changed, 21 insertions(+)
 create mode 100644 docs/index.md
 create mode 100644 mkdocs.yml

3.将提交推送到远程仓库

我这里在github中新建一个仓库

（1）给远程仓库添加别名git remote add origin <你的仓库地址>

PS C:\Users\李\OneDrive\桌面\mywiki> git remote add origin git@github.com:liyuelian/docs-wiki.git
PS C:\Users\李\OneDrive\桌面\mywiki> git remote -v
origin  git@github.com:liyuelian/docs-wiki.git (fetch)
origin  git@github.com:liyuelian/docs-wiki.git (push)

（2）推送到远程仓库：git push -u origin master

PS C:\Users\李\OneDrive\桌面\mywiki> git push -u origin master
Enumerating objects: 5, done.
Counting objects: 100% (5/5), done.
Delta compression using up to 8 threads
Compressing objects: 100% (4/4), done.
Writing objects: 100% (5/5), 644 bytes | 214.00 KiB/s, done.
Total 5 (delta 0), reused 0 (delta 0), pack-reused 0
To github.com:liyuelian/docs-wiki.git
 * [new branch]      master -> master
branch 'master' set up to track 'origin/master'.

4.在本地的站点目录下进行部署：mkdocs gh-deploy

PS C:\Users\李\OneDrive\桌面\mywiki> mkdocs gh-deploy
INFO     -  Cleaning site directory
INFO     -  Building documentation to directory: C:\Users\李\OneDrive\桌面\mywiki\site
INFO     -  Documentation built in 0.41 seconds
...
INFO     -  Your documentation should shortly be available at: https://liyuelian.github.io/docs-wiki/

5.上述最后显示的网址https://<你的用户名>.github.io/<你的仓库名>/就是你生成的网站url

如果你已经创建了https://<你的用户名>.github.io仓库，则有可能产生冲突，因为两者的url路径有重复字段