This article describes how to use MkDocs to publish Jupyter documents to GitHub Pages. Jupyter can be used as an interactive demonstration of scientific computing, data processing, a Python development environment, and even as a real-time Markdown editor. The NBConvert tool converts Jupyter documents to Markdown format and publishes them to GitHub Pages via MkDocs.



1. Installation environment

Start by installing Anaconda, which already includes many Python packages for scientific computers and data processing, as well as Jupyter (skip this step if you only need the normal Python execution environment and Markdown editor features of Jupyter). Direct separate installation of Jupyter).

You can download the TUNA image from Tsinghua University. For details, see “Managing the Python Development Environment with Conda”. Once installed, you can use the conda command to manage the Python development environment:

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 : FalseCopy the code

Generate a new standalone environment from the default environment:

conda env crate -n dhub --clone root

source activate dhub

Copy the code

Install MkDocs:

pip install mkdocs -i http://pypi.douban.com/simple --trusted-host=pypi.douban.comCopy the code

2. Create the GitHub Pages repository

According to the lot ID to create a. Lot. IO public warehouse, which can be accessed through http://username.github.io the warehouse under static documents. Create other warehouse, such as project, can be accessed through http://username.github.io/project/ gh – pages branch under the warehouse.

3. mkdocsThe command

Create a new mkdocs project:

Mkdocs init data-blogcd data-blog git init git remote add origin [email protected]:rainyear/data-blog.git tree -l 1. ├── LICENSE ├─ Readme. md ├─ docs ├─ mkdocs. YmlCopy the code

The Markdown file is saved in the docs/ directory, and the structure of the generated static site is determined by the configuration file mkdocs.yml:

cat mkdocs.yml

pages:
- {Home: index.md}
site_name: Data Lab
theme: flatlyCopy the code

4. Create and modify the Jupyter configuration file

mkdir config jupyters
jupyter notebook --generate-config
cp ~/.jupyter/jupyter_notebook_config.py config/Copy the code

Modify jupyter_notebook_config. Py:

def output_post_save(model, os_path, contents_manager):
  passc.FileContentsManager.root_dir = 'jupyters'c.FileContentsManager.post_save_hook = output_post_saveCopy the code

C.F. IleContentsManager post_save_hook used to set the Jupyter document is saved when the operation of the trigger, The current Jupyter document is converted to Markdown and saved to the docs/ directory by using the jupyter-nbconvert command. And update the mkdocs. Yml configuration file (see jupyter_notebook_config.py for the code).

Open Jupyter Notebook:

jupyter notebook --config config/jupyter_notebook_config.pyCopy the code

5. Publish to GitHub Pages

Run mkdocs serve locally to view the generated static website locally:

Tree - L 2. ├ ─ ─ LICENSE ├ ─ ─ the README. Md ├ ─ ─ the config │ └ ─ ─ jupyter_notebook_config. Py ├ ─ ─ docs │ ├ ─ ─ the About. Md │ ├ ─ ─ Cheatsheet. Md │ └ ─ ─ index. The md ├ ─ ─ jupyters │ ├ ─ ─ the About. Ipynb │ ├ ─ ─ Cheatsheet. Ipynb │ └ ─ ─ Home. The md ├ ─ ─ mkdocs. YmlCopy the code

After each document save, documents in jupyters/ directory will be automatically converted to Markdown and saved in docs/ directory, where sub-directories will be presented on the website as categories:



Run mkdocs gh-deploy –clean to automatically push the generated static site to the GH-Pages branch of the GitHub remote repository for publication to the GitHub Pages page: