基于 github pages 的初步部署

step 0: 写在前面

参考资料：

windows安装创建mkdocs项目

mkdocs 部署到github

如果您在根据本文部署网站的时候遇到问题，可以优先参考上面两个资料解决。

本机环境：win11。

step 1: 在电脑上安装最新版 python

step 2: 安装 pip

网上很多地方能找得到，例如这里，把里面的 pip-9.0.1.tar.gz 解压下来。然后在解压后的文件夹中，打开 cmd，执行命令：

python setup.py install

输入 pip -V 显示版本信息则安装成功。

注：如果上面的链接失效或者你信不过网上随意找的文件，试试这个？

step 3: 安装 mkdocs 和 material 主题

还是在 cmd 中，执行以下命令：

pip install mkdocs

输入 mkdocs --version 显示版本信息则安装成功。

step 4: 新建 mkdocs 项目

在你希望存储项目的目录下，执行以下命令：

mkdocs new FolderName

这时候你会发现该目录下出现了一个文件夹 FolderName ，里面存放的就是你的 mkdocs 项目啦。至于里面内容的修改后面再说。

此时在 FolderName 文件夹下，执行命令：

mkdocs serve

用浏览器访问提示的地址（一般为 127.0.0.1:8000），出现正常页面即可。

step 5: 配置 github pages

从 0 开始的准备工作

如果您之前没有对 github 及其提供的服务 github pages 有所了解，那么您可能需要这一段的帮助。

这一步依托于 github.com 进行。由于该网站位于国外，您的连接可能不稳定，如果上不去请使用魔术技巧（

首先注册一个 github 账号，并下载 git。同样，git 可以通过合理运用搜索引擎找到，如果有其他问题，和上面一样可以试试这个。

在你的 github 账号下创立一个仓库： username.github.io 。

其中 username 为你的 github 用户名（后面同理），如有大写字母转为小写字母。

上传您的网站

在您的 mkdocs 目录下，在 cmd 中依次输入如下命令：

git init
git add .
git commit -m "Initial commit"
git branch -M main
git remote add origin your_url
git push -u origin main

其中 your_url 为您刚刚创立仓库的 url，区分大小写。

中间可能会需要您再次登录自己的 github 账号，根据引导登录即可。

如果这一步无法进行，可以试着把 cmd 关掉重新打开，给出管理员权限，或者重启之后再次尝试。

之后，在 cmd 中输入如下命令：

mkdocs gh-deploy

如果遇到类似 Failed to connect to github.com port 443 after 21117 ms: Could not connect to server 的错误，请看看这里。

进入你的仓库，点击 Setting 选项，进入设置页面。

• 点击侧边栏 Pages 选项，开启 Github Pages 服务。然后找到 Build and deployment 一栏：

  • 将 Source 设置为 Deploy from a branch 选项；
  • 将 Branch 设置为 gh-pages ; /(root) 两个选项；

• 点击侧边栏 General 选项。找到 Default branch 一栏，输入框后第二个按钮（Switch to another branch）找到 gh-pages 并选择。

等待一段时间后，访问 username.github.io ，您就能访问到您的网站啦。