Hugo Flex

A lightweight Hugo theme leveraging CSS Flexbox.

This theme is verified to work with Hugo versions v0.134.0–v0.139.0.

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:

• Server-side math rendering
• 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:
  • 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.11        # 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
  # 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: false   # Set to true to render math in LaTeX notation globally
        delimiters:
          block:
            - ['\[', '\]']
            - ['$$', '$$']
          inline:
            - ['\(', '\)']

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

By default, the date is shown in the headings of all normal pages and hidden on special pages. This can be overriden on specific pages by setting the showdate parameter in their front matter. For example, the date can be hidden on an "About" page by setting its front matter as follows:

+++
title = "About"
date = 2006-01-02
[params]
  showdate = false
+++

Math Rendering

Mathematical formulas written in LaTeX notation can be rendered to HTML without using javascript. Rendering can take place either globally, or in specific locations using a built-in shortcode.

1. To render math globally, enable the passthrough extension in the site configuration.

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

2. To render mathematical expressions in specific locations, surround them with the math shortcode:

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

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.

Built-In Shortcodes

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.

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 page's scratch pad. For instance, a shortcode template myshortcode.html containing the line

{{ resources.Get "myscript.js" | .Page.Store.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.Store.SetInMap "css" "soundcloud" }}
{{ resources.Get "js/soundcloud.js" | .Page.Store.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.