Hugo Flex

A lightweight Hugo theme leveraging CSS Flexbox.

This theme is verified to work with Hugo versions v0.122.0–v0.125.3.

Features

• Flexbox-based responsive layout
• 100% performance and accessibility scores on PageSpeed Insights
• No framework
• No javascript
• Full posts in RSS feed
• RSS page looks like a normal page
• Multilingual support
• Dark theme

Optional features:

• Syntax highlighting
• Show summaries on homepage
• Schema.org, Open Graph and Twitter Cards metadata
• Utterances comments widget
• Custom CSS and JS may be added site-wide, or dynamically with shortcodes
• Built-in shortcodes:
  • Math rendering with KaTeX
  • Netlify contact form
  • Privacy-friendly SoundCloud player

Example

The demo site is built from the hugo-flex-demo repository.

A complete starter template specifically made for this theme is also available at scivision/hugo-flex-example.

Installation

1. Install Hugo.

2. Create a Hugo site.

3. Open a command prompt at the root of the site and download the theme:

git init
git submodule add https://github.com/ldeso/hugo-flex.git themes/hugo-flex

4. Add the theme to the site configuration. If the site configuration is a file called hugo.yaml:

echo 'theme: hugo-flex' >> hugo.yaml

Updating

Open a command prompt at the site's root directory and update the theme:

git submodule update --remote --rebase

Configuration

Any part of the default theme configuration can be copied to the site configuration to be modified. The default theme configuration is:

baseURL: https://example.org/
title: My New Hugo Site
languageCode: en-us
theme: hugo-flex

params:
  color: teal           # Any color in CSS syntax
  width: 42rem          # Any length in CSS syntax / leave empty to span page
  divider: \2500\2500   # Any string in CSS syntax / leave empty for no divider
  footer: >-            # HTML spaces ( ) are needed before HTML elements
    Except where otherwise noted, content on this site is licensed under a  
    <a href="http://creativecommons.org/licenses/by/4.0/" rel="license">Creative
    Commons Attribution 4.0 International License</a>.
  rss: To subscribe to this RSS feed, copy its address and paste it into your
    favorite feed reader.
  favicon: false        # Set to true to add a link to the favicon.ico
  noClasses: &nc false  # Set to true to use inline CSS for syntax highlighting
  katex: 0.16.10        # KaTeX version / leave empty to use the latest version
  headingoffset: 0      # Change heading levels when rendering markdown
  linkicons: false      # Set to hover or true to add a link icon to headings
  summaries: false      # Set to true to show summaries of posts on homepage
  schema: false         # Set to true to add Schema.org metadata
  opengraph: false      # Set to true to add Open Graph metadata
  twittercards: false   # Set to true to add Twitter Cards metadata
  utterances:
    repo:               # Set to Utterances repo URL to add Utterances comments
    issueterm:          # Leave empty for the default blog post to issue mapping
    theme:              # Leave empty to use the adaptive Utterances dark theme
  netlify:
    honeypot: false     # Set to true to add honeypot field in contact form
    recaptcha: false    # Set to true to add recaptcha challenge in contact form
  math: &math false     # Set to true to render LaTeX without using shortcodes
  mathdelim: &md
    block:              # List of pairs of "display" math delimiters
      - ['\[', '\]']
      - ['$$', '$$']
    inline:             # List of pairs of inline math delimiters
      - ['\(', '\)']
  # css:                # Uncomment to add custom CSS from the assets directory
  #   - css/foo.css
  #   - bar.css
  # js:                 # Uncomment to add custom JS from the assets directory
  #   - js/foo.js
  #   - bar.js

markup:
  highlight:
    noClasses: *nc      # Set to same value as params.noClasses
  goldmark:
    extensions:
      passthrough:
        enable: *math   # Set to the same value as params.math
        delimiters: *md # Set to the same value as params.mathdelim

menu:
  main:
    - name: About
      pageRef: /about
      weight: 1
    - name: Posts
      pageRef: /post
      weight: 2
    - name: Tags
      pageRef: /tags
      weight: 3
    - name: Categories
      pageRef: /categories
      weight: 4
    - name: RSS
      pageRef: /
      weight: 5
      params:
        - format: rss

