本文介绍如何利用 MkDocs 将 Jupyter 文档发布到 GitHub Pages 上。Jupyter 既可以用作交互式展示科学计算、数据处理过程,也可以作为 Python 开发环境,甚至可以当做实时的 Markdown 编辑器。借助 nbconvert 工具可以将 Jupyter 文档转化为 Markdown 格式,并通过 MkDocs 将其发布到 GitHub Pages。
首先安装科学计算包 Anaconda,其中已经包含了很多科学计算机、数据处理相关的 Python 包,也包括 Jupyter 在内(如果只需要 Jupyter 普通的 Python 执行环境和 Markdown 编辑器功能,可跳过这一步,直接单独安装 Jupyter)。
可以通过清华大学 TUNA 镜像源下载,具体参考《用 conda 管理 Python 开发环境》。安装完成之后可以通过 conda
命令管理 Python 开发环境:
conda info
Using Anaconda Cloud api site https://api.anaconda.org
Current conda install:
platform : osx-64
conda version : 4.0.8
conda-build version : 1.19.0
python version : 3.5.1.final.0
requests version : 2.10.0
root environment : /Users/rainy/anaconda (writable)
default environment : /Users/rainy/anaconda
envs directories : /Users/rainy/anaconda/envs
package cache : /Users/rainy/anaconda/pkgs
channel URLs : https://repo.continuum.io/pkgs/free/osx-64/
https://repo.continuum.io/pkgs/free/noarch/
https://repo.continuum.io/pkgs/pro/osx-64/
https://repo.continuum.io/pkgs/pro/noarch/
config file : None
is foreign system : False
从默认环境生成一个新的独立环境:
conda env crate -n dhub --clone root
source activate dhub
# discarding /Users/rainy/anaconda/bin from PATH
# prepending /Users/rainy/anaconda/envs/dhub/bin to PATH
安装 MkDocs:
pip install mkdocs -i http://pypi.douban.com/simple --trusted-host=pypi.douban.com
根据 GitHub ID 创建一个 <username>.github.io
的公开仓库,即可以通过 http://username.github.io
访问该仓库下的静态文档。创建其它仓库,如 project
,可以通过 http://username.github.io/project/
访问该仓库下的 gh-pages
分支。
mkdocs
命令创建新的 mkdocs
项目:
mkdocs init data-blog
cd data-blog
git init
git remote add origin git@github.com:rainyear/data-blog.git
tree -L 1
.
├── LICENSE
├── README.md
├── docs
├── mkdocs.yml
其中 Markdown
文件保存在 docs/
目录下,并通过配置文件 mkdocs.yml
决定生成的静态网站的结构:
cat mkdocs.yml
pages:
- {Home: index.md}
site_name: Data Lab
theme: flatly
mkdir config jupyters
jupyter notebook --generate-config
cp ~/.jupyter/jupyter_notebook_config.py config/
修改 jupyter_notebook_config.py
:
def output_post_save(model, os_path, contents_manager):
pass
c.FileContentsManager.root_dir = 'jupyters'
c.FileContentsManager.post_save_hook = output_post_save
c.FileContentsManager.post_save_hook
用于设置 Jupyter 文档保存的时候触发的操作,这里通过 jupyter-nbconvert
命令将当前的 Jupyter 文档转换为 Markdown 并保存到 docs/
目录,并更新 mkdocs.yml
配置文件(具体代码可以查看 jupyter_notebook_config.py)。
打开 Jupyter Notebook:
jupyter notebook --config config/jupyter_notebook_config.py
在本地执行 mkdocs serve
可以在本地查看生成的静态网站:
tree -L 2
.
├── LICENSE
├── README.md
├── config
│ └── jupyter_notebook_config.py
├── docs
│ ├── About.md
│ ├── Cheatsheet.md
│ └── index.md
├── jupyters
│ ├── About.ipynb
│ ├── Cheatsheet.ipynb
│ └── Home.md
├── mkdocs.yml
在每次文档保存之后,jupyters/
目录下的文档将自动转换为 Markdown 并保存在 docs/
目录,其中子目录将以类别的形式呈现在网站上:
执行 mkdocs gh-deploy --clean
即可自动将生成的静态网站推送到 GitHub 远程仓库的 gh-pages
分支,从而发布到 GitHub Pages 页面: