# 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:
.. 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.

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

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 {
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.