Jupyter Blogging in 5 minutes.¶

Q: What is Jupyter Blogging?
A: Blogging with jupyter notebooks.

Q: Why Jupyter Blogging?
A: As a Data Scientists, I use jupyter to create notebooks with code, equations, visualizations, documentation, etc. "Jupyter Blogging" allows me to share those notebooks with the world without any additional work.

Q: How is this achieved?
A: Jupyter Notebook + Github Pages + Nikola = Jupyter Blogging.

This tutorial will give you basic instructions for setting up a minimum blog powered by jupyter notebooks. This tutorial is written on a jupyter notebook.

Github Pages initial setup¶

Github Pages will do the hosting in addition to versioning of your blog.

Create a new repository named username.github.io, where username is your username (or organization name) on GitHub.

Clone it as so:

git clone https://github.com/username/username.github.io
cd username.github.io

In addition, any project you have on github that has a gh-pages branch can be accessed via

username.github.io/your-project

Nikola setup¶

Nikola will render all the HTML from the notebooks in a way that creates a blog structure.

Install Nikola with pip:
```
pip install "Nikola[extras]"
```
Create Nikola project (inside website root directory):
```
nikola init .
```
This will bring a prompt with bunch of questions as "site name". All answers will modify conf.py file. You can use the dafault for everything and later on modify conf.py.

In order to use Jupyter notebooks, we need to edit the conf.py file that was just generated. Scroll down until you see POSTS and PAGES declaration and add .ipynb files lines.

POSTS = (
 ("posts/*.ipynb", "posts", "post.tmpl"), # -- add this line
 ("posts/*.rst", "posts", "post.tmpl"),
 ("posts/*.md", "posts", "post.tmpl"),
 ("posts/*.txt", "posts", "post.tmpl"),
 ("posts/*.html", "posts", "post.tmpl"),
)
PAGES = (
 ("pages/*.ipynb", "pages", "page.tmpl"), # -- add this line
 ("pages/*.rst", "pages", "page.tmpl"),
 ("pages/*.md", "pages", "page.tmpl"),
 ("pages/*.txt", "pages", "page.tmpl"),
 ("pages/*.html", "pages", "page.tmpl"),
)

Create a page¶

Use nikola new_post command to add a new page. I would create an "About" page.

nikola new_page --title="About" --format=markdown

Create a post¶

After you have an empty blog its time to add new posts.

Use nikola new_post command to add a new post to the blog. When creating a jupyter notebook post specify --format=ipynb. To create a post from existing notebook add option --import=../path/Foo.ipynb

Create a post with a new empty notebook and edit it later:
```
nikola new_post --title="test" --format=ipynb
```
Create a post with an existing notebook:
```
nikola new_post --title="test" --format=ipynb --import=../path/Foo.ipynb
```
A new jupyter notebook file posts/test.ipynb has been created. It will be empty unless your imported existing notebook. Optionally, open it with Jupyter to edit it's content.

Build¶

Building will generate HTML from the program files.

nikola build

To view and render the blog start Nikola by:

nikola serve

Alternatively, you can use nikola auto for build and serve in one command.

Point your broswer at localhost:8000. As changes are saved to the notebooks, the site will automatically rebuild and refresh, but it may take a few seconds.

Press Ctrl+C at the command prompt to stop the server.

For more information see Nikola's Getting Started

Delete or Update a post¶

To delete a post, delete the post_name.ipynb file inside posts drectory and rebuild.
```
rm -f posts/test.ipynb.ipynb
nikola build
```
To edit a post you can either:
- edit the file directly with jupyter
```
jupyter notebook posts/test.ipynb
```
- delete the post and create one with the same title from an existing notebook
```
rm -f posts/test.ipynb
nikola new_post --title="test" --format=ipynb --import=../path/Foo.ipynb
```

I cases where things don't get refreshed right after a file delete do:

 nikola check -f --clean-files

Deploy¶

Nikola has github_deploy command that will publish to github pages.

nikola github_deploy

This command will creates two branches on your github: master - holds the rendered HTML of your site src - holds the files used for rendering as notebooks, configs and other. When you clone your repo you need to swithch branch to src in order to modify the site.

git checkout src

The blog should be live online. Go to https://username.github.io to confirm it is working.

Enable teaser for posts¶

Modify config.py to:

INDEXES_PAGES_MAIN = True # optional
INDEX_TEASERS = True

Add this tag to a meta cell where you want the teaser to end:

<!-- TEASER_END -->

Enable comments¶

Create an account with disqus and modify config.py to:

COMMENT_SYSTEM = "disqus"
# For DISQUS it's called the shortname
COMMENT_SYSTEM_ID = "username-github-io"

Google Analytics¶

To enable google analytics you can edit your conf.py and add the analytics snippet to EXTRA_HEAD_DATA variable.

EXTRA_HEAD_DATA = """
paste your snippet here.
"""

Alternatives to Nikola¶

I choose Nikola for site generator because of its built-in Jupyter Notebook support. There are other alternatives that need workarounds to support notebooks.

Jekyll is the default framework used by github and is probably the most popular framework.
Pelican, is another site generator and it is more popular than Nikola.