How to create a Hugo website without a theme

2023-02-14T00:00:00+00:00

Since converting this website to the Hugo static site generator a couple of years ago, I’ve used Hugo for lots of other projects. It’s blazing fast, simple, and makes small website projects much easier.

One of the sites I’ve built with Hugo is a simple site to keep notes for my university classes. Hugo’s documentation tends to assume you’re using a theme, but for such a basic site using a theme would add unnecessary complexity I didn’t want to deal with. So, in this article I’ll show you how to create a site without a theme.

Creating a site

First, install Hugo.

If you want to use SCSS, as I do in the example below, make sure to install the “extended” version of Hugo.

Then, run the following command to create a Hugo site:

$ hugo new site notes

Get into the new notes directory, and let’s edit the config file:

baseURL = "http://example.org/"
languageCode = "en-us"
title = "Notes"
pluralizelisttitles = false

Other than the title, the only thing I changed here is disabling pluralizelisttitles. Hugo expects you to name your sections something singular (e.g., put your blog posts in a post directory), then automatically pluralizes the title when listing content in that section (Posts). I prefer the singular for my university class names (Math 112 instead of Math 112s and so on).

Layout

For a site as simple as ours, we only need a few layout files. Create a directory called _default in the layout directory, to put three files in: baseof.html, list.html, and single.html. We’ll go through each of these files and what it does.

If you need to add different templates for different sections, or if you’re curious about why we use _default here, see Hugo’s lookup order docs.

baseof.html

Every page on the site looks for a base template, which we provide in baseof.html. We’ll use it for the HTML boilerplate — <!doctype html>, the <html> tag, the <head> tag with some logic for what to load, and the <body> tag with a block template for the page content.

<!doctype html>
<html>
  <head>
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <title>{{ or .Title .Site.Title }}{{ if ne .Kind "home" }} | {{ .CurrentSection.Title }}{{ end }}</title>
    {{ $style := resources.Get "scss/style.scss" | toCSS | minify }}
    <link rel="stylesheet" href="{{ $style.RelPermalink }}">
  </head>
  <body>
    {{ block "page" . }}{{ end }}
  </body>
</html>

list.html

The list template defines the layout for section list pages. Sections are defined by directories in the content folder.

Read more about Sections in the Hugo docs.

{{ define "page" }}
<article class="container">
  {{ if ne .Kind "home" }}
  <a href="{{ .Site.Home.RelPermalink }}">Home</a>
  {{ end }}
  <h1>{{ .Title }}</h1>
  {{ range .Sections }}
  <h2><a href="{{ .RelPermalink }}">{{ .Title }}</a></h2>
  <ul>
    {{ range .Pages }}
      <li>
        <a href="{{ .RelPermalink }}">{{ or .Title .RelPermalink }}</a>
      </li>
    {{ end }}
  </ul>
  {{ end }}
  <h2>Other</h2>
  <ul>
    {{ range .RegularPages }}
      <li>
        <a href="{{ .RelPermalink }}">{{ or .Title .RelPermalink }}</a>
      </li>
    {{ end }}
  </ul>
</article>
{{ end }}

Here’s a breakdown of what’s going on:

We define the page block we saw in the base template.
If we’re not on a home page, we show a link to home.
We range through every subsection of the current Section, listing all the pages for each.

Note that in Hugo, everything is a Page, of varying types (like Section). A Section can have multiple subsections as well as Regular Pages, which are just Markdown files with some front matter. This allows us to list direct subsections alongside the Regular Pages for each section, while listing non-section Pages in our “Other” section. You can read about all the available Pages variables in Hugo’s docs.
Then, we list the Regular Pages of the current section.

single.html

{{ define "page" }}
<article class="container">
  <a href="{{ .CurrentSection.RelPermalink }}">Back to {{ .CurrentSection.Title }}</a>
  <h1>{{ .Title }}</h1>
  {{ .Content }}
</article>
{{ end }}

This one’s simple:

Define the same page block — remember, the list and single templates both extend from the same baseof template.
Provide a link back to the current Section’s list page.
Get the title from the page’s front matter.
Show the content (here that means everything except the front matter) run through a Markdown parser.

Styling

I prefer to style with SCSS, which Hugo supports with Pipes.

