使用Sphinx管理个人学习笔记
0. 前言
这个网站是用Markdown写的。我学习了以后发现Markdown真的非常适合记笔记，不需要考虑格式问题，最重要的是语法非常简单，比Latex简单多了。虽然说最后呈现出来的效果就是个简单的html，但是省去了手撸html标签的步骤。
1. Markdown语法
语法可以参考这个知乎上的这篇文章，其效果见网站上的另一篇文档这是用来学习markdown语法的一级标题。VSCode的Markdown插件也很好用，可以实现实时预览。
2. Sphinx环境配置
Markdown写完后需要转换成html才能被浏览器以网页的形式打开。转换成html的方案很多，可以在服务端用javascript转换，也可以转换成静态html网页。我一度也考虑过使用jekyll，但试用感觉仍然过于庞大，还需要安装一堆Ruby的依赖。后来我在看Jupyter和Python的相关文档时发现它们是用Sphinx生成的，十分简洁，整个网站架构就是一个文档库，非常适合这种应用场景。
安装
安装Sphinx有关的包：
pip install sphinx
pip install sphinx-autobuild
pip install sphinx_rtd_theme
pip install recommonmark
pip install sphinx_markdown_tables
编辑项目
创建并建立目录，执行命令
sphinx-quickstart
根据提示选择要不要把源代码和编译产物分开，选择y。然后设置项目名、作者名、版本号，这些后续是可以修改的。
之后目录下会生成一个Makefile，一个source目录，一个build目录。所有的Markdown源文件就可以recursively保存在source目录里。
例如，当前这一级目录下的index.rst用来设置这一级的标题，和这一级有那几篇内容，再下一级又有一个index.rst用来配置下一级的内容。
conf.py是用来配置插件和主题的。sphinx_rtd_theme是Read the Docs官方出品的一系列主题，在这里可以预览，在conf.py可以设置成其他喜欢的主题。
extensions = ['recommonmark', 'sphinx_markdown_tables']
html_theme = 'sphinx_rtd_theme'
热部署预览
在本地调试时可以使用sphinx-autobuild热部署进行预览。其中host默认是localhost，port默认是8000，然后在本地浏览器中就可以打开，每次更新源代码和设置都可以实时看到效果。
sphinx_autobuild source build/html --host=<host> --port=<port>
编译
试用后发现sphinx-autobuild存在一些bug，比如中间级别的目录标题会被显示成Untitled。为了稳定性，最终部署到服务器上的应该是个静态网页，所以需要编译。
sphinx-build source build
所有source里的源代码都被编译成了build里的网页。
3. nginx展示静态网页
在nginx的配置文件/etc/nginx/sites-enabled/default里添加一条匹配规则:
location /notes {
index index.html;
}
重新加载配置后nginx就会在 nginx根目录/notes/ 下面寻找index.html。
nginx根目录的路径则默认是在/var/www/html/，我原本想放在自己的home里，但是nginx没有我的文件系统的权限，会报403 Forbidden Error，所以要把编译好的网页复制到/var/www/html/notes/下面。
参考资料
Markdown
https://zhuanlan.zhihu.com/p/496076040 https://www.markdownguide.org/basic-syntax/
Markdown生成html
https://www.bilibili.com/opus/413566116084184281 https://jameshard.ing/posts/simple-static-markdown-blog-in-flask/ https://blog.csdn.net/qq_34967770/article/details/110098826 https://docs.pingcode.com/baike/3324274
Sphinx
https://nyx-blog.readthedocs.io/zh/latest/note/index.html https://sphinx-themes.readthedocs.io/en/latest/
nginx
https://docs.nginx.com/nginx/admin-guide/web-server/serving-static-content/