Hugo minimal test module/theme

DFD Hugo minimal test theme

Status

Demo website

https://minimal-test-theme.wildtechgarden.ca/

GitHub repository

https://github.com/danielfdickinson/minimal-test-theme-hugo-dfd

Overview

Daniel F. Dickinson, uses this theme for demo/test sites for the modules on which he works. For a repository for creating minimal reproducible test cases see either the v0.3 branch of this repository or hugo-testing by jmooring from the Hugo forums. That use case was previously a goal of this repository, but such is no longer the case.

See License for permissions on use.

Modern hugo only

This minimal theme is built using assumptions that may require Hugo 0.80.0 or higher, and in any event those are the only versions on which it has been tested.

Available features

hello-world shortcode

A simple shortcode that emits an HTML paragraph with ‘Hello World!’. To use it, add {{< hello-world >}} to a content file (not template).

page-assets shortcode

Allows rendering a Hugo resource from the assets directory as Markdown. This is currently used to render this repo’s README.md on a page in the exampleSite.

In order to be compliant with current HTML best practise for h1 elements, which is to have only one h1 element per page, any H1 elements in the asset are rewritten as H2 elements (because this theme adds the page title as an H1 element).

Basic usage (as theme)

Hugo module (preferred)

1. Initialize the Hugo module system: hugo mod init github.com/<your_user>/<your_project>; (assuming you are using GitHub, of course).

2. Import the theme in your config.toml

   [module]
   [[module.imports]]
   path = "github.com/danielfdickinson/minimal-test-theme-hugo-dfd"
   

3. Change back to the site directory

4. Get the module

   hugo mod get github.com/danielfdickinson/minimal-test-theme-hugo-dfd
   

5. To test the result, run the local Hugo server

   hugo server -b http://localhost:1313/
   

Using git submodules (unsupported by theme author)

1. Make a themes directory and switch to it.

   mkdir themes
   cd themes
   

2. In the themes directory, add minimal-test-theme-hugo-dfd as a submodule

   git submodule add -f https://github.com/danielfdickinson/minimal-test-theme-hugo-dfd.git
   

3. Change back to the site directory

4. To test the result, run the local Hugo server

   hugo server -t hugo-minimal-test -b http://localhost:1313/
   

Enjoy!

Page and/or site params available

In/via this module

Test CSS styling

This makes the ’theme’ more usable

To enable the styles:

In config.toml add

[params]
	testStylesInclude = true

Contributions welcome

If your issues can’t be found when searching both open and closed issues, please add it!

Please check open issues on danielfdickinson/minimal-test-theme-hugo-dfd for enhancements and bugs that you would like resolved, write the fix, and submit a PR!

Adding and improving documention is always handy as well.

For accessibility, source code uses tabs

Until recently I was ‘spaces over tabs’ developer, but I recently read a blog post by Bruce Wray about the accessibility argument for tabs over spaces and followed the links he gave, and the ability of tabs to be handled by braille or screen reader devices (or users who need to zoom their displays) is more than just ’taste’ but can in fact be a huge win for ‘getting stuff done’. That major sites don’t handle tabs well in code blocks is a reflection on poor site design, and should not be excused or catered to.

All it takes is (for example)

code,
pre {
	tab-size: 3;
}

And of course, you can use CSS selectors to override when needed.

Support and general questions

Please use GitHub Discussions for support and general questions.