Because I’m using SCSS, I’ll put my styling in the assets/scss directory (you’ll need to create it). If you want to use plain CSS, you could put it in a static/css folder — everything in static is copied to the build folder, preserving the existing structure. Then, you can link to it normally, without the Hugo Pipe I use for SCSS parsing.

To keep it simple, my style.scss is less than 100 lines long. Here’s part of it:

$paradise-pink: #EA1F4B;
$paradise-pink-light: #EF5778;

html {
  font-size: 62.5%;
}

body {
  font-size: 1.6rem;
  line-height: 1.3;
}

h2, h3, h4, h5, h6 {
  margin: 3.8rem 0 .6rem;
}

h1 {
  font-size: 3.2rem;
}

h2 {
  font-size: 2.5rem;
}

p, ul, ol {
  font-size: 1.8rem;
  margin: 0 0 .8em;
}

a {
  text-decoration: none;
  color: $paradise-pink;

  &:hover {
    color: $paradise-pink-light;
  }
}

article {
  padding: 2rem 1rem;
  max-width: calc(44em + 2rem);
  margin: 0 auto;
}

See Aleksandr Hovhannisyan’s article for a good explanation of setting the html font size to 62.5%.

Content

As I mentioned earlier, Hugo’s sections are defined by directories in the content directory. Here’s what my notes look like after I organize them by university semester:

└── content
    ├── _index.md
    ├── winter-2022
    │   ├── _index.md
    │   ├── cs-235
    │   │   ├── _index.md
    │   │   ├── lecture-9.md
    │   │   ├── lecture-10.md
    │   │   └── quicksort-getting-started.md
    └── winter-2023
        ├── _index.md
        └── ec-en-240
            ├── _index.md
            └── lecture-01-09.md

The _index.md files are used to add frontmatter and content to list pages. In this site, I just use them to name my sections. If you don’t specify anything, it’ll use the directory name.

---
title: Electrical and Computer Engineering 240
---

And here’s one of those Markdown files; I’ll use lecture-9.md as an example:

---
title: "Lecture 9"
date: 2022-02-01T09:39:28-07:00
katex: true
---

`sumto()` function: \\(\sum_1^i i\\)

Can be done recursively: `sumto(5) = 5 + sumto(4)`

Recursive function rules:

1. have a base case (a case to stop the recursion)
2. the recursive function must progress toward the base case (otherwise it will recurse infinitely)
3. trust the induction
4. Make sure that it won't make too many recursive calls
5. Never run the same arguments of the recursive function twice. Caching may help

You may notice a katex: true key & value in the front matter. That’s an optional extra goody I’ve added, which we’ll go over soon!

Building and using the development server

To deploy the site to the build directory, run:

$ hugo

Or to use Hugo’s development server (one of its strongest features, in my opinion), go to the base site directory and start it:

$ cd notes
$ hugo serve

It will give you a localhost address with a port (1313 unless it’s taken by another service) that you can open in your browser of choice.

Now you should have a shiny new Hugo site to work with, no theme required!

Here’s the list page template in action:

And the single page template, plus our content file:

Adding KaTeX support

KaTeX is a lightweight JavaScript TeX implementation. I use enough math in my notes as an engineering student that I wanted an easy way to show math notation.

Although I use math notation pretty often, I wanted to only load the JavaScript when necessary. For this, I set a front matter variable (katex), and render a katex.html partial in the site’s <head> if it’s there.

Add the following to baseof.html, in the <head> tag:

{{ if .Params.katex }}{{ partial "partials/katex.html" . }}{{ end }}

The partial function takes a path relative to layouts, so partials/katex.html finds the file in layouts/partials/katex.html.

Put the following in layouts/partials/katex.html:

<link rel="stylesheet" href="/katex/katex.min.css">
<script defer src="/katex/katex.min.js"></script>
<script defer src="/katex/contrib/auto-render.min.js" onload="renderMathInElement(document.body);"></script>

I downloaded KaTeX myself, which is nice for serving your own content while offline. But you could easily modify this partial to use CDN-hosted files.

If you host the files yourself, just download and move the necessary files to static/katex. You only need to keep a few files out of the ones KaTeX ships with:

