Nikola

First steps

Initialize the site

Type the following at the command line to initialize a new Nikola site:

nikola init site_name

Answer the questions to setup the initial site. Be sure the base URL ends in '/'.


Install and configure the org-mode plugin

Nikola can compile org-mode files using a custom plugin. Information on the plugin can be found here: http://plugins.getnikola.com/#orgmode. To install the plugin for my site, I ran the following command from inside my site directory:

nikola plugin -i orgmode

This created a folder called plugins inside the site directory containing the orgmode plugin files. The most important file is init.el.

Next, I had to add the org-mode compiler to the COMPILERS dictionary in conf.py:

COMPILERS["orgmode"] = ('.org',)

Note that I manually edited the COMPILERS dictionary to add the key-value pair; I did not actually add to the dictionary with the code above.

I also had to modify my POSTS and PAGES variables in conf.py to read .org files:

POSTS = POSTS + (("posts/*.org", "posts", "post.tmpl"),)
PAGES = PAGES + (("stories/*.org", "posts", "post.tmpl"),)

To create a post using org-mode, I need to enter the following code at the top of the org-file in a comments section:

#+BEGIN_COMMENT
.. title:
.. slug: 
.. date: 
.. tags: 
.. link:
.. description:
.. type: text
#+END_COMMENT

Setting the github_deploy variables

When publishing a project website on GitHub, you push the website files to a branch called gh-pages. However, when publishing a GitHub user page, the files are pushed to the master branch.

By default, Nikola is configured to push to gh-pages. For my personal website, I need to change the deploy branch to master. I can do this in the conf.py file by uncommenting and modifying the line for the GITHUB_DEPLOY_BRANCH variable:

GITHUB_DEPLOY_BRANCH = 'master'

Customization

Customization and Mako tutorial

There is a great tutorial for customizing Nikola pages and using Mako at http://www.shisaa.jp.


Set the theme to bootstrap3 with a color scheme from bootswatch

First, install the bootstrap3 theme from the themes repository. In the end, I don't think this part is necessary.

nikola install_theme bootstrap3

Next, change the color scheme to darkly from bootswatch.com.

nikola bootswatch_theme -n custom_theme -s darkly -p bootstrap3

Finally, change the theme variable to custom_theme inside conf.py.


Changing bootswatch navbar elements

I am using the Darkly swatch in Nikola's bootstrap3 theme. This swatch has two menu bars; one is blue and the other green. When I installed this swatch, the default was set to green, but I wanted the blue one.

