mkdocs

创建个人网站（github pages）并将站点一键托管到Github

亮点：个人网站一键部署，简易文档直接渲染成网页挂载全流程
使用工具：mkdocs和git命令

mkdocs介绍

MkDocs is a fast, simple and downright gorgeous static site generator that’s geared towards building project documentation. Documentation source files are written in Markdown, and configured with a single YAML configuration file.

MkDocs是一个快速的、简单的、优美的静态站点生成器，主要用于构建项目文档。文档源文件采用Markdown格式，配置文件采用一个YAML格式文件。

mkdocs安装

安装mkdocs前需要安装python环境。mkdocs要求python版本为：python 3.5、python 3.6 、python 3.7和python 3.8。

安装mkdocs非常简单，只需要在控制台运行如下命令即可：

1	pip install mkdocs

查看mkdocs是否安装成功，只需要运行如下命令：

1	mkdocs --version

如果提示不能运行mkdocs命令，简单的解决方法只需要在命令前加上python -m，即：

1	python -m mkdocs --version

永久的解决方法是将python安装目录下的Scripts加入环境变量Path中。

mkdocs创建站点

我们只需要运行如下命令，就可以创建一个站点：

1	mkdocs new my_wiki(你喜欢的目录名)

这个命令会在当前目录下创建一个目录（my_wiki）

然后进入我们创建的目录

1	cd my_wiki

运行如下命令，即可在本地访问站点：

1	mkdocs serve

在浏览器输入地址http://127.0.0.1:8000，页面如下：

在运行站点的同时，我们可以实时修改站点信息，mkdocs会更新并展示在浏览器上，方便我们预览。

我们可以修改mkdocs.yml文件中的站点名site_name：

1	site_name: 我的第一个站点

部署站点

首先来认识一个命令:

1	mkdocs build

这个命令会在learn-mkdocs目录下生成一个目录site，这个目录中包含了静态站点的页面内容。

我们可以在GitHub中创建一个仓库

然后在目录下打开git，并将当前目录设置为一个仓库，然后与GitHub新创建的仓库连接：

1 2	git init git remote add origin 仓库地址

然后在目录下打开控制台，执行以下命令：

1	mkdocs gh-deploy

这个命令会在GitHub项目上创建一个gh-pages分支，并执行mkdocs build命令，然后将当前目录中的site目录下的内容推送到远程的gh-pages分支

浏览器访问http://YourGithubUsername.github.io/repo-name即可

添加本地的文件到本地仓库：

git add .

这里的.表示所有文件都加进去，这里正常是没有输出反馈的，只要不报错一般就是没问题已经添加成功。

将本地修改保存到本地仓库中：

1	git commit -m"first version"

推送到远程仓库：

1 2	git remote add origin 仓库地址 git push -u origin main(or master)

新建 .gitignore 文件，忽略掉除 docs 、 mkdocs.yml 以及 git 相关文件之外的文件

/*
!/docs
!/mkdocs.yml
!/.gitignore
!/.github

然后我们在编写完文章后，一般至少都要执行这些命令

git add .
git commit -m 'new article'
git push    # 第一次push时执行git push -u origin main
mkdocs gh-deploy

在仓库根目录下新建 .github/workflows 文件夹

1	mkdir -p .github/workflows

在 .github/workflows 文件夹下新建 gh-deploy.yml 文件，其他文件名也可以，内容如下

name: Publish docs via GitHub Pages
on:
  push:
    branches:
      - main
jobs:
  build:
    name: Deploy docs
    runs-on: ubuntu-latest
    steps:
      - name: Checkout main
        uses: actions/checkout@v2
      - name: Deploy docs
        uses: mhausenblas/mkdocs-deploy-gh-pages@master
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          EXTRA_PACKAGES: build-base

在GitHub仓库页面中，将 Settings -> Actions -> General -> Workflow Permissions 设置为 Read an write permissions，点击 Save 保存设置。这样每次编写完文章，只需成功执行 git push ，GitHub就会自动帮助我们部署。

mkdocs简单使用

添加页面

在入门使用中，mkdocs为我们创建了一个页面index.md，我们同样可以自己添加页面，比如，在docs目录下创建页面about.md，然后在配置文件mkdocs.yml中添加以下配置项：

nav: 

  --主页: index.md

  --关于我: about.md

更改外观

如果你不满意mkdocs默认的外观样式，我们也可以进行相应的更改。

更改图标

如果使用mkdocs主题，只需要在docs目录下创建目录img，然后在目录img中放入favicon.ico图标即可。

更改主题

mkdocs默认有两个主题：mkdocs和readthedoc，默认使用mkdocs。

我们在配置文件中修改，使用readthedocs主题：

1 2	theme: name: readthedocs

我们也可以使用第三方主题，第三方主题详细列表如下：

https://github.com/mkdocs/mkdocs/wiki/MkDocs-Themes

可以参照具体的主题使用教程，进行配置。

在本例中，我们配置一个名为material的主题。

首先利用pip下载相应的主题：

1	pip install mkdocs-material

然后在配置文件中修改主题：

1 2	theme: name: material

个性化设置

如果想进行网页左上角logo修改，颜色修改等可加入如下内容

theme:
    name: "material"
    logo:
        icon: "mkwiki"
    palette:
        primary: "black"
        accent: "white"
    language: "zh"