Now I have decided to use github + pelican for personal blog. The plan is to integrate with ipython notebook so all the math and stats notes can be displayed easily.

Setup Steps

1. Follow the instructions from How to setup Github User Page with Pelican, up to the point where first post is done and local devserver is up. The only difference is that I am using main branch ("master") for all edits. The other very good references are:

   • Migrating to GitHub Pages using Pelican
   • Creating your blog with Pelican

   In fact, they use pretty themes. I plan to read through carefully later and see if can use some of their settings.

2. For now, use the same theme as in python4oceanographers, mainly download theme and plugin from github, then edit pelicanconf.py and publishconf.py scripts.

   $ git clone https://github.com/jakevdp/pelican-octopress-theme.git
   $ git clone https://github.com/getpelican/pelican-plugins.git
   

3. Write markdown files in conten folder, then run make devserver to generate HTML for the site, and serves is up locally at http://localhost:8000. Note that make devserver will also automatically regenerate the whole site, i.e. run pelican on content every time one save a change to a content, configuration, or theme file. Just refresh the page in your browser, and you should immediately see the changes. To shutdown the webserver, use make stopserver.

4. Now we have two repos, one is for blog-source, the other is actual site under output directory. See Posting to GitHub for how to publish to username.github.io site. In short summary, use the following commands:

   $ cd blog
   $ make publish # or "pelican content"
   $ cd output
   $ git add --all
   $ git commit -m "commit message"
   $ git push origin master
   

5. The disadvantage of previous step is that two checkins are needed for update, one for blog-source, the other for actual site. One can use git hooks to push changes to both repos at the same time, as shown here. Now one can do the following:

   $ vim content/your-message.md
   $ git commit -am "commit message"
   $ git push origin master
   

Workflow

I use conda to manage virtualenv. The normal workflow is going to be like below:

$ activate myblog
$ vim content/blog-post-file.md  # add/edit entries
$ ... # test locally till all is good
$ git commit -am "commit message"
$ git push origin master
$ deactivate myblog # or just exit once all done

As to ipython notebook integration and how to use markdown, the blog post Migrating from Octopress to Pelican from Jake gives very detailed instructions. Check it out.

Resources

1. Creating your blog with Pelican
2. Migrating to GitHub Pages using Pelican
3. Migrating from Octopress to Pelican
4. A great reference for Pelican
5. Daring Fireball site's full documentation for Markdown

Update

11-24-2014: It turns out Pelican only monitors '.md' files in content folder, so any changes to '.ipynb' would not trigger regeneration of html. One need to edit pelicanconf.py to disable cache:

LOAD_CONTENT_CACHE = False

Now every ipython notebook change requires manually run make html or make publish. If anyone knows a better solution, please let me know.

12-10-2014: The generated notebook html has no color highlighting for python code. Found a solution from a post by joergdietrich here, also see discussion on github.

--- a/liquid_tags/notebook.py
+++ b/liquid_tags/notebook.py
@@ -298,7 +298,7 @@ def notebook(preprocessor, tag, markup):
        print ("\n ** Writing styles to _nb_header.html: "
            "this should be included in the theme. **\n")

-       header = '\n'.join(CSS_WRAPPER.format(css_line)
+       header = '\n'.join(CSS_WRAPPER.format(css_line.replace(".highlight ", ".highlight-ipynb "))
                        for css_line in resources['inlining']['css'])
        header += JS_INCLUDE