└── static
    └── katex
        ├── contrib
        │   └── auto-render.min.js
        ├── fonts
        │   ├── KaTeX_AMS-Regular.ttf
        │   ├── KaTeX_AMS-Regular.woff
        │   ├── KaTeX_AMS-Regular.woff2
        │   ├── KaTeX_Caligraphic-Bold.ttf
        │   ├── KaTeX_Caligraphic-Bold.woff
        │   ├── KaTeX_Caligraphic-Bold.woff2
        │   ├── KaTeX_Caligraphic-Regular.ttf
        │   └── … (more fonts here, not shown to save space)
        ├── katex.min.css
        └── katex.min.js

Remember that the contents of static are directly copied to the build directory, so you don’t need to include static/ when referencing them in your templates.

Now we can turn on the katex switch and use math notation! The auto-render extension will, by default, look for blocks denoted by \$ \$, or $$ $$ for bigger symbols and centered.

Let’s make a new file in content called katex-test.md:

---
title: "Some math notes"
katex: true
---

\\(
\text{A system of } m \text{ equations in } n \text{ variables:}\\newline
a_{1,1}x_1 + a_{1,2}x_2 + ... + a_{1,n}x_n = b_1\\newline
a_{2,1}x_1 + a_{2,2}x_2 + ... + a_{2,n}x_n = b_2\\newline
\vdots\\newline
a_{m,1}x_1 + a_{m,2}x_2 + ... + a_{m,n}x_n = b_m
\\)

This one's in "display mode" — centered, with larger symbols:

$$
\begin{bmatrix}
a_{1,1} & a_{1,2} & ... & a_{1,n} & \mid b_1\\\\
a_{2,1} & a_{2,2} & ... & a_{2,n} & \mid b_2\\\\
\vdots\\\\
a_{m,1} & 1_{m,2} & ... & a_{m,n} & \mid b_m
\end{bmatrix}
$$

