integrate isso into hugo
Isso Server Setup
Please refer to1 for questions on how to setup isso on your server. For FreeBSD you might wanna use my port2 I did. It is not available to the public, but it will in the future. Not sure if I’ll setup my own git server or if I simply use github. We will see. The basic server and client side configuration of isso is documented here3. Some part of client side configuration can be found here
Hugo4
From the website itself:
Hugo is one of the most popular open-source static site generators. With its amazing speed and flexibility, Hugo makes building websites fun again.
To install hugo please refer to5. Id recomment the extended version. It has some more features you might profit from. If you are building on FreeBSD from ports you should enable the option EXTENDED=on which is disabled by default.
Setup
After installing hugo you may want to create your first side called “mynewside”. This is easiely done by typing into the commandline:
$> hugo new site mynewsite
This creates a new skelleton structure you can work on. The first next step would be to edit the config.toml file. Here you define all the global options for your new hugo site.
There are two parameters I added to my side configuration to control the appearence of isso on my website. The first one is in the config.toml file:
[params]
enableIsso = true # enable commenting with isso
This gives me the freedom of enabling or disabling the isso comments section on a global base for all of my pages. Then I didnt want to have comments on all pages. So I introduced a parameter comments on a page/post basis.
---
author: "René Thümmler"
title: integrate isso into hugo
date: 2019-09-12
comments: true
---
I simply set it to true if I want to allow adding comments and unset (set it to false) otherwise. Only if both parameters are true comments are enabled.
Theme
I use a theme called hermit6 for my site. So all the integration stuff is very related to the structure of this specific theme. If you are using a different theme you might have to tinker around to find the right integration setup.
The themes are installed as subfolders in the folder themes inside your sitefolder. The themes have the same folder strukture as you side has. So if you want to override anything of the theme all you have to do is to copy the files from the theme folders into your site folder and edit. Please DONT change anything inside the theme folder unless you know what you are doing.
All the basic layout is done in the folder layouts. All the custom css stuff should go into the static/css folder.
Layouts
There are two files we need to adjust. The first post/single.html is the one that determines the isso client interface.
posts/single.html
Copy the file themes/hermit/layouts/posts/single.htmlfrom the theme folder into your site folder layouts/posts/single.html. Now we are going to adapt this template file. On the top look for the header section. Should look something like this on default:
{{ define "header" }}
{{ partial "header.html" . }}
{{ end }}
We will add the isso client interface here with the right configuration. I have customized some of the css of Isso, so thats the cause to add data-isso-css="false". See css to read more about that.
{{ define "header" }}
{{ partial "header.html" . }}
{{ if (and .Site.Params.enableIsso .Params.comments) -}}
<script data-isso="{{ .Site.BaseURL }}isso/" src="{{ .Site.BaseURL }}isso/js/
embed.min.js" data-isso-css="false"></script>
{{- end -}}
{{ end }}
Basically we are checking if the parameters to enable commenting are set and if so we add the isso embed.min.js script to the page. The parameter data-isso="{{ .Site.BaseURL }}isso/" depends on your isso configuration. I configured isso to sit on https://www.example.com/isso/.
This was number one. For the second please move on…
partials/comments.html
This is the one it draws the comment section onto your page. It is very basic and does only load the default hugo Disqus template.
{{- if .Site.DisqusShortname }}
{{ template "_internal/disqus.html" . }}
{{- end }}
Just empty the complete file and add the following three lines.
{{- if (and .Site.Params.enableIsso .Params.comments ) }}
<section id="isso-thread"></section>
{{- end }}
You wont be able to see comments with your localhost hugo server. If you want to add this you need to follow1
static/css/isso.css
I needed to adjust the isso.css for matching my page layout and make the comments readable. You dont need to change the css file installed by your package manager. Just copy over the isso.css file int the folder static/css and adjust it. To apply the css to the site add the css file to your config.toml here:
[params]
# Add custom css
customCSS= ["css/isso.css"]
Summary
So once Isso was fully running it was very easy to add it to my hugo site. The setup gives a good control over what page is commentable and whats not. The needed customization is done on a very minimum of small changes.
Thats primarily all you need to do. Easy isnt it? Now you can run hugo to build your productive pages and upload them to your server and you are done. If you have any comments please let me know.
Happy commenting…
Need a printer friendly page? Get it here
comments