Blogging with IPython Notebooks
If you are tech geek and want to blog, Static web pages hosted on github or S3 for free to low cost seemed the right approach. Writing blogs using Markdown offers the right combination of fun, ease of use and flexibility. I can even add
code in my blog without HTML markup cluttering my content. No wonder Jekell / Octopress is very popular amoung tech geeks writing blogs and hosting in github / S3.
I use Python a lot and really love IPython Notebooks. I would like write my blogs in IPython notebooks and publish them. This basically came down to two choices - Pelican and Nikola. Both are static blog generator and have integration with IPython notebooks. In this post, I try to rationale, why I choose Nikola and how you can set it up and start blogging using IPython Notebooks.
Pelican vs Nikola
Pelican is more popular than Nikola and has a huge eco-system of themes. But the integration with IPython seems bit hacky and doesn't work with the most recent update of markdown python package. See this blog post by Jake VanderPlas. If IPython integration is not a deal breaker, Pelican is a good choice.
I choose Nikola, because of easy integration with IPython Notebook. You can follow the steps here or see Damian Avila's blog posts. I used Damian's blog posts and his zen-ipython theme to build this blog.
Setting up local system
Change to the directory you want to create the blog in local system. First, let's setup a new virtual environment for blog post and activate the virutal environment. I used Python 3 / pyvenv for this blog. Alternatively, you can use conda to setup your environment.
pyvenv env3 source env3/bin/activate
Now that the virtual environment is active, Let's install nikola (static web page generator), requests, markdown and IPython libraries
pip install nikola requests markdown webassets ipython[notebook]
Create the blog by -
nikola init myblogsite
cd into the new blog directory -
All commands will be entered inside the directory -
More information at Nikola
Modifying Configuration file
conf.pyto add Markdown and IPython as valid blog formats.
POSTS = ( ("posts/*.md", "posts", "post.tmpl"), ("posts/*.ipynb", "posts", "post.tmpl"), ("posts/*.txt", "posts", "post.tmpl"), ("posts/*.rst", "posts", "post.tmpl"), ) PAGES = ( ("stories/*.md", "stories", "story.tmpl"), ("stories/*.ipynb", "stories", "story.tmpl"), ("stories/*.txt", "stories", "story.tmpl"), ("stories/*.rst", "stories", "story.tmpl"), )
- Set Teaser to True to show only partial content on Index Page with Read More link -
# Show only teasers in the index pages? Defaults to False. INDEX_TEASERS = True
Update COMMENT_SYSTEM to use disqus or another comments engine to the blog
Update License and Footer to give credits
Creating Blog Posts
To create a new blog post by -
nikola new_postin the terminal at the top level folder of your blog. This might create a post with rST / text format.
- To use Markdown, create the blog post using
nikola new_post -f markdown
- To use rST format, use -
nikola new_post -f rest
- Most importantly, to use IPython Notebook for the blog post, create using,
nikola new_post -f ipynb
It's that simple to create blog posts from IPython Notebooks.
To create a page like about-me by -
nikola new_story. The format can be specified ysing
-f format, similar to the syntax for creating blog posts.
To install / checkout themes that are bundled with nikola,
nikola install_theme -l. For this blog, I used zen-ipython theme by Damien. To do that, run
nikola install_theme zen-ipython from the main folder of the blog.
conf.py is updated with the theme -
# Name of the theme to use. THEME = "zen-ipython"
Build / Serve
To build the static pages -
To test on local machine,
nikola serve. To serve on local machine,
nikola serve --port 8080or any other port number.
- Github: To publish to github pages, follow the instructions. Nikola has some nice integration with github pages. Read the docs. You may just have to do
I have following in
conf.py to push to master and publish the output html to gh-pages. All I do is
nikola deploy and it's done for me. Note that you still need to do
nikola build to create the output html files before running deploy command.
DEPLOY_COMMANDS = ["git add .", "git commit -am 'Update'", "git push origin master", "git subtree split --prefix output -b gh-pages", "git push -f origin gh-pages:gh-pages", "git branch -D gh-pages"]
- S3: Publishing blog to AWS S3 is little bit more involved. I believe Nikola has some integration with S3 as well, but I have not tried it.