The highlighting here works fine, but it doesn’t work exactly how I’d expect. Markdown should always render first, then KaTeX should search for delimiters in the generated HTML, but the backslash behavior doesn’t seem consistent — I have to escape the backslash in \newline or Markdown catches the \n, but \\( collapses to \( and works fine, even with KaTeX looking for \\( (which looks like \\\\( when properly escaped in Markdown). Exploring that may be a topic for another blog post…

Now you should be able to include math notation in your notes to your heart’s content!

Converting to Hugo

2021-08-23T00:00:00+00:00

We recently converted the End Point website from Middleman to Hugo. I’ll go into more detail shortly, but the general result has been much better build times with less configuration and better support for local development.

Background

In 2017 we converted this website from a Ruby on Rails app to a static site. With tons of high-quality static site generator options, we could implement the shiny features used by our Rails site in 2009 with less overhead and quicker load times.

We also wanted to move away from Blogger to self-hosting our blog, using GitHub issues for comments. We ended up switching to Middleman, a static site generator written in Ruby, and had a mostly positive experience. Ruby was a good fit switching from Rails, and (if I remember correctly) Middleman had pretty competitive performance.

With over 1000 blog posts at the time, as well as lots of other pages, our site was quite slow to build—3.5 minutes when building with the full blog.

Middleman had a nice development server, but due to some server-side rewrites, we couldn’t use it. Instead, we got around the build times by writing a simple Ruby script to generate an HTML preview, letting our blog authors see what their post would look like, more or less. This worked okay, but was not 100% accurate and made copy-editing and formatting slower than it needed to be for us “Keepers of the Blog”.

We started hiding most of the blog from Middleman while building to save time, but build times were still 40 seconds or more. With our patience for long build times waning, as well as Middleman losing most of its support in the development and user community, we decided to get in the market for a new site generator.

Shopping around

Before we (🚨 spoiler alert 🚨) settled on Hugo, we tried using Zola, a site generator written in Rust and boasting tiny build times. Zola is a small project, and would have worked fairly well for us, but it had several downsides.

Initial build times were very promising, but slowed down more than expected after adding our now more than 1500 blog posts. We still ended up with very respectable build times of less than 15 seconds.
As far as I could tell, Zola would have required an _index.md file in every section and subsection, to hold section settings or to make it a transparent section, passing its files to the parent section. I didn’t like the sound of having a couple hundred extra Markdown files, one for every blog year and month.
At the time of writing, Zola doesn’t support custom taxonomy paths. That means we would have our blog tags at www.endpointdev.com/tags/, instead of our existing (and preferred) www.endpointdev.com/blog/tags/. This has been discussed on Zola forums, but seems to have stalled. This wasn’t a complete dealbreaker, but it was disappointing.

Making the switch to Hugo

We wanted to see if there was another option which solved our issues with Zola. I decided to try Hugo. It’s written in Go and is currently one of the most popular static site generators.

I partially converted the site and blog, and found that Hugo solved our main concerns with Zola:

Build times were close to twice as fast as Zola.
You can dump as many subdirectories as you want in each section, and they’ll still belong to the section but retain the original directory structure.
Hugo supports custom taxonomy paths through its permalinks.

We were also able to shave off a lot of build time by analyzing our template metrics—this is one of my favorite features in Hugo.

Local development

So far, we’ve had extremely smooth local development. Hugo (like Zola) comes as a standalone single executable, so it’s extremely easy to get started or update. This was a huge improvement over Middleman, which required a heap of Ruby gems and plugins. Now every blog author can easily clone our repo, run the development server, and edit their post directly, with the full site building in anywhere from ~10 seconds all the way down to ~2 seconds, depending on the author’s machine.

For blog authors, we were using a fork of an abandoned Middleman plugin. With Hugo, we’re using their taxonomies, which have been fairly easy to set up. We were also able to use Hugo’s built-in Chroma highlighter, instead of loading and running highlight.js on every blog page.

Some drawbacks

July 2025 Update: Hugo has seen a lot of development since this post was written in 2021. I’ve added Wayback Machine links so the references are historical, but these examples are out of date now. From my usage in the past few years, the documentation has improved quite a bit.

We’re loving the wonderfully fast build times and easy local development. I like the templating fairly well, and the simple configuration is wonderful. But Hugo does have several issues and missing features I’d like to see.

One place Zola wins over Hugo is the ability to easily print the entire context in a big JSON object. It’s a bit hard to navigate, but in my experience much easier and clearer than Hugo, where I have to either try using printf to display the context’s variables, or search through the documentation. This was one of my favorite ways to quickly debug and learn about the inner workings of Zola, and would be very welcome in Hugo as well, without needing to know Go formatting width and the full shape of Hugo’s context object beforehand.

Joe Mooring, a Hugo developer, mentioned that you can print some things with debug.Dump. I tried passing the context with {{ debug.Dump . }}, which worked well for seeing what context variables are available/set.

Documentation is another area where Hugo struggles sometimes. Pages often don’t feel interconnected and examples are often lacking. Here are a few examples I encountered:

The Hugo Pipes page SASS/SCSS shows how to transform Sass files to CSS, but did not link to the very useful Page Resources page. It turned out I just needed to link to {{ $style.RelPermalink }}, but as a new user it wasn’t clear that the CSS file was considered a Resource. Having more links to related pages or more examples could save a lot of headaches for newbies.
Lookup Order says under the Layout section that it “can be set in page front matter,” but I had to look under Front Matter to see that layout is the key name. A small change, and didn’t take long to experiment and find out, but especially since YAML is case sensitive, having a link to the actual front matter key would be better.
Enabling custom outputs on a per-taxonomy basis does not seem to be possible. We want to generate Atom feeds for our blog tags, but not for our blog authors, both of which are taxonomies. As far as I can tell, we have to enable them both and live with the cruft of unnecessary blog author feeds being generated.
Joe also provided a solution to this problem: cascade the outputs front matter field down from the taxonomy page (e.g., content/tags/_index.md) or from your site configuration.
- https://gohugo.io/configuration/cascade/
- https://gohugo.io/content-management/front-matter/#cascade-1
I tested this and it works like a charm.

Onward and upward!

It may look (mostly) the same, but on our end it’s never been easier to write blog posts or update the website, thanks to Hugo and all its contributors!

Jamstack Conf Virtual 2020: Thoughts & Highlights

2020-06-16T00:00:00+00:00

Welcome to Jamstack Conf Virtual 2020

Last week I attended Jamstack Conf Virtual 2020. It had originally been slated to take place in London, UK but was later transformed into a virtual event in light of the COVID-19 pandemic. The conference began at 2pm London time (thankfully I double-checked this the night before!)—6am for those of us in the Pacific Time Zone.

Up early for #jamstackconf 😎☕️ pic.twitter.com/ydjvrHWCZH
— Greg Davidson (@syncopated) May 27, 2020

Before getting too much further I wanted to mention that if you are not familiar with the Jamstack, You can read more about it at jamstack.org.

To virtually participate in the conference we used an app called Hopin. I had not heard of it before but was impressed with how well it worked. There were over 3000 attendees from 130+ countries one of the times I checked. Phil Hawksworth was the Host/MC for the event and did a great job. There were virtual spaces for the stage, sessions, expo (vendors), and networking. If you opted to, the networking feature paired you with a random attendee for a video chat. I’m not sure what I expected going into it but I thought it was fun. I met a fellow developer from the Dominican Republic. The experience was very similar though more serendipitous than the hallway track or lunch line at an in-person conference.

Keynote

Matt Biilmann opened the conference with a keynote address about the challenges we face as a developer community trying to improve access to accurate, timely and locally relevant information to a global audience. Many billions of users with all kinds of devices and varying levels of connectivity. He moved on to share how Netlify is trying to enable developers to “build websites instead of infrastructure” and “ensure all the best practices become common practices” through features like git-based deployments, build plugins, and edge handlers (more on those later).

State of the Jamstack Survey results

Laurie Voss walked us through the results of the Jamstack Survey 2020. There were some interesting findings and surprises. Later on I read Laurie’s post (which Matt had mentioned in his talk) and found that very interesting as well.

Fireside chat with Harper Reed

Frances Berriman chatted with Harper Reed and asked him about his application of Jamstack principles from years ago when he led the technology team for Barack Obama’s election campaign. He described the need to “get far with very limited resources” and spoke about experimenting with serving HTML from Google App Engine and Amazon S3. Using pre-built HTML allowed them to scale very efficiently and he opted to use message queues rather than interacting with the database to keep things very quick for users.

Another benefit Harper noted was how quickly and easily new team members could be onboarded. Folks who knew HTML, CSS and JavaScript would be up to speed and productive in no time. He admitted it’s more complicated today 😀. Speed is another benefit—he just loves when he comes across a super-fast web site (often mostly static).

Lightning Launch: Netlify ⚡

David Calavera gave a demo of Netlify’s new Edge Handlers feature which lets developers add logic to their code at the edge (e.g. the CDN servers geographically closest to the user). He demonstrated how Edge Handlers make it possible to examine the headers of the request to tailor the response to that unique request. Check out the video of his talk to watch him live code an example. I believe Cloudflare Workers and Fastly’s Edge Compute are operating in a similar problem space. I plan to look into each of these offerings more thoroughly in future.

Lightning Launch: Prismic ⚡

Renaud Bressand from Prismic demoed Slicemachine—a new feature from Prismic which lets you combine nuxt/Vue components with content managed in Prismic. It looked like a very compelling way of enabling better collaboration between developers and content creators.

Lightning Launch: RedwoodJS ⚡

Tom Preston-Werner demoed his latest project RedwoodJS. I had heard Tom speak about this on a few podcasts recently and it was nice to see him demo it for us. It looks interesting and feels reminiscent of Rails. RedwoodJS simplifies wiring up your database to a GraphQL API (they use Prisma for this) and integrating it into a React application. Tom is also the creator of Jekyll—a Jamstack-style tool which has been around for many years. It was nice to see several speakers give him some recognition for his work on that project.

The COVID Tracking Project: 0 to 2M API requests in 3 months

Erin Kissane gave an inspiring talk about her work on The COVID Tracking Project. She described it as an “interim public data rescue project”. Erin and some friends, journalists and volunteers worked together to create the site. They started by scraping COVID data from each state’s web site and storing it in a Google Sheet. They used Gatsby, Contentful, and Sass modules and hosted the site on Netlify. Using the Jamstack approach allowed the site to remain performant and continue to be responsive under some huge traffic spikes. Over time, they iterated on the design and continue to improve the site daily. I highly recommend checking out the video of the talk when you get a chance.

Jamstack for emerging markets

Christian Nwamba described some of the challenges of building sites for users in Nigeria (low power devices, spotty connectivity, unreliable power). He shared that 55% of the most visited sites in Nigeria are global companies (Google, Facebook/Instagram, Netflix, Stack Overflow etc.). Christian reviewed a large, popular banking site in Nigeria and noted its many shortcomings.

To demonstrate how the bank might do better he built an app for transferring money between friends & family built in the Jamstack style and using serverless functions. The most interesting thing I picked up from this was his method of using serverless functions to protect the app secrets (API keys, etc.). The front end of the application did not need to concern itself with this—the serverless functions kept the secrets safe and acted as a proxy between the frontend and the backend APIs. Be sure to take a look at Christian’s code if you are interested.

Managing diabetes with Jamstack

Jamie Bradley taught us about diabetes and the Jamstack app he built to help himself and others manage it. He built HeySugar with Gatsby and Sanity, hosted it on Netlify. He’s making it easier for others to deploy their own instances as well.

Selling tickets without servers. Or frameworks. Or cookies.

Jan van Hellemond has volunteered for years at a very popular conference in Europe (Fronteers I think). In previous years tickets sold out in 6 minutes one year, and 30 seconds in another! Their ticket vendor was struggling to handle to the load and this caused them to oversell early bird tickets. Jan built a Jamstack site to sell their tickets and was very pleased with the performance. He used simple, single-purpose vanilla JavaScript components and simple, single-purpose API handlers (serverless functions).

Jan prerendered as much as possible and seeded a relational database with the tickets available for sale. As the tickets were sold, they were marked sold with a database update. Webhooks were used as customers stepped through the checkout flow. Jan joked about deploying to production on a Friday afternoon because of how safe and simple the deployment process was. There were no services to restart, etc. because “it’s just files”. It was cool to see a practical example and that Jan used the basic building blocks of the web (HTML, JavaScript, CSS, old school links) successfully without reaching for a large JavaScript framework.

The business side of the Jamstack

Ana Rossetto shared how her company has been having great success with the Jamstack. Previously, the agency had been building projects for clients with Drupal. She walked through a project she and the team built to encourage people to buy from small, locally-owned businesses. She was impressed with what they were able to create in a very short amount of time.

Build plugin authors’ session

After the main talks there were several sessions. In the Hopin app, I was able to peek into some of these and the presenters and attendees were chatting (both text chat and video). This was very much like the experience of peeking into conference rooms at a physical venue and choosing whether to stay and participate or move on. After some wandering I chose to attend a session with three Netlify build plugin authors.

Peter Müller built Subfont with a friend. He demonstrated how subsetting web fonts (i.e. only loading the characters & glyphs you really need) can dramatically improve frontend performance. He compared the WebPageTest results for Google Fonts with and without Subfont and Subfont was seconds faster! I have subset and locally hosted webfonts in several client projects here at End Point. It takes time and is a manual process. Peter’s plugin makes this excellent performance improvement relatively painless.

David Darnes demoed his build plugin to turn Ghost content into Markdown files. Very interesting and it seemed flexible enough to work with other tools as well.

Gleb Bahmutov presented the build plugin he created to run Cypress tests as part of your Netlify build process. It was amazing to see how simple it was (single devDependency and single line in the netlify.toml config file).

Videos from the conference

Netlify has already put all of the Jamstack Conf Virtual 2020 talks on YouTube so head over there and check those out if you’d like to. Thanks very much to the team at Netlify for organizing the conf, all of the speakers, vendors and attendees!

Using GitHub for Blog Comments

2017-11-14T00:00:00+00:00

Last Saturday, November 11, we rolled out a new website that we’ve been working on for a few months. Part of this update was moving from Blogger as our blogging platform to static HTML generated by Middleman. We were more than happy to move away from Blogger for a variety of reasons, including its lack of HTTPS support for custom domains and how difficult it was to keep its templating and styling up to date with our main website. We were also able to move from blog.endpoint.com to www.endpoint.com/blog.

The most obvious thing that is missing from Middleman’s blog extension is the lack of a commenting system. After exploring some options for comments, we settled on using GitHub issues and comments, inspired by Don Williamson’s post about doing the same thing. It’s a bit of an unconventional approach, so this post will explain how to use our commenting system and how we implemented it.

Commenting requires a GitHub account, which is easy to sign up for and free, and the general target audience of our blog will often already have a GitHub account. At the bottom of each post will be a link to a GitHub issue at the top of the list of comments, if there are any. Click on the issue, write and post your comment, and it’ll appear on the blog post when you reload the page. It’s pretty simple.

Now, for the gritty details. Don’s post shows the JavaScript he uses to find the correct GitHub issue and fetch its comments, but it required a bit of modification to work in our Middleman project. First, we needed a way to get the right GitHub issue number. Don’s example has that worked into the JavaScript with Hugo, fetching it from some parameter value, but I opted to create a hidden input on the page that would provide the right number:

<input type="hidden" name="gh_issue" value="<%= current_page.data.gh_issue_number =>">

Or in HAML:

%input{type: "hidden", name: "gh_issue", value: current_page.data.gh_issue_number}

And we can fetch that value with jQuery:

var issue_id = $('[name="gh_issue"]').val();

From there, we just had to modify the IDs referenced in Don’s JavaScript to match ours, and comments were working perfectly! Well, new comments were.

Our blog is over 9 years old now, with over 1,300 posts and comments on many of those, and we needed to pull those existing comments over into GitHub as well. Actually copying the data wasn’t too difficult. I wrote a simple Python script to use the Blogger API to fetch posts and their comments, sort them by date, create an appropriately-named GitHub issue, and add the comments to them. Aside from GitHub’s anti-abuse detection system getting in the way a few times, it was an easy process.

We wanted to preserve original author and timestamp information, so I had my script prepend the comment body with that information in a code block so it could be easily read by people reading comments on GitHub and parsed by JavaScript:

original author: ...
date: ...

To parse that out, I wrote a quick and dirty regex that runs if I’m the user who created the comment:

if (data.user.login == "phinjensen") {
  var regex = /^```\r?\noriginal author: ([^\r\n]+)\r?\ndate: ([^\r\n]+)\r?\n```/;
  var info = data.body.match(regex);
  if (info) {
    author_name = info[1];
    date = new Date(info[2]);
    data.body_html = data.body_html.replace(/^<pre><code>.+\r?\n.+\r?\n<\/code><\/pre>/, '');
  }
}

If that regex isn’t matched, then the author and date data is left as-is and parsed as normal. Here’s the full JavaScript we’re using:

function formatDate(date) {
  var monthNames = [
    "January", "February", "March",
    "April", "May", "June", "July",
    "August", "September", "October",
    "November", "December"
  ];

  var day = date.getDate();
  var monthIndex = date.getMonth();
  var year = date.getFullYear();

  return monthNames[monthIndex] + ' ' + day + ', ' + year;
}

$(document).ready(function () {
	var issue_id = $('[name="gh_issue"]').val();
	var url = "https://github.com/EndPointCorp/end-point-blog/issues/" + issue_id
	var api_url = "https://api.github.com/repos/EndPointCorp/end-point-blog/issues/" + issue_id + "/comments"

  $.ajax(api_url, {
    headers: { Accept: "application/vnd.github.v3.full+json" },
    dataType: "json",
    success: function(comments) {
      $(".comments").append("Visit the <b><a href='" + url + "'>GitHub Issue</a></b> to comment on this post.");
      $.each(comments, function(i, data) {
        var date, author_name;

        if (data.user.login == "phinjensen") {
          var regex = /^```\r?\noriginal author: ([^\r\n]+)\r?\ndate: ([^\r\n]+)\r?\n```/;
          var info = data.body.match(regex);
          if (info) {
            author_name = info[1];
            date = new Date(info[2]);
            data.body_html = data.body_html.replace(/^<pre><code>.+\r?\n.+\r?\n<\/code><\/pre>/, '');
          }
        }
        if (!date) {
          date = new Date(data.created_at);
        }

        var $comment = $("<div/>", {'class': 'comment'});
        if (!author_name) {
          $comment.append($("<img/>", {
            'src': data.user.avatar_url,
            'class': 'avatar-image'
          }));
        }
        var $body = $("<div/>", {'class': 'comment-body'});
        var $header = $("<span/>", {'class': 'comment-header'});

        if (author_name) {
          $header.append(author_name);
        } else {
          $header.append($("<a/>", {'href': data.user.html_url, 'text': data.user.login}));
        }
        $header.append(" commented on " + formatDate(date));
        $body.append($header);
        $body.append($("<div>" + data.body_html + "</div>", {'class': 'comment-body',}));
        $comment.append($body);
        $(".comments").append($comment);
      });
    },
    error: function() {
      $(".comments").append("Comments are not open for this post yet.");
    }
  });
});

Huge thanks to Don Williamson for sharing his implementation of this idea! If you have any feedback for us and how we’re doing it, let us know in the comments!