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.
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:In addition, any project you have on github that has a
git clone https://github.com/username/username.github.io cd username.github.io
gh-pagesbranch can be accessed via
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.pyfile. You can use the dafault for everything and later on modify
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.
nikola new_postcommand 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
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.ipynbhas been created. It will be empty unless your imported existing notebook. Optionally, open it with Jupyter to edit it's content.
Building will generate HTML from the program files.
To view and render the blog start Nikola by:
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.
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
- edit the file directly with jupyter
I cases where things don't get refreshed right after a file delete do:
nikola check -f --clean-files
Nikola has github_deploy command that will publish to github pages.
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 -->
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"
To enable google analytics you can edit your conf.py and add the analytics snippet to
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.