Starting a Personal Blog with Nikola

Creating a custom look for Nikola site

There are some ready to use themes for Nikola, but really none of them corresponded to what I wanted to create. The good thing is that you don't need to create a new theme from scratch, but you can inherit it from an existing theme. All you need to do is just copy files you want to modify from an existing theme into a new folder inside [themes]. Then the folder tree for the new theme should look similar to this...

[themes]
    [mytheme]
        [assets]
            [css]
                bootstrap.css
                bootstrap.min.css
                custom.css
                nikola_ipython.css
                theme.css
            [img]
            [js]
                custom.js
        [templates]
            base.tmpl
        bundles
        parent

I decided to create a theme based on Bootstrap3 framework, which must be specified in the file parent. Basically, the look of the site based on Bootstrap is given by file with CSS styles named bootstrap.css. I really don't recommend to modify this file itself since it's a really huge file (over 6000 lines). But there is this useful online application http://bootstrap-live-customizer.com which enables you to play with all the colors and styles and then generate the desired CSS files. For any later fine-tuning, I've added files custom.css, theme.css to override existing styles and add some new ones to make things better arranged. If you are using Jupyter files, specify their styling by nikola_ipython.css.

Well, we have done some styling, but how to change the layout of the site? That's also easy to do with Nikola. You can use some template files from an existing theme and copy them into folder [templates]. Especially base.tmpl is essential, because it defines the actual layout for the whole site. Also, there are other templates to specify the layout for posts, indexes, etc.

Markdown vs. reStrtructuredText

Before starting to create the actual content for the new site, you need to decide which format of source files to use for post and pages. Nikola supports lots of these textual formats, but probably the most useful is Markdown (.md) or reStructuredText - reST (.rst). I've been hesitating a lot which one would be better for my needs. Even-though I'm writing this post using reST, I'm still not so sure which one is better. Let me try to summarize pros and cons for both formats...

Markdown

• This format seems to be more popular and is used by lots of web applications.
• You can directly insert HTML code without any redundant directives.
• Syntax for hyperlinks is really simple e.g. [Markdown](https://en.wikipedia.org/wiki/Markdown)

• Markdown eats every second backslash on output. So, if you want symbol \\ for break-lines in LaTeX math formulas, you need to type \\\\ in Markdown, which is really annoying and redundant work.
• I haven't found any elegant way how to insert styled images and figures, apart of inserting plain HTML code.

reStrtructuredText

• reStrtructuredText seems to be the default and preferred format for Nikola.
• No problem with double backslash \\ which is nice for inserting LaTeX math.
• There are lots of useful directives for inserting code-blocks, images, figures, etc.

• The official documentation for reStructuredText is rather poor.
• I didn't find a way how to explicitly specify a section header (h1, h2, ...). Header levels seem to be just derived from the structure of document.
• To insert plain HTML, you need to use a special directive.

MathJax vs. KaTeX

There are basically two options for rending math. MathJax is the default option for Nikola and also for Jupyter notebooks. It has nice render quality and I haven't faced any serious problems using it. The only problem seem to be quite slow rendering time, and also the need to re-render all math after reloading the page.

On the other side, KaTeX seems to be much faster to render, and there is no obvious re-rendering after page reloading. The font quality is also nice or maybe even better than MathJax. But I have faced serious problems that made me give up using KaTeX for my site. For example, I wasn't able to insert inline math using standard $..$ directive, and TeX environments produced by Nikola are also not supported. All this makes KaTeX still too immature for usage with Nikola and Jupyter.

Deploying Nikola Site to GitHub

When you are happy with the new site, you just need to choose a webhosting service. There are really lots of options, because Nikola generates static pages, thus doesn't require to run any server-side scripts. Finally, I've chosen GitHub, because it offers free space for static pages and doesn't contain any annoying commercial ads.

GitHub is originally a service for version control system called Git, and the possibility for hosting static pages is quite new. Therefore, to use this service, one need to get familiar with the Git protocol first. This makes things a bit more complicated in contrast to other webhostings, where you can just use FTP for uploading your site. On the other side, if you are interested in programming, learning to use Git is definitely worth of it.

So, to deploy a new site to GitHub, first you must have a GitHub account. Then, create a new repository named after the site URL - in my case I created a repository named meshlogic.github.io, because my user name is "meshlogic". Now, we can do some basic customization in the Nikola config file conf.py.

GITHUB_DEPLOY_BRANCH = 'master'  # Deploy the Nikola output to the master branch of your repository
GITHUB_SOURCE_BRANCH = 'src'     # Deploy Nikola project source files to src branch of your repository
GITHUB_COMMIT_SOURCE = True

When everything ready to deploy, open console in the path of the Nikola project and start using Git. Of course, you need to have Git installed on your computer and available from command line.

$ git config --global user.name "USER_NAME"
$ git config --global user.email "USER_EMAIL"
$ git init
$ git remote add origin https://github.com/meshlogic/meshlogic.github.io.git
$ git pull origin master --allow-unrelated-histories

Note that git init creates a hidden folder [.git] inside your project folder. git remote makes a branch named "origin" linked to your GitHub repository specified by its URL. git pull seems to be necessary to run even when your repository is still empty (at least in my case it was).

Finally, run a simple command nikola github_deploy, which commits the output and pushes it to GitHub. Now if everything went right, your site should be running online :)