2. Computer
  3. Blogging with Jupyter and Pelican

Blogging with Jupyter and Pelican

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