Build RKey Tech

Build project

Matching Blog Post

This document is old and probably not accurate anyway as I initially built the site using the Congo theme and the changed to the GeekDocs theme but just modified from memory on what was different. This will be completely redone in the near future to reflect the Docsy build and deployment. So stay tuned for that.

Update 19-July-2022: When I first built my site I built it using the Congo theme with Hugo. I did that because I could not figure out how to build my preferred theme GeekDocs correctly. Well is was a simple Markdown error on my part so now RKey.Tech will be a GeekDocs theme and my personal only site RKey.Online will use Congo GeekBlog theme.

Create new Hugo project

hugo new site

cd into new project and initialize

git init

Verify and initialize ‘go’

go version
  go version go1.17.7 linux/amd64
hugo mod init

I initially tried using webpack, but my luck putsing with npm on Linux is no better than the luck I have on FreeBSD. I have come to realize Java freaking hates me!! If you want to use the theme from a cloned branch instead of a release tarball you’ll need to install webpack locally and run the build script once to create all required assets. (This did not work for me)

# install required packages from package.json
npm install

# run the build script to build required assets
npm run build

So I just I just downloaded the pre-release bundle

mkdir -p themes/hugo-geekdoc/
curl -L | tar -xz -C themes/hugo-geekdoc/ --strip-components=1

From here I just copied the files and directories from the theme directry to the site directory.
NOTE: You should only need to do this for files you are modifying from the downloaded theme. I guess the saying do as I/they say not as I do is appropiate here.

cd themes/hugo-geekdoc/
cp -a archetypes assets data i18n images layouts static ../../

From there it is just a matter of configuring toml or yaml files.

The first one to tackle is config.toml in the site root. I left this mostly as is.

cat config.toml
baseURL = ''
languageCode = 'en-us'
title = 'RKey Tech'
#theme = "hugo-geekdoc"

pluralizeListTitles = false

# Geekdoc required configuration
pygmentsUseClasses = true
pygmentsCodeFences = true
disablePathToLower = true
geekdocFileTreeSortBy = "date"
geekdocSearchShowParent = true

# Required if you want to render robots.txt template
enableRobotsTXT = true

# Needed for mermaid shortcodes
    # Needed for mermaid shortcode
    unsafe = true
    startLevel = 1
    endLevel = 9

   tag = "tags"

Then I added my deployment script.

rm -rf public/
rm public.tar
HUGO_ENV="production" hugo --gc || exit 1
echo OK, now that stuff is built
rsync -azP --delete public/ caddy:~/
echo OK, now that stuff is uploaded
echo ======================================
echo Done
echo ======================================

I then made the following modification to i18n/en.yaml for footer brandinig.

footer_build_with: >
  Copyright 2022 - Robert Key
  for <img alt="" src="/images/rkeytechlogostny.png.webp" width="50" height="25"<a> and <a href="" target="_blank"><img alt="RKey.Online" src="/images/rkeyonline.png.webp" width="60" height="60"></a>  
footer_legal_notice: Legal Notice
footer_privacy_policy: Privacy Policy
footer_content_license_prefix: >
    Content licensed under

For my links in the header I modified layouts/partials/head/custom.html and added the following to this blank file.

<!-- You can add custom elements to the page header here. -->
<a href="" target="_blank"><img alt="RKey.Online" src="/images/rkeyonline.png.webp" width="70" height="70"></a>
<a href="" target="_blank"><img alt="GitLab" src="/images/icons8-gitlab-70.png.webp" width="30" height="30"></a>
<a href="" target="_blank"><img alt="GitHub" src="/images/icons8-github.svg" width="30" height="30"></a>
<a href="" target="_blank"><img alt="BSDNetwork@Mastodon" src="/images/mastodon.png.webp" width="30" height="30"></a>
<a rel="me" href="" target="_blank"><img alt="Twitter" src="/images/icons8-twitter-circled.svg" width="30" height="30"></a>
<a rel="me" href="" target="_blank"><img alt="Facebook" src="/images/icons8-facebook.svg" width="30" height="30"></a>
<a rel="me" href="" target="_blank"><img alt="Instagram" src="/images/icons8-instagram.svg" width="30" height="30"></a>
<a rel="me" href="" target="_blank"><img alt="Reddit" src="/images/icons8-reddit.svg" width="30" height="30"></a>
<a href="" target="_blank"><img alt="InfoSecExchange@Mastodon" src="/images/mastodon.png.webp" width="30" height="30"></a>
<a href="" target="_blank">StandWithUkraine<img src="/images/icons8-ukraine-70.png.webp" width="30" height="30"></a>
<a href="" target="_blank">ProtectDemocracy<img src="/images/icons8-usa-70.png.webp" width="30" height="30"></a>

From there I just extract my favicons I created at icongen

cd static/favicons

All my images for the site are kept in static/images for brand images I usually go to Icons8. I generally strive to download .svg files, barring that I will download .png files and then use either convert on the command line from the ImageMagick program or more recently I discovered libwebp and now use cwebp to convert images from the command line.

The Geedocs theme turned out to be the perfect solution for my online documentation. My origional theme used Congo, which is a beautiful theme, but not suited quite as well as the Geekdocs theme for documentation purposes. I really like the layout better for even using as a blog.