outputFormats:
  rss:
    mediatype: application/rss+xml
    baseName: feed      # Rename RSS feed URL from rss.xml to feed.xml

Built-In Shortcodes

Math Rendering

Mathematical formulas written in LaTeX notation can be rendered to HTML on the client side by bundling the KaTeX library with the website. Rendering can take place either globally, or in specific locations using a built-in shortcode.

1. Math can be rendered globally or on a per-page basis by setting the math parameter to true in the site configuration or on specific pages, and by enabling the passthrough extension in the site configuration.

2. If the math parameter is set to false, mathematical formulas can still by rendered by surrounding them with the math shortcode:

   {{% math %}}
   Inline formulas such as $y=ax+b$ are supported, displayed formulas as well:
   
   $$e^{i\pi}+1=0$$
   {{% /math %}}
   

As of 2024, it is not yet possible to render math on the server side with Hugo.

Netlify Contact Form

A contact form that works with the Netlify Forms service can be inserted with the shortcode:

{{< contact >}}

A custom URL for the success page may be given as a parameter:

{{< contact "/success" >}}

SoundCloud Player

A privacy-friendly SoundCloud player can be inserted with the shortcode:

{{< soundcloud https://soundcloud.com/artist/track >}}

The embed player will only load after user input, and will be replaced by a simple link if JavaScript is disabled.

Syntax Highlighting

By default, syntax highlighting in Hugo adds inline styles to the HTML code generated by the syntax highlighter. This can be problematic if the site has a strict Content Security Policy. This theme makes it possible to automatically use an external stylesheet for syntax highlighting.

To use an external style sheet instead of inline styles, switch the options markup.highlight.noClasses and params.noClasses to false in the site configuration. The resulting external style sheet is only included on pages of the site that require it.

The default syntax highlighting style is called github-dark. To use a different style, a style sheet can be generated at the location assets/css/syntax.css by running the following command at the site root:

hugo gen chromastyles --style style-name > assets/css/syntax.css

The styles featuring both a high contrast and good compatibility with dark mode are called average, doom-one, doom-one2, github-dark, modus-operandi (light background), modus-vivendi, rrt, and witchhazel.

Custom CSS and JS

This theme offers two ways to add custom CSS or JS assets, allowing minor modifications to be applied without needing to create a fork.

Site-Wide

Custom CSS and JS files can be loaded as part of the base assets linked by every page. To do so, their filenames have to be added to the site configuration:

params:
  css:
    - css/foo.css
    - bar.css
  js:
    - js/foo.js
    - bar.js

The paths are relative to the asset directory. In this example, the file paths relative to the site root would be: assets/css/foo.css, assets/bar.css, assets/js/foo.js, and assets/bar.js.

Dynamically Embedded

Sometimes, custom CSS or JS is needed only on specific pages. This theme offers a mechanism to load CSS or JS assets through shortcodes. The assets are loaded only once per page, even if they are required by several shortcodes in the same page.

To load a CSS or a JS resource on each page where a shortcode is used, the shortcode template has to add the resource to the css or the js key of the Scratch variable. For instance, a shortcode template myshortcode.html containing the line

{{ resources.Get "myscript.js" | fingerprint | .Page.Scratch.SetInMap "js" "myscript" }}

will cause myscript.js to be loaded on every page where myshortcode is used.

As a real-life example, this is the template for the built-in SoundCloud shortcode:

{{ resources.Get "css/soundcloud.css" | .Page.Scratch.SetInMap "css" "soundcloud" }}
{{ resources.Get "js/soundcloud.js" | .Page.Scratch.SetInMap "js" "soundcloud" }}

<div class="Soundcloud">
  <a href="{{ .Get 0 }}" target="_blank" class="Soundcloud-box Soundcloud-box--link"><span class="Soundcloud-ellipsis">{{ .Get 0 }}</span></a>
</div>

License

This theme is licensed under the Apache License 2.0.