Rootwork.org publishing system

Rootwork is created with the static site generator Hugo using the Hugo Clarity theme with customizations.

Also included in this repo are some Bash scripts for Hugo to create a post, start the server and generate a production copy of the site. They are user-configurable and meant to be easy to fork. Take a look!

---

• Rootwork.org publishing system
• Local development
  • Creating a new post
  • Editing site variables
  • Hugo modules
  • Editing the theme
• Generating the site for production
• Fresh installation
  • Go
  • Hugo
  • This repo
  • Node/npm
• Updating dependencies
  • Go
  • Hugo
  • Hugo modules
  • Node modules
• Licenses

---

Local development

npm run s or ./scripts/server_start.sh

Set your preferred configuration at the top of the script for base URL (http://localhost by default), port (1313 by default) and open command (xdg-open, a Linux command, by default).

When you run this script, your default web browser will automatically open the site.

By default Hugo will run with fastRender on and buildDrafts off. You can use the flags -s and -d to change this. For details, run npm run s -- -h.

Creating a new post

npm run n or ./scripts/new_blog_post.sh

Set your preferred text editor at the top of the script.

This script will:

• Ask you for a title
• Ask you for a date (defaults to today)
• Create an appropriate slug
• Create taxonomy year and month files, if necessary (cf. gohugoio/hugo#448 )
• Create the necessary Markdown file, with sane defaults, at the appropriate directory/file location
• Open the file in your text editor

It does much more than just hugo new ....

Editing site variables

You can find text strings and other variables in several places:

• hugo/config/_default/config.toml (main configuration)
• hugo/i18n/en.toml (translatable strings, such as the copyright)
• hugo/config/_default/menus/menu.en.toml (menus)
• hugo/config/_default/configTaxo.toml (embedded social media settings)
• hugo/config/_default/markup.toml (settings for Hugo's markup highlighter)
• hugo/config/_default/params.toml (other site parameters used in the theme)

Hugo modules

The site imports components like the theme as Hugo modules rather than as git submodules (as in the past). More information about this approach.

The go.mod file is in the hugo directory of the repository, and modules are loaded in hugo/config/_default/config.toml.

Editing the theme

Customizing a theme is done by overriding theme files. Because themes are loaded dynamically using Hugo modules, go to the themes' original repos to see what files to override and their initial content.

Add notes at the top of any overridden files using Go comments ({{/* */}}) to note what has been changed -- this vastly eases integrating new changes to the overridden files from upstream.

For styles, we use assets/sass/_override.sccs to load our own component styles, which override parent theme styles as necessary. We could use _custom.scss for components that have nothing to override, but in practice this just makes things more confusing; it's easier to simply import everything as an override.

Generating the site for production

npm run p

This will generate the Hugo site in public with minification turned on. It's equivalent to running:

hugo --source ./hugo --minify --gc

Note that public is excluded from the repo in .gitignore, so this command should be run from a GitHub Action or other CI to build the site.

Fresh installation

Go

• Follow the instructions

Hugo

• Get the hugo_extended_VERSION_OS-64bit.* package from GitHub releases (e.g. hugo_extended_0.81.0_Linux-64bit.deb). On Debian-based Linux systems, ignore the alert that an older package is available in the channel.
• Install the package, which will place it in /usr/local/bin/hugo.

This repo

• git clone [email protected]:rootwork/rootwork.org.git
• cd rootwork.org

Node/npm

npm i

Node is used for automated tools like Prettier. Tested with Node 14.x and 16.x, and npm 6.x and 8.x.

Updating dependencies

Go

• Check version: go version
• Remove old version and install new version

Hugo

• Check version: hugo version
• sudo rm -rf /usr/local/bin/hugo
• Get the hugo_extended_VERSION_OS-64bit.* package from GitHub releases (e.g. hugo_extended_0.81.0_Linux-64bit.deb) and install.

Hugo modules

• Update all modules: hugo mod get -u
• Update all modules recursively: hugo mod get -u ./...
• Update a single module: hugo mod get -u <repo_path>
• Update a single module to a specific branch: hugo mod get <repo_path>@<branch>
• Update a single module to a specific version (tag must use semver): hugo mod get <repo_path>@<git_tag>

For more, see Hugo Module Site and the overview of Hugo modules.

Node modules

npm outdated

Then npm up <module> as necessary, and commit.

Licenses

The content of the site, contained in the Markdown files in the hugo/content directory and its subdirectories only, is licensed under the Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License. Images or other media in these directories may have different copyright and licensing statuses.

Hugo itself is licensed as Apache v2.0.

The theme Rootwork.org uses, Hugo Clarity, is licensed under the MIT license.

Modifications to the theme, as well as the files in the scripts directory, are licensed under the GNU Affero General Public License v3.0, as noted in the general project LICENSE file.