打造个人笔记—03Sphinx案例之markdown笔记

上篇文章简单介绍了rst笔记的写法，本文将介绍使用markdown来记笔记，如何用sphinx来生成好看的静态网页。

预览效果：https://selfteachingroad.cn/wiki/HintCAD/

笔记源码：https://gitee.com/yanggenjie/HintCAD-tutorial（非sphinx源码，是markdwon笔记源码）

因为来看纬地教程的读者大多都是土木类专业的同学，非程序员，基本都不上github，所以我之前就都把源码放到gitee上，方便大家访问了。

这是我以前写的关于纬地7.0的使用教程，以前不懂编程，就只是简单的用markdown写了，然后导出pdf而已。

接下来简单介绍一下这个项目是怎么做的；

1.初始化sphinx

首先还是找个空的文件夹，右键打开终端，输入sphinx-quickstart​初始化项目

sphinx-quickstart

2.修改配置文件

修改source/conf.py​文件

# 修改主题，变量赋值为piccolo_theme
html_theme = 'piccolo_theme'
# extensions变量添加recommonmark、sphinx_markdown_tables
extensions = [
	'recommonmark',
	'sphinx_markdown_tables',
]
# 添加对.rst、.md文件的支持
source_suffix = {'.rst': 'restructuredtext','.md': 'markdown'}

上面的配置文件修改完之后，还需要安装对应的主题和插件，打开任意终端，输入以下命令安装

pip install piccolo_theme recommonmark sphinx-markdown-tables

3.添加笔记文件

可以下载我的纬地笔记源码先测试一下：https://selfteachingroad.cn/wiki/HintCAD/，也可以直接开始写你自己的笔记

还是一样在source文件夹下创建docs，下载笔记，把笔记都放进去；

新建docs文件夹，只是一个习惯而已，直接在source文件夹下写也可以。

最终的笔记源码如下：

4.修改source/index.rst​文件

整个index.rst​文件内容如下：

纬地一学即会
=============

纬地一学即会的html版本

.. toctree::
   :maxdepth: 2
   :caption: Contents:
   :glob:
   
   docs/*

Indices and tables
==================

* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`

5.编译生成html文件

.\make.bat html

预览

用浏览器打开build/html/index.html​文件

ok，大功告成。除了可以在本地自己浏览，也可以使用githubPage之类的静态托管功能，分享到公网上给其它同学。

关于图片丢失的问题

一般是因为图片的路径中包含了中文，所以编译的时候没有正确识别。

文件的路径只能由数字或英文组成。如下：

![image-20201126151256576](./00/0472ee57dfaf4c479fb781359c1158dc.webp)