ipynb2pelican is used to provide jupyter ipynb support in pelican.

This my blog source code repo: https://github.com/peijunz/peijunz.github.io/tree/src, and .travis.yml

Installation and Setup

Setup pelican

Simply run command pelican-quickstart, and you will get the welcome information, and asked some questions. For the following questions, you probably do not want to use default setting:

> What is your time zone? [Europe/Paris] US/Eastern
> Do you want to upload your website using GitHub Pages? (y/N) Y
> Is this your personal page (username.github.io)? (y/N) y

Setup navigation by TOC

This part depends on pelican-toc plugin and applies to bootstrap3 theme. It is updated to my fork of pelican-theme repo

We can add the following code in article.html before {{ article.content }} to implement the navigation(Table of contents).

        {% if article.toc %}
        <div class="panel panel-default">
            <div class="panel-heading">Table of Contents</div>
            <div class="panel-body">
            {{article.toc}}
            </div>
        </div>
        {% endif %}

Remove paragraph indicator ¶ inside navigation

Look for the first line below, and add the second line in :

content.toc = tree_soup.decode(formatter='html')
content.toc = content.toc.replace('¶', '')

Setup Git and Github Pages

  • Set up your Github Pages

    Head over to GitHub and create a new repository named username.github.io, where username is your username (or organization name) on GitHub.

  • Change directory to the blog folder containing Makefile, pelicanconf.py etc.
  • Init git repo by git init
  • Create a branch src by git checkout -b src. This will be your working folder
  • Add a remote repo related to your github page and push the src to github
  • Now you can push webpage to master branch by make github, which includes ghp-import commands.

Write your post in jupyter notebook!

There is a official tutorial on how to write a MarkDown/reStructuredText article with metadata

ipynb2pelican defined a metadata format here: https://github.com/peijunz/ipynb2pelican#metacell

Make your contents

  • Generate Site
    make html
  • Test site at localhost
    make serve
    Then, go to address localhost:8000 in your browser.
  • Generate + test
    make devserver
    It will automatically regenerate html instantly after your change of the src.
  • Deploy to github page
    make github

Tweaks

Extra \n in indented code block

For indent style code block

Some text before

    This is a indented code block
    This is another line

Some text after the block with an empty line between them

It will produce


Some text before

This is a indented code block
This is another line

Some text after the block with an empty line between them


So you should stick to ``` style code block or remove empty lines after indented code block. This is a bug of nbconvert

extra directory

This supports an extra directory in the same directory of your Makefile, which can be used to place static files to root directory of your sites, such as:

  • CNAME file for github page
  • local mathjax for local preview of your site.
    • Link local mathjax to the extra directory by ln -s MATHJAX_PATH extra/static
    • Use MATHJAX_CDN="/mathjax/MathJax.js" in pelicanconf.py
    • Use MATHJAX_CDN=None in pelicanconf.py

In html and publish section of Makefile, simply add:

if test -d $(BASEDIR)/extra; then cp -r $(BASEDIR)/extra/* $(OUTPUTDIR)/; fi

Cache

Enable cache for local build but not for publishing:

  • pelicanconf.py
    CACHE_CONTENT = True
    LOAD_CONTENT_CACHE = True
    
  • publishconf.py
    CACHE_CONTENT = False
    LOAD_CONTENT_CACHE = False
    

Comments

comments powered by Disqus