-
Markdown:书写文档
-
Pandoc:格式转化
-
Sphinx:生成网页
-
GitHub:托管项目
-
ReadtheDocs:发布网页
接下来,就来看看到底是如何实现的?
01
成品展示
02
安装Sphnix
$ pip install sphinx sphinx-autobuild sphinx_rtd_theme
# 先创建一个工程目录:F:\\mkdocs
$ cd F:\\mkdocs
$ sphinx-quickstart
> Project name: MING's BLOG
> Author name(s): MING
> Project release []: 1.0
> Project language [en]: zh_CN
F:\mkdocs
(mkdocs) λ ls -l
total 5
-rw-r--r-- 1 wangbm 1049089 610 Jun 23 16:57 Makefile
drwxr-xr-x 1 wangbm 1049089 0 Jun 23 16:57 build/
-rw-r--r-- 1 wangbm 1049089 817 Jun 23 16:57 make.bat
drwxr-xr-x 1 wangbm 1049089 0 Jun 23 16:57 source/
F:\mkdocs
(mkdocs) λ tree
卷 文档 的文件夹 PATH 列表
卷序列号为 0002-B4B9
F:.
├─build
└─source
├─_static
└─_templates
-
build:文件夹,当你执行make html的时候,生成的html静态文件都存放在这里。
-
source:文件夹:你的文档源文件全部应全部放在source根目录下。
-
Makefile:编译文件。完全不用管。
-
make.bat:bat脚本。你也不用管。
03
配置及扩展
-
配置主题
-
支持LaTeX
-
支持中文检索
pip install -r requirements.txt -i www.idiancai.com/simple/
04
撰写文章
第一章 如何成为有钱人
======================
1.1 财富继承法
---------------------
有个有钱的老爸。
1.2 财富共享法
---------------------
有个有钱的老婆。
.. toctree::
:maxdepth: 2
:caption: Contents:
how_to_be_a_rich_man
Indices and tables
==================
* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`
F:\mkdocs
(mkdocs) λ make html
Running Sphinx v1.7.4
loading translations [zh_CN]... done
loading pickled environment... done
building [mo]: targets for 0 po files that are out of date
building [html]: targets for 2 source files that are out of date
updating environment: [extensions changed] 2 added, 0 changed, 0 removed
reading sources... [100%] index
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
preparing documents... done
writing output... [100%] index
generating indices... genindex
writing additional pages... search
copying static files... done
copying extra files... done
dumping search index in English (code: en) ... done
dumping object inventory... done
build succeeded.
The HTML pages are in build\html.
05
托管项目
build/
.idea/
*.pyc
06
发布上线
这里要提醒一下的是,Sphinx的文档格式,默认是 rst 格式,如果你习惯了使用Markdown来写文章,可以使用 Pandoc 这个神器转换一下。
这里给出转换命令。
pandoc -V mainfont="SimSun" -f markdown -t rst hello.md -o hello.rst
或者你也可以在Sphinx上添加支持Markdown渲染的扩展模块及配置。也很简单,但是,我发现使用 md 文件,在网站上的导航无法实现跳转。
到这里,属于你的个人博客就搭建好了,快去试一下吧。