Fix missing base.css integrity in RSS pages
Update tested Hugo versions in README.md
Fix redundant processing of base resources (#38)
A lightweight Hugo theme leveraging CSS Flexbox.
This theme is verified to work with Hugo versions v0.122.0–v0.128.0.
Optional features:
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.
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
hugo.yaml:echo 'theme: hugo-flex' >> hugo.yaml
Open a command prompt at the site's root directory and update the theme:
git submodule update --remote --rebase
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
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.
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.
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.
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" >}}
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.
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.
This theme offers two ways to add custom CSS or JS assets, allowing minor modifications to be applied without needing to create a fork.
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.
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" | .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>
This theme is licensed under the Apache License 2.0.