Setting Up Nikola on Windows 10 with Visual Studio Code

Published

Comments

Initial Install

The very first step will be installing Python from https://www.python.org/. I am using version 3.8 as of the date of this post. Once Python is installed, open PowerShell as an administrator.

Update pip to the latest version:

python -m pip install -U pip

Then install virtualenv:

pip install virtualenv

At this point you can close PowerShell, at least temporarily. The next item to install is GIT, assuming you are going to be using it for version control (which I highly recommend). https://git-scm.com/download/win and download/install the latest package.

Next up, you want to head over to https://code.visualstudio.com/ and download/install the latest version of Visual Studio Code. Once it is installed, open it and install the extensions for Python (ms-python.python), PowerShell (ms-vscode.powershell), and Mako (tommorris.mako). These are optional, but add some command highlighting features that are rather nice.

If you don't all ready have it, I would recommend installing Windows Subsystem for Linux as that is the easies way to get rsync which will be used to deploy the final website to a server. See https://docs.microsoft.com/en-us/windows/wsl/install-win10 for install instructions. I tend to use Ubuntu as the distribution, but you can use any you are comfortable with.

Now that the pre-requisites taken care of, we can start working on the actual website. Open up a new PowerShell terminal and navigate to your home directory:

virtualenv nikola-env
cd nikola-env
.\Scripts\activate.ps1
pip install "Nikola[extras]"
nikola init new-website
cd new-website
git init

Now create a file names .gitignore in the directory new-website and place the following in it:

.doit*
cache
__pycache__

You can now continue setting up your git repository:

git add .
git commit -m "Initial commit of new website"

You will probably now want to go to GitHub (https://github.com/) and create a new repository (for the rest of this document we will refer to it as git-website-repo). Do not choose the option to initialize the repository on the website. You will, instead, want to follow instructions for "Push an existing repoository". This can be accomplished by:

git remote add origin https://github.com/$username/get-website-repo.git
git push origin master

You can get a more complete rundown of this process at https://help.github.com/en/github/importing-your-projects-to-github/adding-an-existing-project-to-github-using-the-command-line

Now, whenever you want to do something involving Nikola, you should use a file browser to navigate to the directory nikola-env, open a PowerShell window there, and issue the command .Scriptsactivate.ps1. After that you can use all standard Nikola commands, as documented in the getting started guide and the handbook (https://getnikola.com/getting-started.html and https://getnikola.com/handbook.html)

Nikola Extensions

For the time being, I am only really using 2 Nikola extensions, sidebar which is in the main repository and filetreesubs by felixfontein (https://github.com/felixfontein/filetreesubs/). Install them:

nikola plugin --install sidebar
pip install filetreesubs pyyaml

You will now need to make a directory in the main site directory themesyour_theme_namemessages and create a file messages_en.py in that directory. Its contents should be:

MESSAGES = {
    "Recent Posts": "Recent posts",
    "Archives": "Archives",
    "Categories": "Categories",
    "Tags": "Tags",
}

Obviously, customize this to your liking. Next create a file in the root directory called subs-config.yaml and put the following code in it:

source: output
destination: final
substitutes:
'.*\.html':
    '<!-- include:sidebar-en -->':
    file: sidebar-en.inc
create_index_filename: index.html
create_index_content: |
<!DOCTYPE html>
<html lang="en">
    <head>
    <title>there's nothing to see here.</title>
    <meta name="robots" content="noindex">
    <meta http-equiv="refresh" content="0; url=..">
    </head>
    <body>
    there's nothing to see here. go <a href="..">here</a> instead.
    </body>
</html>
encoding: utf-8
doit_config:
dep_file: '.doit-subs.db'

Finally, create two script files in the root site directory, I have named them build.ps1 and serve.ps1. Their contents should be as follows:

build.ps1:

..\Scripts\activate.ps1
nikola build
filetreesubs subs-config.yaml

serve.ps1:

..\Scripts\activate.ps1
nikola --conf=final-conf.py serve

And create an alternate config file for Nikola, named final-conf.py also in the root directory:

# -*- coding: utf-8 -*-

from __future__ import unicode_literals

OUTPUT_FOLDER = 'final/'

DOIT_CONFIG = {
    'dep_file': '.doit-final.db'
}

(Many thanks to felixfontein for his example site on which this is based!) Now, if you run the build.ps1 script it will build the site and do substitutions as detailed in the subs-config.yaml file. Running serve.ps1 will start the server that comes with Nikola but direct it to the files that have had substitutions applied.

A final configuration option that will speed things up is to create a file .vscodetasks.json with the following code in it:

{
    // See https://go.microsoft.com/fwlink/?LinkId=733558
    // for the documentation about the tasks.json format
    "version": "2.0.0",
    "tasks": [
        {
            "label": "Build and sub site",
            "type": "shell",
            "command": "./build.ps1",
            "group": {
                "kind": "build",
                "isDefault": true
            }
        }
    ]
}

This will allow you to launch the build task from within Visual Studio using the command Ctl-Shft-B.

Nikola Scripts

PowerShell scripts for building website, deploying website, new post, etc

Visual Studio Configuration

Make a file called settings.json in the folder .vscode in the same folder as your vs-workspace.code-workspace file and put the following contents into it:

{
    "restructuredtext.confPath": ""
}

Also edit your vs-workspace.code-workspace file and include the following:

{
    "folders": [
        {
            "path": "."
        }
    ],
    "settings": {
        "files.associations": {
        "*.tmpl": "mako"
        },
        "editor.wordWrap": "on"
    }
}

This will turn word-wrap on all the time (very helpful when you are editing a long text document on a small screen) and, more importantly, turn on mako code highlighting for .tmpl files (since Nikola uses a non-standard extension for its Mako templates).

Comments

Comments powered by Disqus