Why and how i created my personal static blog (and why you should do the same) [Part 2]

Design phase

Few weeks ago, i was looking for a new challenging project to drive my nights and since the idea of creating my small personal website was bouncing in my head since months, i decided to dive into this. My concept of personal website is not a webapp or a complex website, are just few pages, arbitrary designed and styled, which present yourself and tells something more about you. For IT people for example, it can be another evaluation parameter for recruiters or another media to reach other people with hands in your topic to start collaborations. Due to this, the website does not need to be that big or animated but on the contrary it may be composed mainly by written text and eventually by a bunch of pictures. Of course, anyone can design the website as he wish but here comes into account creativity and originality, for example, one might implement a blog section inside the site.

My design phase (pen & paper, old style) ended up in the need of 5 pages to present myself plus a blog section, maybe later.
I was interested in learning something new, python speaking even better, so i ended up in Nikola a SSG written in Python which seems really interesting. You can decide upon several popular SSG such as Gatsby, Hugo and Jekyll which use other languages such as Go or Javascript

Static site generator

The purpose of an SSG is to convert normal written text files, in browser-readable HTML/CSS files which represents our final webpages, so is actually a tool which compile text files and returns the associated html pages. Every SSG supports certain text formats, but usually input pages are written in .rst or markdown ( my favorite one!)

In Nikola, the settings are described in a config file, which is itself a python file (using dictionaries for storing entries) where this represent the console for defining the tool behavior. You can setup pretty everything, from the compiler, formats,pages, hyperlinks, languages and so on. Nikola comes also with some additional plugins and themes, but if it’s true that i never used the former, i’ve used the latter and they are easy to install.
Additionally, Nikola supports Mako themes, which is a template library written in python.
Since we are dealing with python, the package manager pip is enough to handle everything.

Nikola SSG

My tech stack and what you will need:

  • Kubuntu 18.04 [Optional]
  • Python3 + pip
  • Git/ Github account
  • Atom/Visual Studio Code

After the installation process the first step is to create a folder where init the project in order to let Nikola creating all the additional files it needs to work properly. Once created the folder, type:

nikola init mysite

Now inside the folder you have an active Nikola environment workspace to play with.

The /page folder will contain the source files of your pages.
The /output folder will contain the compiled and generated output pages
The /post folder will contain your blog posts, if any.
You can start by creating a new page or new post, moving to the /page/posts folder and using:

nikola new_page -f markdown

nikola new_post -f markdown

will create a new page in markdown format. Follow the wizard to fill metadata and that’s it.
To display the first generated page we need to tell Nikola to build the entire sites, and we do this using:

nikola build

On the output folder you will find your generated html page!
Nikola also gives the possibility to open the site on localhost, typing:

nikola serve -b

and ….

Et Voilà! Les jeux sont faits

You actually have build and served your small website in localhost.
Now, take a look at the structure of Nikola created project folder:

I’ve marked with * the main folders where i’m going to focus on and spend a bit on them,

Files:

This is addressed to contain additional files you wanna serve on your site.

Galleries:

Folder dedicated to store galleries as a dictionary format. For simple images in your post or pages the default folder is /images which anyway need to be created on the root folder using:

mkdir /images

Both galleries and images options can be easily found in the cnfg file.

Output:

This is dedicated to store the generated file by the build operation in Nikola, where they represents the desired html files we are looking from our SSG. Depending on which settings (Prettyurls) you set up on the config file, each page can have an own folder named with the slug of the file,with the relative index.html file inside, or if prettyurls is disabled, pages will be simply displayed on the root of the output folder. Personally i prefer to have prettyurls set on True.

Pages

Remember the command for creating a new page? This is where the new page files are placed.

Posts

If your site has blog enabled, this is the folder where new posts are stored.

Themes

I will not cover the part relative to templates and themes in Nikola since is pretty straightforward and intuitive and it all depends on which theme you install for your website. Anyway, this is the folder where themes will be placed and where you can find CSS and JS files to edit.

Keep in mind that the build command will scan the pages and posts folder to produce your output files, so every time a new page/post is created you need to rebuild your site again and the results will appear in the output folder!

Config file

For tuning and setup Nikola’s parameters, we need to access and read a bit of the configuration file called:

conf.py

This is a sort of dictionary where the entries are the Nikola parameter and the values are the parameter we are going to set.
For example, these are the entries reserved to specify the directory and the kind of file Nikola need to scan when doing the build operation.

These entries allows to tell Nikola how we want to handle our pages and posts. As a matter of fact, in PAGES we specify first the input folder where scan for files and which type of file it needs to search for.

The second parameter refers to the sub-folder of the output folder where Nikola need to store the resulted/compiled pages. For consistency with what i told you before i let Nikola creating pages on the root of my output folder, but that’s up to you.
The third parameter specify the template which need to be used for each page or post, usually story.tmpl is the default one for pages whereas the post.tmpl is the one used to display posts.

Another interesting option is the INDEX_PATH which as stated in comments, indicate the folder where the compiled blog posts will be stored inside the output folder.
Specifying the INDEX_PATH pointing to another folder instead of the root output folder provide us a simple way to differentiate the two indexes file and let the static site and the blog section coexists. This is may seems a little confusing and hard to get, but you will understand better when you’ll practice a bit on yourself.

