搭建SM2 Wiki之路

|

搭建SM2 Wiki之路

Preface

想不到什么好标题就用这个了。这篇文章记录了我搭建SM2 Wiki的大致经历，在这个过程中遇到的许多问题以及最后的解决方式。希望能给大家，尤其是也想通过Mkdocs搭建的人一些参考。但是本文也是个人理解，无法保证没有错误，恳请谅解。

在这里先致谢mkdocs和所有网络上参考资料的编辑者

准备工作

首先我使用了阿里云学生优惠的服务器，100+RMB 每年，选择安装的是Ubuntu 16.04系统

开机后升级一下源。但是我发现这个云主机的默认软件源是阿里云的，不知道怎么才能换成NUS的

安装Mkdocs

中文文档:https://markdown-docs-zh.readthedocs.io/zh_CN/latest/

英文文档:https://www.mkdocs.org/

按照上面步骤来先看一下python版本,结果是2.7.12的…似乎有点低，不过文档说资瓷的话就不管了

按照文档pip install mkdocs后，查看mkdocs时神奇的报错了就发生了，而且似乎是因为python版本太低不兼容造成的 :(

安装python3后发现版本还是没有变，于是上网找到了这篇博客:Ubuntu16.04下完美切换Python版本，完美解决问题

结果再次pip时又报错了，搜索错误信息找到了Stackoverflow上的这个问题

按照其中一个方法重装pip就好了

开始部署

还是按照官方文档中的步骤

1
2
mkdocs new SM2-wiki
cd SM2-wiki

此时文件夹里的mkdocs.yml是配置信息，关于更多配置信息的编辑可以参考这里

当然这里只是你服务器本地的文件，我们这里使用Github Pages托管

怎么做呢？

先在Github中创建一个新repo，例如创了一个叫SM2-wiki的repo

然后我们将它clone到本地

git clone https://github.com/<user-name>/SM2-wiki <本地目录名>

如果你不熟悉Git指令强烈推荐阅读这篇文章:http://www.ruanyifeng.com/blog/2014/06/git_remote.html

接下来把mkdocs创立的SM2-wiki里的文件比如mkdocs.yml,/docs全都复制到clone到的那个repo里

完成后同时cd到clone到的repo中，接下来所有的本地文件操作都在那里进行

此时文件夹应该用这几样东西:/docs,mkdocs.yml,LICENSE（如果你在创建repo时有选的话）,README.md

然后输入指令mkdocs gh-deploy,开始部署

它会要求输入你的Github上的用户名和密码.

如果成功后就可以在https://<user-name>.github.io/SM2-wiki这里看到你的网页了

但是这时候有一个很不方便的是我们这时只能在本地修改/docs和mkdocs.yml,怎么把它们与repo中的master分支关联使得我们可以在Github上编辑呢？

其实几行Git指令就好了,但是首先我们先保证不把部署后生成的/site也给送到master分支

1
2
3
4
echo "site/" >> .gitignore
git add /docs mkdocs.yml .gitignore
git commit -m "add /docs mkdocs.yml .gitignore"
git push origin master

这样的话就建立起关联了，我们假如在Github上修改了master分支里的文件，只需要

git pull origin

就把远程分支的更新与我们本地的合并了，然后再次mkdocs gh-deploy部署后就完成了更新这个过程

更多操作

官方mkdocs的主题我觉得太丑了,于是才用和OI-wiki一样的mkdocs-material主题

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

但是安装时出了个大坑

修改主题后部署时报错，原因是本地markdown版本太低了

结果用pip更新markdown时又给我报错了,错误信息

ERROR: Cannot uninstall 'Markdown'. It is a distutils installed project and thus we cannot accurately determine which files belong to it which would lead to only a partial uninstall.

谷歌了一下发现这个相关issues:https://github.com/pypa/pip/issues/5247

发现了一个非常好的方法，完美解决了问题:

1
2
3
4
5
6
#Reduced version,
pip install --upgrade --force-reinstall pip==9.0.3
#Tried to re-install package
pip upgrade markdown --disable-pip-version-check
#At last, recover the latest version for pip
pip install --upgrade pip

关于更多配置，这里推荐几个地方:

…