To change this, I had to change the base.tmpl file in themes/bootstrap3/templates/base.tmpl. (If you're using a virtualenv, you will find these inside the nikola site-packages data folder; see the end of this section.) In the Menubar section, I found the tag

<nav class="navbar navbar-inverse navbar-fixed-top" role="navigation">

and changed navbar-inverse to navbar-default, the name of the swatch element.

NOTE: In recent versions of Nikola (at least 7.3.1), the bootstrap3 css files were moved. In my nikola virtualenv, I now find them in ~/envs/nikola/lib/python3.4/site-packages/nikola/data/themes.


Navigation links

You can edit what navigation links appear by changing the NAVIGATION_LINKS variable in conf.py. See this section of the handbook: http://getnikola.com/handbook.html#configuration


Adding Disqus comments

I already had a Disqus account for my old site. Adding functionality for Disqus comments to my new Nikola-based site was incredibly simple.

In conf.py, I set the following two variables:

COMMENT_SYSTEM = "disqus"
COMMENT_SYSTEM_ID = "MY_SHORT_NAME"

The shortname for the Disqus site can be found using these instructions.


Redirects

One of my old pages was linked to by another website. For this reason, I wanted to preserve this URL so that the other site's owner didn't have to update the link himself.

Nikola makes it easy to setup a redirect in conf.py. I changed the REDIRECTIONS variable to the following:

REDIRECTIONS = [("notes/pgFocus.html", "/stories/notes/pgFocus.html")]

Code syntax highlighting and the orgmode plugin

To get code syntax highlighting with Pygments working, I needed to generate a custom.css file with pygments and add it to my theme's css files. I got this information from the following thread on the Nikola mailing list: https://groups.google.com/forum/#!topic/nikola-discuss/pRgevspZgvM

First, I found the available styles for highlighting with the command:

pygmentize -L style

After choosing a style, I generated the custom css with

pygmentize -S default -a .highlight -f html

and placed the output in custom.css. I placed this css file in <NIKOLA_ROOT>/themes/custom_theme/assests/css/. After this, highlighting worked on my site.


Teasers

To only include portions of posts on the index page, you have to set the INDEX_TEASERS variable to True. By default, only the RSS feed will include teasers.

I'm not currently sure how to implemement this with the orgmode Nikola plugin, however. I tried surrounding the reStructuredText .. TEASER_END in #+BEGIN/END_COMMENT brackets, but this did not work.


Adding MathJax support to all pages

Adding MathJax suppport involves inserting a link to the global MathJax server through script tags in the head tags of every page.

I can add this link by editing the following variable in my conf.py file:

EXTRA_HEAD_DATA = '''<script type="text/javascript" src="https://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML"></script>'''

(Note that you will have to replace any occurence of &lt; and &gt; to less-than and greater-than symbols above. For whatever reason org-mode will ALWAYS try to render these into HTML and I haven't figured out how to prevent this). After doing this, MathJax will automatically used to render LaTeX equations into math. Very nice and simple!


Jupyter Notebooks

Fixing the font color

Posting from Jupyter notebooks seems to sometimes have issues with styling. One problem I encountered is that the font color was too dark with my slate bootswatch theme. The font color for the Notebooks can be manually changed by editing the nikola_ipython.css file in the Nikola install.

This file is currently in ~/.venvs/Nikola/lib/python3.5/site-packages/nikola/data/themes/base/assets/css. I set it to #c8c8c8 for the Slate bootswatch theme.

div.text_cell_render {
padding: 0px;
color: #c8c8c8;
}

I also added the following tags to this file to bring the underline-on-hover effect back to links:

.rendered_html :link:hover {
text-decoration: underline;
}

Fixing the output font color

Output from code execution is black by default. I changed it to white by editing nikola_ipython.css and adding a color option to the element div.output_area pre:

div.output_area pre {
color: #FFFFFF;
font-size: 13px;
}

Inline LaTeX

To get inline LaTeX equations working, you need to tell MathJax to read \\( and \\) tags. To do this, edit your conf.py file and uncomment the default MATHJAX_CONFIG variable:

MATHJAX_CONFIG = """
<script type="text/x-mathjax-config">
MathJax.Hub.Config({
    tex2jax: {
        inlineMath: [ ['$','$'], ["\\\(","\\\)"] ],
        displayMath: [ ['$$','$$'], ["\\\[","\\\]"] ]
    },
    displayAlign: 'center', // Change this to 'center' to center equations.
    "HTML-CSS": {
        styles: {'.MathJax_Display': {"margin": 0}}
    }
});
</script>
"""

For some reason, single dollar signs still doesn't work, but the double-backslash parenthesis does, so use this when making inline LaTeX in a Jupyter notebook


Displaying HTML5 Video

The size of HTML5 video from a Jupyter Notebook on a mobile phone is horrible if you don't set the CSS manually; the video will pop out of its container. I changed the video tag in assets/css/all-nocdn.css (both inside the root directory and the output directory!) to the following so that the video filled the size of its container and did not pop out:

video {
  width:  100% !important;
  height: auto !important;
}

Errors

Duplicated definition of render_listings

Shortly after switching my GitHub user page from Jekyll to Nikola, I received the following error while running the command nikola github_deploy:

ERROR: Task generation 'render_site' has duplicated definition of 'render_listings:output/listings/index.html'
[2014-12-27T15:09:48Z] ERROR: github_deploy: Build failed, not deploying to GitHub

I deleted the cache and pycache directories and the doit database files after reading around the internet, but this didn't fix the problem. Ultimately, I deleted the listings folder which fixed it, though I'm not sure how good of a fix this is, since I may want to use the feature enabled by listings in the future. I believe that this feature is easy insertion of formatted code into webpages.