The last useful voice i want to introduce is the one relative to the menu for displaying your pages. This feature is again defined in the config file in the NAVIGATION_LINKS section:

Each line represents the path to your index html page and the name it will appear on the menù. Pretty easy isn’t it?

Anyway, Nikola is highly customizable with many more available options and a wide rang of plugins, so i’m sure you can find almost eveything you need to setup your space.

Deploy

When you are satisfied with what you built on local, it’s time to share your efforts to the world deploying your local files.
You will find so much about how to deploy a static site, since you can use almost any current cloud provider or many other solutions, but i’ll go trough my deploy process and why i opted for this.

First of all, let me reminds you that while i was designing this side project, one of the requirements for my site was to be completely CI/CD compliant in order to automatically deploy from everywhere with very few efforts.

The picture show a bit the whole lifecycle of the development, from the build on local machine to the deploy to a central repository versioning system such as Github Pages and how to achieve HTTPS and CDN features placing afterwords a cloudflare layer. Let’s move to a deeper view of each step for a better comprehension.

Step 1: Setting up the repository

Create a GitHub repository which contains the files of the site we want to serve (such as our HTML pages). Github Pages provide a free space for static sites only if you host file on Github on a special repository which must be named as :

your_github_username.github.io

Once done this, on the top page of your created repo you should see something like:

git clone https://github.com/your_github_username/your_github_username.github.io.git

copy this url, open the output folder of your Nikola project, open a terminal window and type inside:

git init

and then

This will hook your local folder to the remote SVN repo, and will allows us to commit from anywhere.
To execute the first deploy, from the root of the output folder type:

if you open the browser and type http://your_github_username.github.io your website should appear.

Every time we recompile our pages, we can simply push trough git the contents of the output page and the website will change consequently.

Step 2.1: Purchase a first level domain (Optional)

Even if we are dealing with a quite simple website which probably will not handle anything monetary, i do not like 3rd level domains at all and i purchased a custom domain to be used for addressing my site.
I got mine from Namecheap.com which imho is very good and cheap but you can choose any registrar you want. If you do not bother to have a 2nd-level-domain and you are fine with the 3rd level domain, you can jump to step 3, otherwise go ahead in this article.

Once you have your custom domain, you have to login to your registrar and adds these dns (A record) for your website, pointing the github HTTPS domain name servers

and then open the settings tab on your github repository and add the custom domain you chose in the Pages section. You can also enable HTTPS from the Enforce HTTPS section on the same settings page. With this step you are basically saying to your first level domain to forward the dns requests to the github domain name servers.

Step 2.2: Add a CNAME file to your repository

In order for Github to accept traffic from a custom domain, we need to create a cname file in the repository containing the custom domain name. Hence, open your git output folder and type:

echo “www.mypurchasedcustomdomain.domain” > CNAME

add to the staged files and push it to github.

Step 2.3: Add cloudflare to provide statistics

Is not properly clear if Github pages provides HTTPS for custom domain, however it does not provide any kind of statistics or analytics about your site. This is why i added a CDN to handle the requests to my website, which is totally free and is a further shield against attacks, and it allows to leverage the whole power of CDN replications and caching for further decrease time response latency.

First of all, sign up to cloudlfare is cheap and really fast, then add your website (the 2nd level version) to your personal profile panel, this is completely free even if it has few limitations.

In this case, heading back to the step 2.1 we will have to set in the registrar the cloudflare name servers, and let cloudflare handle the DNS records for us, so the 4 A records will be added to our website settings page in cloudflare account.

Furthermore, from the crypto tab on CF we can set Flexible or Full encryption, where the former means that the communication is encrypted only between the client and CDN servers while the 2nd one ensure a FULL encryption but without certificate validation since github does not provides it. Be aware to not choose the FULL STRICT since it requires an SSL certificate on the origin server and unfortunately it’s not our case.

Final thoughts

From now on, everytime you want to publish a new blog post or you need to edit any of your page you can just launch the Nikola tool to rebuild the html pages, and push them remotely to your repo. This change will be automatically propagated to your CDN and served to the external world.
Concluding, let your site being handled by a CDN such as cloudflare will also provide you some analytics, monitoring features and dashboard where you can start to evaluate your website in terms of visits and catchyness.

I’m currently using this configuration since months and it works smoothly and with a very low latency. I’m planning to build my own template and add a blog section, in case, i will update this post with additional features!

I’m pretty sure you will get your feet wet in Nikola easily since it’s a quite straightforward tool which sufficient documentation provided to easily move your first steps on this tool. Additionally, lots of sources provide additionally instructions on how to deploy a static site using whatever technology.

Hope this helps!

Sources:

https://blog.cloudflare.com/secure-and-fast-github-pages-with-cloudflare/

https://www.tobias-schwarz.com/en/posts/8/#private-git-repository-on-bitbucket

https://medium.com/@kent/how-to-host-your-blog-using-pelican-amazon-s3-and-cloudflare-300e718943f8

https://codebushi.com/hosting-your-static-website/

Computer engineer with a keen interest in security, blockchain and distributed systems

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store