WTG Hugo minimal test theme




Wild Tech ‘Garden’, uses this theme for demo/sample sites for the modules on which they work. 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 true.

See LICENSE for permissions on use.

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

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

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).

Headings within a page have a link to the header id that can be copied by hovering over the header, and copying the link on the hash (#) sign that appears.

Through the use of the render-link and render-image hooks, internal links and image src URLs on the site are validated. If ‘static’ fallback is allowed only a warning is emitted (since the link may be to a resource handled outside the Hugo normal content tree), otherwise the build will display an error for the offending link.

If a user decides to put the H1 element in the content file rather than specifying a Title in the frontmatter, this theme will display the H1 element as the page title. If there is also a Title element specified, the duplicate title will be surpressed. If there is more than one H1 element, or the H1 does not match the page title, then the H1’s will be converted to H2 elements.

Advanced image handling can be done by other modules, if the module supplies the ‘hook’ template that this theme’s render-image hook expects.

This repository includes a number of code quality checking and maintenance configurations and uses pre-commit and other tools for keeping the codebase in good order.

The hooks allow the top of the page’s HTML document to add CSS styles based on code in later parts of the document. (This takes some ‘magic’). By doing so we can add things like LQIPs (Low Quality Image Placeholders) using CSS only (no JavaScript).

The full effect will only be available with the addition of an appropriate image handling module.

It does this by adding a (poor) French translation to the main English version of the site. This ensure verifies that providing a translated edition works correctly.

Provides ‘previous/next section’, ‘previous/next’ page, and up a level buttons on every page. This makes navigation easy.

Provides hooks for adding CSS and JavaScript that gets minified, and renamed to bust cache if the CSS or JavaScript changes.

We divide the CSS into essential and deferrable, but we do not (yet) add rel="preload" to the styles because preload is not supported well enough.

We specify pages as non-canonical for pages also on another site (and the real canonical link may be specified, if you wish). By default for this demo site we make all pages non-canonical.

  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

    path = "github.com/wildtechgarden/minimal-test-theme-hugo-wtg"
  3. Change back to the site directory

  4. Get the module

    hugo mod get github.com/wildtechgarden/minimal-test-theme-hugo-wtg
  5. To test the result, run the local Hugo server

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

  1. Make a themes directory and switch to it.

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

    git submodule add -f https://github.com/wildtechgarden/minimal-test-theme-hugo-wtg.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/


In/via this module

absLinkIf true make all Markdown links absolute
addLQIPStylesIf true parse the LQIP styles from the archives
remoteFallbackPull resources from remote if link is remote
staticFallbackIf not a resource (static) use the link verbatim
isImageLinklinks is for an image not a URL/site
multipleH1ErrorFixFix too many H1’s on a page; default false
multipleH1ErrorWarnOnly warn instead of erroring of too many H1’s on a page
multipleH1ErrorIgnoreSurpress warning about too many H1’s on a page
pageCanonicalIf false the page is not marked as canonical
pagesOldestFirstIf true list pages from oldest to newest instead of newest to oldest
staticFallbackIf true only warn on missing link targets, on the assumption they are ‘static’
taxCanonicalWhether to make taxonomies and terms canonical
testStylesIncludeIf true adds a very small amount of CSS to improve theme usability.
toCanonicalURL of a the actual canonical page for a give page
topLevelClassspecifies the class(es) to apply to the <html> element

This makes the theme more usable

To enable the styles:

In config.toml add

	testStylesInclude = true