A blog, the fun way

3 minutes read
hugo • docker • netlify

To write a blog you must first build a blog?
Apparently in my mind this is true, so here we are.

tl;dr: putting disparate technologies together always takes longer than expected

Tools

  • Vs Code

  • Docker

  • Hugo

  • asciidoctor

  • github

  • netlify

Whilst VS Code and Docker aren’t strictly necesary, I’ve been itching to use the Container Development feauture of VS Code.
You’re going to need to install the Remote Development extension pack for this.

Create a repo

do your thing.

Add a Dockerfile

This is pretty standard sauce; using klakegg/docker-hugo as the base, because the Hugo package provided using apt-get is several versions behind which caused issues with the themes.
Also I was too lazy to build it from source.

FROM klakegg/hugo:0.74.3-ext-ubuntu

RUN apt-get update && apt-get install -y \
    git \
    ruby-full \
    silversearcher-ag \
    vim \
    && rm -rf /var/lib/apt/lists/*

RUN gem install asciidoctor:2.0.1 \
    asciidoctor-diagram:1.5.18 \  
    rouge:3.6.0 
 (1)

COPY ./asciidoctor /usr/local/sbin

RUN chmod +x /usr/local/sbin/asciidoctor
1asciidoctor-diagram not used just yet.

Do some unsafe stuff with asciidoctor

Hugo calls asciidoctor with the --safe parameter which seems reasonable. The unreasonable part is that you can’t disable it or you pass custom parameters to it.

Kudos here for the original idea, I just tweaked it slightly.
If you place the asciidoctor script in /usr/local/sbin/ it will be evaluated before the original binary located at /usr/local/bin, allowing us to intercept the call and do with it as we wish.

Unresolved directive in <stdin> - include::.//asciidoctor[]
After I changed the context of the hugo site to not be in a sub-folder, then this wasn’t necessary, but it might still come in useful when I want to use diagrams.

Add .devcontainer.json

This tells VS Code how to instantiate your container, this file only has the dockerFile portion, but if you want to push using your ssh keys, you might want the additional ssh related snippets.

//See https://aka.ms/vscode-remote/devcontainer.json for format details.
{
	"dockerFile": "Dockerfile",
	"extensions": [],
	"runArgs": [ 
		"-v", "${env:HOME}${env:USERPROFILE}/.ssh:/root/.ssh-localhost:ro", (1)
		"--name", "hugo_dev" (2)

	],
	"postCreateCommand": "mkdir -p ~/.ssh && cp -r ~/.ssh-localhost/* ~/.ssh && chmod 700 ~/.ssh && chmod 600 ~/.ssh/*" (3)
}
1mount the ssh keys in a temporary location
2name the container so that we get a consistent container name
3now that the container is running, move the keys into a better location

Because I’m lazy I added the --name argument so that I can always access the container with the same command docker exec -it hugo_dev bash -c 'cd /workspaces/blog ; exec "${SHELL:-sh}"'

Maybe we should create this blog and set a theme

docker exec -it hugo_dev  bash -c 'cd /workspaces/tldr ; exec "${SHELL:-sh}"'
hugo new site tldr
mv tldr/* . (1)
rm tldr
git submodule add https://github.com/luizdepra/hugo-coder.git themes/hugo-coder
1we don’t need the sub folder - we aren’t doing multiple sites

It’s also necessary to update the theme value to hugo-coder, as mentioned on the hugo-coder homepage

Let’s go rouge

Hugo doesn’t seem to support asciidoctor very well; Code highlighting and admonitions need to be manually added as well.

Hello netlify

Finally, lets make these ramblings more accessible.
I found the following readings useful in getting this blog hosted.

My final netlify.toml looks as follows

Unresolved directive in <stdin> - include::.//netlify.toml[]

Also worth noting that I had to include a Gemfile

Unresolved directive in <stdin> - include::.//Gemfile[]

Source of blog can be found at https://github.com/timothysparg/tldr