How to set up a Nikola-powered blog with multi-markup support

• TL;DR
• Context
• What is a static site generator and what's the difference with normal CMSs
  • Key Differences Between SSGs and Traditional CMSs
• Steps
  • 1. Install Nikola
  • 2. Create Your Nikola Site
  • 3. Configure Nikola
  • 4. Setting Up Version Control
  • GitHub vs. GitLab
  • Using GitLab
  • 5. Edit and Update Your Blog
  • 6. Link to Deployment Guide
• Conclusion
• Check the Handbook
• Check my other articles on nikola

TL;DR

This article guides you through creating a blog using Nikola, a static site generator that supports Markdown, reStructuredText, and Jupyter Notebooks. I'll use the Bootblog theme and detail how to host the code in a private repository on GitHub or GitLab, with a preference for GitLab. Deployment steps to Cloudflare are covered in a separate article (link provided). For editing, VSCode or PyCharm is recommended, though any text editor works.

Context

Nikola is a versatile static site generator that is perfect for researchers, educators, and bloggers who want to incorporate rich content like Jupyter Notebooks into their posts. It's Python-based, easy to customize, and supports various content types.

After extensive research and testing various static site generators, I chose Nikola as my blogging platform. While Nikola may not be as trendy as some newer generators that frequently pop up in tech articles, my priority was finding a tool that offered both stability and flexibility—qualities that are sometimes overlooked in favor of following trends.

Nikola stood out for me for several reasons:

• Stability : The project has been actively maintained for over eight years, indicating a mature and dependable platform.
• Flexibility : Written in Python, Nikola is particularly advantageous for those involved in DevOps and Data Science. It supports a wide array of formats and markup languages including AsciiDoc, Markdown, Jupyter Notebooks, and HTML and allows importing metadata and content also from several sources (WordPress, Pelican and others). Here you have a cheat sheet for some markup languages
• Extensibility : The availability of shortcodes and plugins enhances its functionality, allowing for a high degree of customization and integration. I've created some shortcodes myself for my personal use case
• Deployment Versatility : It can be deployed to virtually any platform, though I personally use Cloudflare Pages for its simplicity and performance.
• Version Control Friendly : The content being stored in plain formats in a Git repository (I use GitLab) means that it's not only secure but also highly manageable and version-controlled.

This combination of features makes Nikola an ideal choice for me (and I dare say for those who value a stable, extendable, and developer-friendly blogging environment).

What is a static site generator and what's the difference with normal CMSs

A static site generator (SSG) is a tool used to produce HTML websites by compiling source files written in various markup languages like Markdown or reStructuredText. Unlike traditional content management systems (CMSs) that dynamically build a page every time a user accesses it, SSGs generate (compile) all pages at once during development. This process results in a set of static HTML files which can be easily hosted and served.

Key Differences Between SSGs and Traditional CMSs

• Performance : Static sites generally load faster than their CMS counterparts because they consist of simple HTML files, eliminating the need to query a database or execute server-side scripts on each request.
• Security : With fewer moving parts and no database interactions, static sites are less vulnerable to common web attacks such as SQL injection and XSS (Cross-Site Scripting).
• Scalability : Hosting static files is straightforward and can handle high traffic with less overhead than dynamic sites.
• Cost : Static sites can be hosted on any simple web server or services like GitHub Pages and Cloudflare Pages often for free, reducing the cost associated with web hosting.
• Maintenance : Static sites require less maintenance since they don’t involve managing a server or database. Updates are made by regenerating and redeploying the site, rather than through an online interface. This means you don't need to update anything, and you may use an old version forever, so long it runs locally.

However, traditional CMSs like WordPress or Drupal offer advantages in scenarios requiring frequent updates, user interaction, or complex dynamic functionalities. They provide a user-friendly interface that allows non-technical users to easily manage content and make updates in real-time without touching the underlying code. And traditional CMSs are friendlier for a normal user.

Steps

Here's how to set it up on any major operating system and prepare it for hosting on Cloudflare.

1. Install Nikola

First, you need to install Nikola. It's Python-based, so ensure Python is installed on your system.

I recommend to use a virtual environment. I usually use miniconda. You can check the install instructions here.

Once you have Python installed (with or without a virtual environment) you need to install nikola.

pip install Nikola[extras]

2. Create Your Nikola Site

Generate your new Nikola site with:

nikola init mysite
cd mysite

3. Configure Nikola

Edit conf.py in your site directory to set up the Bootblog theme and enable support for Markdown, reStructuredText, and Jupyter Notebooks:

# Add bootblog to your theme
THEME = "bootblog"

# Enable support for Markdown, reStructuredText, and Jupyter Notebooks
COMPILERS = {
    "rest": ['.rst'],
    "markdown": ['.md'],
    "ipynb": ['.ipynb']
}

4. Setting Up Version Control

GitHub vs. GitLab

GitHub: - More popular and widely used. - Integrates well with other tools and services. - Provides free private repositories with a limit on collaborators.

GitLab: - Offers free private repositories with unlimited collaborators. - Includes built-in CI/CD features. - I prefer GitLab for its comprehensive DevOps capabilities.

Using GitLab

Create anew account on https://about.gitlab.com/pricing/ on the free plan and then create a new private repository in GitLab and push your site:

git init
git remote add origin [your-gitlab-repository-url]
git add .
git commit -m "Initial commit"
git push -u origin master

5. Edit and Update Your Blog

For updating your blog, use VSCode or PyCharm, though any text editor will suffice. These IDEs offer great support for Python and Markdown, enhancing the blogging workflow.

6. Link to Deployment Guide

For steps on deploying your blog to Cloudflare, refer to my detailed guide here: Deploying Nikola Site to Cloudflare.

Nikola has a deploy command, but I prefer to use the Cloudflare pipeline to auto-publish on git push.

Conclusion

Setting up a Nikola blog is straightforward (but requires more steps than setting a blog on WordPress.com). It supports a variety of content formats and can be easily integrated into modern workflows and tools like GitLab and Cloudflare for a robust blogging setup. The best of it is that you are not dependent on a specific platform.

Check the Handbook

The handbook on https://getnikola.com/handbook.html is great and has almost everything you might need for your blog.

Check my other articles on nikola

I've writen some articles about nikola that might interest you after this one

• 2024-02-01 How to Create a 'Next/Previous' Article Navigation in Nikola Static Site Generator _ 4 min read.
• 2023-12-12 Introducing my Custom Shortcodes for Nikola Static Site Generator _ 3 min read.
• 2023-12-07 How to Deploy a Nikola Static Site on Cloudflare Pages: A Step-by-Step Guide _ 5 min read.
• 2022-12-29 How to add a table of contents (TOC) to a markdown post or page to nikola ssg _ 1 min read.