chipzoller / hugo-clarity

A theme for Hugo based on VMware Clarity

Hugo Clarity Theme

A technology-minded theme for Hugo based on VMware's open-source Clarity Design System featuring rich code support, dark/light mode, mobile support, and much more. See a live demo at neonmirrors.net.

Preview on Desktop

Light Mode	Dark Mode

Preview on Mobile

Light Mode	Dark Mode

Table of Contents

• Features
• Prerequisites
• Getting up and running
• Configuration
  • Global Parameters
  • Page Parameters
  • Menus
    • Main Menu
    • Social media
  • Search Engine
  • Blog directory
  • Mobile menu positioning
  • Tags and taxonomies
  • Images
    • Organizing page resources
    • Modern image formats
    • Image captions
    • Adding figure positions to image captions
    • Inline images
    • Floating images
    • Round borders
    • Adding CSS classes
    • Featured image
    • Thumbnail image
    • Share image
    • Logo alignment
  • Code
  • Table of contents
  • Pinning featured posts
  • Notices
  • Custom CSS and JS
  • Custom Site Disclaimer
  • Forcing light or dark mode
  • Internationalization - I18N
  • Hooks
  • Comments
  • Math notation
  • Open Street Map
  • Search
• Contributing
• Code of conduct
• License

Features

• Blog with tagging and category options

• Search

• Deeplinks

• Choice of whether to use Hugo Page Bundles

• Native image lazy-loading

• Customizable (see config)

• Dark mode (with UI controls for user preference setting)

• Toggleable table of contents

• Toggleable automatic figure numbering

• Configurable site disclaimer (i.e. "my views are not my employer's")

• Flexible image configuration, and support for modern formats like WebP

• Logo alignment

• Mobile support with configurable menu alignment

• Syntax highlighting

• Rich code block functions including:

  1. Copy to clipboard

  2. Toggle line wrap (dynamic)

  3. Toggle line numbers

  4. Language label

  5. Toggle block expansion/contraction (dynamic)

     To put it all in context, here is a preview showing all functionality.

     

Prerequisites

Firstly, ensure you have installed the extended version of Hugo 0.91.0 or above. See installation steps from Hugo's official docs for more information. Note that software repositories may be several versions behind and may not include the extended version.

Getting up and running

Read the prerequisites above and verify you're using the extended version of Hugo 0.91.0 or newer.

There are several ways to use this theme:

Option 1a: Development in the browser

For trying out the theme, quick experimentation, and to contribute Pull Requests, Gitpod is the easiest option. Use the button above and it will spin up a prebuilt environment with a site ready to go.

If you want to contribute a PR, this is a good overview of that process, and there's also an optional browser extension. Read more about contributing to Hugo Clarity

Option 1b: Development on your machine

If you prefer not to use Gitpod, you can also test, develop and contribute PRs locally from your computer.

git clone https://github.com/chipzoller/hugo-clarity
cd hugo-clarity/exampleSite/
hugo server --themesDir ../..

Note that while this is a good way to work on Hugo Clarity, isn't a good way to work on your own site, since it uses the content from exampleSite, and wouldn't be aware of any overrides your site might apply to the theme.

Read more about contributing to Hugo Clarity

Option 2: Hugo modules

This option arguably requires the least effort to run and maintain your website with the Hugo Clarity theme.

We assume you've already run hugo new site <sitename> and are in the <sitename> directory.

1. Ensure you have the go binary installed on your machine. (Mac users: brew install go.)

2. Run the following command:

hugo mod init <sitename>

3. Hugo Clarity comes with exampleSite files prefilled with helpful configuration and sample posts. If you're starting a new Hugo site and don't have any content yet, it's easiest to grab the whole thing:

wget -O - https://github.com/chipzoller/hugo-clarity/archive/master.tar.gz | tar xz && cp -a hugo-clarity-master/exampleSite/* . && rm -rf hugo-clarity-master && rm -f config.toml

If you are using PowerShell, paste this instead:

wget -O - https://github.com/chipzoller/hugo-clarity/archive/master.tar.gz | tar xz -and cp -a hugo-clarity-master/exampleSite/* . -and rm -rf hugo-clarity-master -and rm -f config.toml

If you do already have a site and don't want to risk overwriting anything, we suggest copying the contents of config over, as well as replacing your archetypes/post.md (if it exists) with Hugo Clarity's. Then migrate any necessary settings from <sitename>/config.toml to <sitename>/config/_default/config.toml and remove the original <sitename>/config.toml file.

4. Open <sitename>/config/_default/config.toml and change theme = "hugo-clarity" to theme = ["github.com/chipzoller/hugo-clarity"]

5. You can now run:

hugo server

If that seems like a lot of setup, it's meant to reduce the pain of pulling in new versions of Hugo Clarity when they are released.

To pull in theme updates, run hugo mod get -u github.com/chipzoller/hugo-clarity. You can also update all your Hugo modules with hugo mod get -u ./... -- read more about updating Hugo modules.

There is more you can do with hugo modules, but this will suffice for our use case here.

Option 3: Git submodules

For those not ready to use Hugo modules, you can use the "old way" using git alone.

We assume you've already run hugo new site <sitename>, are in the <sitename> directory, and have a working git repo (git init).

1. Run:

git submodule add https://github.com/chipzoller/hugo-clarity themes/hugo-clarity

2. Hugo Clarity comes with exampleSite files prefilled with helpful configuration and sample posts. If you're starting a new Hugo site and don't have any content yet, it's easiest to grab the whole thing:

cp -a themes/hugo-clarity/exampleSite/* . && rm -f config.toml

If you do already have a site and don't want to risk overwriting anything, we suggest copying the contents of config over, as well as replacing your archetypes/post.md (if it exists) with Hugo Clarity's. Then migrate any necessary settings from <sitename>/config.toml to <sitename>/config/_default/config.toml and remove the original <sitename>/config.toml file.

3. You can now run:

hugo server

While this is less setup than option 2 initially, it comes with important caveats. First, to pull in new versions of the theme, you'll need to run git submodule update --remote --merge and commit those changes to your git repo. Second, if you clone your repo to another machine, have multiple people working on your site, or have a continuous-integration or deployment script (like Netlify), after cloning you'll need to also remember to run git submodule update --init --recursive to get the theme files.

See an overview of using git submodules for Hugo themes and troubleshooting git submodules in Hugo themes for details.

Configuration

Hugo Clarity uses a config folder rather than a single file. If you're used to having a config.toml file in your main folder, now you'll find that located in config/_default/config.toml, along with other settings files.

This section will mainly cover settings that are unique to this theme. If something is not covered here (or elsewhere in this file), there's a good chance it is covered in this Hugo docs page.

Global Parameters

These options set global values that some pages or all pages in the site use by default.

Parameter	Value Type	Overridable on Page
author	map / string	no
twitter	string	no
largeTwitterCard	boolean	no
ga_analytics	string	no
google_tag_manager_id	string	no
baidu_analytics	string	no
plausible_analytics	boolean	no
matomo_analytics	boolean	no
description	string	yes
keywords	array of strings	yes
introDescription	string	yes
introURL	string/false	no
numberOfTagsShown	integer	no
usePageBundles	boolean	yes
fallBackOgImage	file path (string)	no
codeMaxLines	integer	yes
codeLineNumbers	boolean	yes
mainSections	array/string	no
centerLogo	boolean	no
logo	file path (string)	no
iconsDir	dir path (string)	no
mobileNavigation	string	no
figurePositionShow	boolean	yes
figurePositionLabel	string	no
customCSS	array of file path (string)	no
customJS	array of file path (string)	no
enforceLightMode	boolean	N/A
enforceDarkMode	boolean	N/A
titleSeparator	string	no
showShare	boolean	yes
comments	boolean	yes
numberOfRecentPosts	integer	no
numberOfFeaturedPosts	integer	no
pinFeatured	boolean	no
numberOfPinnedPosts	integer	no
dateFormat	string	no
enableMathNotation	boolean	yes
customFonts	boolean	no
since	integer	N/A
rss_summary	boolean	N/A
rss_summary_read_more_link	boolean	N/A
showRelatedInArticle	boolean	yes
showRelatedInSidebar	boolean	no
footerLogo	string	N/A
enableSearch	boolean	N/A

Page Parameters

These options can be set from a page frontmatter or via archetypes.

Parameter	Value Type	Overrides Global
title	string	N/A
date	date	N/A
description	string	N/A
keywords	array of strings	yes
introDescription	string	yes
abstract	string	N/A
summary	string	N/A
draft	boolean	N/A
featured	boolean	N/A
tags	array/string	N/A
categories	array/string	N/A
toc	boolean	N/A
usePageBundles	boolean	yes
featureImage	file path (string)	N/A
featureImageAlt	string	N/A
featureImageCap	string	N/A
thumbnail	file path (string)	N/A
shareImage	file path (string)	N/A
codeMaxLines	integer	yes
codeLineNumbers	boolean	yes
figurePositionShow	boolean	yes
figurePositionLabel	string	no
comments	boolean	yes
enableMathNotation	boolean	yes
showDate	boolean	N/A
showShare	boolean	N/A
showReadTime	boolean	N/A
sidebar	boolean	N/A
singleColumn	boolean	N/A
showRelatedInArticle	boolean	N/A
noindex	boolean	N/A

Modify Menus

Main Menu

To add, remove, or reorganize top menu items, edit the files here. Specifically look for items with [[main]].

If you prefer the more traditional approach, delete content\config folder and enter a main menu entry inside the config.toml file

Social media

To edit your social media profile links, edit the files referenced above. Specifically, look for items with [[social]]

If you wish to globally use a large Twitter summary card when sharing posts, set the global parameter largeTwitterCard to true.

Web site analytics

If using Google Analytics, configure the ga_analytics global parameter in your site with your ID. You can opt to set a google tag manager using google_tag_manager_id.

If using Baidu Analytics, configure the baidu_analytics global parameter in your site with your ID.

If using Plausible Analytics, configure the plausible_analytics global parameters in your site with the following.

enable To enable plausible analytics change to true.

websiteDomain Set domain name of your website, most cases same as your base URL this is required.

plausibleDomain Default is set to plausible.io, this parameter is only required if plausible is self-hosted.

scriptName Default is set to plausible, this parameter is only required if using a custom name for script.

If using Matomo Analytics, configure the matomo_analytics global parameters in your site with the following.

enable To enable matomo analytics change to true.

websiteDomain Set the domain name of your website, in most cases same as your base URL this is required.

matomoDomain Set to Matomo domain

matomoSiteID Default is set to 1, change this to the siteid being tracked

Blog directory

Edit params.toml and change the mainSections key. Values will be directories where the blogs reside.

...
mainSections = ["posts", "docs", "blogs"]
...

For more info, see the Hugo docs.

Mobile menu positioning

The navigation menu when mobile browsing can be configured in config.toml to open right or left depending on preference. The "hamburger" menu icon will always display in the upper right hand corner regardless.

[params]
...
mobileNavigation = "left" # Mobile nav menu will open to the left of the screen.
...

Tags and Taxonomies

Show number of tags

The number of tags and taxonomies (including categories) that should be shown can be configured so that any more than this value will only be accessible when clicking the All Tags button. This is to ensure a large number of tags or categories can be easily managed without consuming excess screen real estate. Edit the numberOfTagsShown parameter and set accordingly.

[params]
...
numberOfTagsShown = 14 # Applies for all other default & custom taxonomies. e.g categories, brands see https://gohugo.io/content-management/taxonomies#what-is-a-taxonomy
...

Number of tags example

Images

A number of CSS classes are automatically added to images based on their source or type to aid you in any tweaks to the theme. These include:

• image_figure when the image appears inside a <figure> element
• image_internal when the image is local, within the site
• image_external when the image is loaded from a URL
• image_processed when the image has been passed through Hugo Pipes (requires the image to be using page bundles or be in the assets directory)
• image_unprocessed when the image has not been passed through Hugo Pipes
• image_thumbnail when the image is in a list of content excerpts
• image_featured when the image is a banner or hero image at the top of a post
• image_svg when the image is an SVG (and thus cannot be run through Hugo Pipes)

Most images in Hugo Clarity are loaded lazy and asynchronously to improve site speed. Images that are not loaded in this manner include the site's logo.

Images, whether used within Markdown content or using parameters like featureImage or thumbnail, can be local or remote images. Remote images (starting with http...) will automatically be downloaded, stored and optimized by Hugo Clarity, so that the finished site will only serve local images.

Organizing page resources

By default, Hugo Clarity assumes that page resources -- images and other related files -- are stored in the static or assets directories. Alternatively, you can opt-in to using Hugo page bundles by setting the usePageBundles option to true in your site parameters. Using this method, you keep a post's assets in the same directory as the post itself.

If you have an existing site that is not using page bundles but would like to start with new posts, usePageBundles can be overridden at the post level in the front matter. If it is not set in the post, it will default to the site's parameter. Take a look at exampleSite/content/post/bundle/index.md for more information and an example of overriding this setting on an individual post.

Support for modern image formats

If you are using page bundles (see above) and reference sample.jpg in your post, Hugo Clarity will check to see if the same image (based on filename) exists in the modern formats of WebP, AVIF or JXL. If it does, these will be presented to browsers as alternative options. Browsers that support these formats and the <picture> element will load them, while browsers that do not will fall-back to the default image.

Note that this does not create the other versions of the image for you, it simply checks to see if they exist. You may want to automate this process in your site build; here is one example.

Image captions

Image captions are automatically generated. If an image has title text, the caption will be created from it; if an image has no title text, the alt text will be used. To display an image with alt text but no caption, use title text of a single space (" ").

Examples of captions:

• ![Jane Doe](../images/jane-doe.png) will display the local jane-doe.png image with a caption of "Jane Doe".
• ![Jane Doe](https://raw.githubusercontent.com/chipzoller/hugo-clarity/master/exampleSite/static/images/jane-doe.png "This is Jane Doe") will display the remote image jane-doe.png with a caption of "This is Jane Doe".
• ![A building](../images/building.png " ") will display the local image building.png with no caption.

Examples of this can also be found in the "Markdown Syntax Guide" post in the example site content.

NOTE: Due to limitations in Markdown, single and double quotes should not be used within alt or title text.

Adding figure positions to image captions

You have the option of prepending a desired string such as "Figure N" to the caption text of images within an article's content.

Two global settings control this feature:

• figurePositionLabel is a string which will be prepended to any caption text of an article image; by default this is set to "Figure".
• figurePositionShow controls, globally, whether to show this label. (It does not affect the visibility of image captions in general, only the prepended figure position text.) For more granular control, figurePositionShow can be overridden at the article level if desired.

Figure numbers will be automatically inserted after the figurePositionLabel text, starting from the top of the article and increasing as you move down.

Example of image with figure positions added

Assume that figurePositionLabel is set to "Figure" in config.toml and this is the first image in a given article.

![A schematic for using Antrea with Kubernetes](./images/image-figure.png "Antrea Kubernetes nodes prepared")

Inline images

To make an image inline, append :inline to its alt text.

Inline images example

<!-- an inline image without alt text -->

![:inline](someImageUrl)

<!-- an inline image with alt text -->

![text describing the image:inline](someOtherImageUrl)

Float images to the left

To align a blog image to the left, append :left to its alt text. Article text will then flow to the right of the image.

Float images left example

<!-- a left-floated image without alt text -->

![:left](someImageUrl)

<!-- a left-floated image with alt text -->

![text describing the image:left](someOtherImageUrl)

Float images to the right

To align a blog image to the right, append :right to its alt text. Article text will then flow to the left of the image.

Float images right example

<!-- a right-floated image without alt text -->

![:right](someImageUrl)

<!-- a right-floated image with alt text -->

![text describing the image:right](someOtherImageUrl)

Round borders for images

To make the image borders round, append ::round to its alt text. This is a pre-defined image class commonly used to display portrait images. Note that round is just another class and it can be mixed with other classes separated by space.

Round borders for images example

<!-- an image without alt text and round borders-->

![::round](someImageUrl)

<!-- an image with alt text and round borders-->

![text describing the image::round](someOtherImageUrl)

<!-- a left-floating image without alt text and with round borders-->

![:left::round](someOtherImageUrl)

Add classes to images

To add a CSS class to an image, append ::<classname> to its alt text. You can also add multiple classes to an image separated by space. ::<classname1> <classname2>.

Image classes example

<!-- an image without alt text -->

![::img-medium](someImageUrl)

<!-- an image with alt text -->

![text describing the image::img-large img-shadow](someOtherImageUrl)

Featured image

Each article can specify an image that appears at the top of the content.

...
featureImage: "images/2020-04/capv-overview/featured.jpg"
...

The path for the featured image is relative to the static directory if not using Page Bundles, and relative to the post's own directory if using them.

Two other frontmatter settings allow you to set alt text for the featured image and an optional caption.

...
featureImageAlt: 'Text describing the featured image' # Alternative text for featured image.
featureImageCap: 'A caption appearing below the image.' # Caption (optional).
...

Unless specified using featureImageCap, a caption will not be generated for the featured image.

Thumbnail image

Each article can specify a thumbnail image which will be displayed on the left of the article's card on the home page and in lists of articles.

...
thumbnail: "images/2020-04/capv-overview/thumbnail.jpg"
...

Thumbnails look best when square (height:width ratio of 1:1) and at least 150x150 pixels.

The path for the thumbnail image is relative to the static directory if not using Page Bundles, and relative to the post's own directory if using them.

Share image

Each article can specify a share image which will used when the article is shared on social media.

...
shareImage: "images/theImageToBeUsedOnShare.png"
...

If a share image is not specified, the order of precedence that will be used to determine which image applies is thumbnail => featureImage => fallbackOgImage. That is, if no thumbnail is specified, the featured image will be used; if neither is specified, the fallback image will be used.

When sharing a link to the home page of the site (as opposed to a specific article), the fallbackOgImage will be used.

The path for the share image is relative to the static directory if not using Page Bundles, and relative to the post's own directory if using them.

Logo alignment

You can left align or center your site's logo.

...
centerLogo = true # Change to false to align left
...

If no logo is specified, the title of the site will appear in its place.

Code

Display line numbers

Choose whether to display line numbers within a code block globally with the parameter codeLineNumbers setting to true or false.

[params]
...
codeLineNumbers = true # Shows line numbers for all code blocks globally.
...

Limit code block height

You can globally control the number of lines which are displayed by default for your code blocks. Code which has the number of lines exceed this value will dynamically cause two code block expansion buttons to appear, allowing the user to expand to full length and contract. This is useful when sharing code or scripts with tens or hundreds of lines where you wish to control how many are displayed. Under params in config.toml file, add a value as follows:

[params]
...
codeMaxLines = 10 # Maximum number of lines to be shown by default across all articles.
...

If the value already exists, change it to the desired number. This will apply globally.

If you need more granular control, this parameter can be overridden at the blog article level. Add the same value to your article frontmatter as follows:

...
codeMaxLines = 15 # Maximum number of lines to be shown in code blocks in this blog post.
...

If codeMaxLines is specified both in config.toml and in the article frontmatter, the value specified in the article frontmatter will apply to the given article. In the above example, the global default is 10 and yet the article value is 15 so code blocks in this article will auto-collapse after 15 lines.

If codeMaxLines is not specified anywhere, an internal default value of 100 will be assumed.

Line Highlighting

It is possible to highlight specific lines in a code block by applying {hl_lines=[7]} after the fence and language. For example, the below snippet will highlight lines 7 and 8 in the code block to which it is applied.

```yaml {hl_lines=[7,8]}

Ranges are also supported by quoting the range inside the braces.

```yaml {hl_lines=["7-18"]}

Table of contents

Each article can optionally have a table of contents (TOC) generated for it based on top-level links. By configuring the toc parameter in the article frontmatter and setting it to true, a TOC will be generated only for that article. The TOC will then render under the featured image.

Table of contents (TOC) example

Pinning featured posts

This allows you to show the featured posts at the top of the post list.

Use the site configuration option pinFeatured to enable/disable it, and the option numberOfPinnedPosts to control how many posts to be pinned.

Custom CSS and JS

To minimize HTTP requests per page, we would recommend loading CSS styles and JavaScript helpers in single bundles. That is to say, one CSS file and one JavaScript file. Using Hugo minify functions, these files will be minified to optimize the size.

Going by the above 👆🏻 reason, we recommend adding custom CSS and JS via these files:

1. _override.sass. This file should only be used to override sass & css variables e.g theme colors
2. _custom.sass. This file should only be used to override everything else except sass & css variables.
3. custom.js.

Pro Tip: Ensure that your changes are git trackable by creating these files outside the theme directory. That is, at the root level of your site's directory. See tree below.

├── yourSite
│   ├── archetypes
│   │   └── post.md
│   ├── assets
│   │   ├── js
│   │   │   └── custom.js
│   │   └── sass
│   │       ├── _custom.sass
│   │       └── _override.sass
│   ├── config
│   │   └── _default
│   │       ├── config.toml
│   │       ├── configTaxo.toml
│   │       ├── languages.toml
│   │       ├── markup.toml
│   │       ├── menus
│   │       │   ├── menu.en.toml
│   │       │   └── menu.pt.toml
│   │       └── params.toml
│   ├── content
│   │   ├── _index.md

However, sometimes you may need to load additional style or script files. In such cases, you can add custom .css and .js files by listing them in the config.toml file (see the snippet below). Similar to images, these paths should be relative to the static directory.

[params]
...
customCSS = ["css/custom.css"] # Include custom CSS files
customJS = ["js/custom.js"] # Include custom JS files
...

Notices

This theme includes functionality to display some "hightlight blocks" - called "notices" using a shortcode.

For example, see the shortcode markup below will render as a notice:

{{% notice note "Note Title" */%}}
This will be the content of the note.
{{% /notice %}}

For more examples see the "Notices" page in the exampleSite.

Site Disclaimer

The theme includes the ability to put a Disclaimer on your website (e.g. "My views are my own and not my employer's"). Currently, the disclaimer displays in the sidebar under the author information. You can enable and customize it as follows:

• Uncomment the sidebardisclaimer parameter in config/_default/params.toml.
• Uncomment and edit the disclaimerText parameter in config/_default/params.toml.
• Add and modify an override for the div.sidebardisclaimer selector in assets/saas/_custom.sass.

div.sidebardisclaimer{padding: 0px 10px 15px 10px;margin: 20px 5px 20px 5px;border: 1px solid #eee;border-left-width: 10px;border-right-width: 10px;border-radius: 5px 5px 5px 5px;border-left-color: orange;border-right-color: orange;border-top-color:orange;border-bottom-color:orange}

The code for the sidebar disclaimer text is in layouts/partials/sidebar.html. The default color scheme displays in both light and dark mode. Additionally, the styling has been placed into _custom.sass so that it's easily editable with beginner's understanding of CSS properties and easier to find.

Forcing light or dark mode

By default, sites authored using Clarity will load in the browser with the user's system-wide settings. I.e., if the underlying OS is set to dark mode, the site will automatically load in dark mode. Regardless of the default mode, a UI control switch exists to override the theme mode at the user's discretion.

In order to override this behavior and force one mode or another, add either enforceLightMode or enforceDarkMode to your config.toml file. If neither value is present, add it.

To enforce Light Mode by default, turn enforceLightMode to true.

To enforce Dark Mode by default, turn enforceDarkMode to true

[params]
...
enforceLightMode = true # Force the site to always load in light mode.
...

Please note that you cannot enforce both modes at the same time. It wouldn't make sense, would it?

⚠️ Please also note that the mode toggle UI will remain in place. That way, if a user prefers dark mode, they can have their way. The best of both worlds.

I18N

This theme supports Multilingual (i18n / internationalization / translations)

The exampleSite gives you some examples already. You may extend the multilingual functionality by following the official documentation.

Things to consider in multilingual:

• supported languages are configured in config/_default/languages.toml
• add new language support by creating a new file inside i18n directory. Check for missing translations using hugo server --i18n-warnings
• taxonomy names (tags, categories, etc...) are translated in i18n as well (translate the key)
• menus are translated manually in the config files config/_default/menus/menu.xx.toml
• menu's languages list are semi-hardcoded. You may chose another text for the menu entry with languageMenuName. Please, do better and create a PR for that.
• content must be translated individually. Read the official documentation for information on how to do it.

note: if you do NOT want any translations (thus removing the translations menu entry), then you must not have any translations. In the exampleSite that's as easy as removing the extra translations from the config/_default/... or executing this one-liner:

sed '/^\[pt]$/,$d' -i config/_default/languages.toml && rm config/_default/menus/menu.pt.toml

To change the values of translatable text, such as read_more or copyright, edit the values in the language file you are using in the i18n directory. If you have no such directory, copy the one inside the theme to your root Hugo directory.

Hooks

Clarity provides some hooks for adding code on a page.

If you need to add some code (CSS import, HTML meta or similar) to the head section on every page, add a partial to your project:

layouts/partials/hooks/head-end.html

Similar, if you want to add some code right before the body end (e.g fonts' links), create your own version of the following file:

layouts/partials/hooks/body-end.html

Comments

Clarity supports Hugo built-in Disqus partial. You can enable Disqus simply by setting disqusShortname in your configuration file.

You can also override layouts/partials/comments.html to take advantage of disqus comments Alternatives for details.

Please leave #disqusShortname = "" commented out if you decide to use other comments tools

You can disable them site-wide by setting comments = false under [params] from config.toml file and vice versa. Omitting that setting will default to comments will be enabled.

You can override these setting from each post individually. For example, you may want to disable/enable comments on specific posts. Use the same syntax used on the config.toml file.

please use comments and not comment

Utterances Commenting Support

If you wish use Utterances comments on your site, you'll need to perform the following:

• Ensure you have a GitHub public repository, which you've granted permissions to the Utterances GitHub App.
• Comment out the line for disqusShortname = "" in the /config/_default/config.toml file.
• Set comments = true in the /config/_default/params.toml file.
• Configure the utterances parameters in the /config/_default/params.toml file.
• Optionally, you can choose a label that will be assigned to all issues created by Utterances. The label must exist in your Github repository, as Utterances cannot attach labels that do not exist. Configure utterancesLabel parameter in /config/_default/params.toml file, after you have added a label to your Github repository Issues labels. Labels are case sensitive and support Emoji in label names. ✨💬✨

Utterances is loaded in the comments.html partial by referring to the utterances.html partial. Since single.html layout loads comments if comments are enabled, you must ensure both the comments and utterances parameters are configured.

Math notation

Clarity uses KaTeX for math type setting if enableMathNotation is set to true in global or page parameters (the latter takes precedence).

Also see supported TeX commands in KaTeX.

If you want chemical typesetting provided by the mhchem extension, first copy [site]/themes/clarity/layouts/partials/math.html to [site]/layouts/partials/math.html:

# cd /path/to/site
mkdir -p layouts/partials && cp themes/clarity/layouts/partials/math.html layouts/partials/math.html

Then add the corresponding line as its README suggested (without the + sign):

<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/[email protected]/dist/katex.min.css" integrity="sha384-AfEj0r4/OFrOo5t7NnNe46zW/tFgW6x/bCJG8FqQCEo3+Aro6EYUG4+cU+KJWu/X" crossorigin="anonymous">

<script defer src="https://cdn.jsdelivr.net/npm/[email protected]/dist/katex.min.js" integrity="sha384-g7c+Jr9ZivxKLnZTDUhnkOnsh30B4H0rpLUpJ4jAIKs4fnJI+sEnkvrMWph2EDg4" crossorigin="anonymous"></script>

+ <script defer src="https://cdn.jsdelivr.net/npm/[email protected]/dist/contrib/mhchem.min.js" integrity="sha384-5gCAXJ0ZgozlShOzzT0OWArn7yCPGWVIvgo+BAd8NUKbCmulrJiQuCVR9cHlPHeG" crossorigin="anonymous"></script>

<script defer src="https://cdn.jsdelivr.net/npm/[email protected]/dist/contrib/auto-render.min.js" integrity="sha384-mll67QQFJfxn0IYznZYonOWZ644AWYC+Pt2cHqMaRhXVrursRwvLnLaebdGIlYNa" crossorigin="anonymous"
  onload="renderMathInElement(document.body);"></script>

The added line should be before auto-render.min.js and after katex.min.js.

MathJax

The new version of MathJax has comparable performance to KaTeX and better support for TeX commands.

If you prefer MathJax, create a blank [site]/layouts/partials/math.html and add the following two lines:

<script src="https://polyfill.io/v3/polyfill.min.js?features=es6"></script>
<script id="MathJax-script" async src="https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js"></script>

This file will take precedence over the one Clarity provides and the site will load MathJax instead of KaTeX.

Related Content

Related content within a series taxonomy can be shown at the end of a piece of content, or optionally on the sidebar above the Related Content section.

The site configuration option showRelatedInArticle controls if this option is enabled. The same configuration option can be used in a posts frontmatter to disable the feature (but the site configuration overrides the per-page option).

Likewise, the site configuration option showRelatedInSidebar controls if related content is shown on the sidebar. There is no corresponding option within a post to disable this.

Maps

Creating and including a map

First create a map for free on https://umap.openstreetmap.fr/en/. Then include this map by using the openstreetmap shortcode, e.g. {{<openstreetmap mapName="demo-map_1" >}}

Options

The only required parameter is mapName. All other parameters are completely optional.

Available parameters are:

• coordX (default auto)
• coordY (default auto)
• scale (default auto)
• scaleControl (default true)
• miniMap (default false)
• scrollWheelZoom (default true)
• zoomControl (default true)
• allowEdit (default false)
• moreControl (default true)
• searchControl (default true)
• tilelayersControl (default null)
• embedControl (default null)
• datalayersControl (default true)
• onLoadPanel (default none)
• captionBar (default false)

Search

Search is currently a BETA feature. Ensure you have these settings inside your configuration files:

# config/_default/config.toml
[outputs]
  home = ["HTML", "RSS","JSON"]

# config/_default/params.toml
enableSearch = true

Next add the search.md file from the exampleSite and add it to your content folder. This is not necessary if you recently created a site based on the example site and already have the file.

Compose, from which this feature is derived, implements fuse.js to enable search functionality. At the time of this writing, search on this theme takes either of the following forms:

1. Passive search

   This occurs only when the user loads the search page i.e /search/. They can directly navigate to that url. Alternatively, the user can type the search query on the search field and hit enter. They will be redirected to the search page which will contain matched results if any.

   Currently, this only works on the default language. Support for multilingual passive search is coming soon.

2. Live search

   This behavior will be obvious as the user types a search query on the search field. All valid search queries will yield a list of quick links or a simple "no matches found". Else, the user will be prompted to continue typing.

   Live search works even for multilingual sites.

   For Chinese-like languages, it may or may not work.

Search Scope

• Searching within a section will yield results from that section.

  For example, if you have 3 sections in your content i.e blog, docs & examples, searching in the docs section will only produce results for that section.

• Searching outside a section will search the entire site.

  For example, with the above setup, searching from the homepage will produce results from the entire site.

Contributing

Please read our contribution guidelines, and thank you for being involved!

Code of conduct

Hugo Clarity has a code of conduct. Please follow it in all your interactions with the project.

License

Hugo Clarity is open-sourced under the MIT license.

hugo-clarity's Issues

For me the Author/Intro is missing from the homepage. i see it on posts and other pages.

https://inspiring-jang-56bfc9.netlify.app/ example.

thumbnail 404 not found in tag page

hugo version?

ERROR 2020/08/05 11:53:04 HUGO-CLARITY theme does not support Hugo version 0.54.0. Minimum version required is 0.63.0
But i already have the latest version : hugo 0.74.3 already installed

I can't upload from github to netlify because of this error.

Theme breaks when deploying via netlify

Hi,

I have an issue where the theme seems to break when deploying my site with netlify. I'm using the latest version of the theme and Hugo 0.75.0 extended. The site and theme render fine when running locally. However when built via netlify, the build succeeds but the site looks like this: https://5f60b89d250b6d000748b738--vigilant-raman-d8e917.netlify.app/

I have not had this issue with any other themes including the theme I have reverted to, which is why I'm raising it as an issue as the problem seems to be specific to hugo-clarity. I'm not sure where to look next. Any thoughts or ideas?

i18n: support Multilingual

Just to keep things tidy, here is a Feature Request for this PR: #21 #39

Feature request: support search.

Docs: Getting up and running > Option 1: needs a few clarifications

I have checked all the prerequisites below and I'm yet experiencing a problem

• Read the README.md
• Have the extended version of Hugo installed
• Used the exampleSite's config.toml as a reference

Describe the bug

Unless I'm misreading option 1 or missing something, following its steps will create the following directory structure:

yourSiteName
yourSiteName/config.toml [default new site config]
yourSiteName/exampleSite
yourSiteName/exampleSite/config.toml [Hugo Clarity's exampleSite config]
yourSiteName/themes/hugo-clarity

Thus when you run hugo server, you'll still be in the root project folder (yourSiteName above) and it will use the default new site config to render the site, not the example site's. If you cd into exampleSite and try to run hugo server, it'll complain that the theme isn't in a subdirectory.

I think instead of
cp -a themes/hugo-clarity/exampleSite/ .
perhaps you meant
cp -a themes/hugo-clarity/exampleSite/* .
?

Additionally, as a final step before running hugo server I would suggest instructing users to edit the config.toml file and change the baseurl, or CSS files will be broken.

Desktop (please complete the following information):

• OS: Ubuntu 20.04
• Browser Firefox 80.0

Error with "highlight html" function

The function {{< highlight html >}} for code blocks in the source file shows an error on my webspace when I move the mouse pointer over a code box (see my webside). It does not matter which browser (e.g. Firefox or Chromium) I use, the error message appears on both browsers.

But if I call this page locally with the built-in webserver of hugo, no error message appears.

The page is available online at:
https://bluelupo.info/post/aktuelle-betaversionen-von-firefox-nutzen/

Here you can see the error.

regards
Michael

Unable to hide Language selection with site variable

I have checked all the prerequisites below and I'm yet experiencing a problem

• Read the README.md
• Have the extended version of Hugo installed
• Used the exampleSite's config.toml as a reference

Describe the bug

Setting the isMultiLingual site variable to 0 in the config.toml does not cause the Language selection nav to be hidden (or not rendered). Should this be expected behavior? The nav.html file contains a check if {{ if .Site.IsMultiLingual }}, Should the language navigation be disabled another way?

Desktop (please complete the following information):

• OS: Windows 10 w/ WSL running Hugo on Ubuntu 20.04
• Browser: Edge v 87.0.656.0 and 85.0.564.63

If no logo is specified allow site title to be used in place.

Clarification on getting started instructions

Apologies if I'm missing something basic here but seems like the getting started Option 1 steps are not correct in README.md

Currently the cp command here results in a exampleSite directory being copied to base dir of your new site. This doesn't work as expected.

hugo new site yourSiteName
cd yourSiteName
git init
git submodule add https://github.com/chipzoller/hugo-clarity themes/hugo-clarity
cp -a themes/hugo-clarity/exampleSite/ .

When I did the following it does work as expected.

cp -a themes/hugo-clarity/exampleSite/* .

Adding double quotes to image caption text breaks rendering past that point.

I have checked all the prerequisites below and I'm yet experiencing a problem

• [ x] Read the README.md
• [x ] Have the extended version of Hugo installed
• [ x] Used the exampleSite's config.toml as a reference

Describe the bug
When an image caption text contains double quotes, the rendered output breaks at that point. Removing double quotes shows all the text as expected.

Google Analytics Parameter is missing from config.toml

CSS file are not available in Sample project

I tried to run the project files using the instructions from readme page. but no luck in finding the same look and feel as mentioned.

Please suggest
below screenshots for reference

How to override css and js with additional files?

Twitter large summary card support

https://developer.twitter.com/en/docs/tweets/optimize-with-cards/overview/summary-card-with-large-image

It would be great to support this

Right now, they come out like this:

Math notation does not work on exampleSite

Hello,
I have installed the last version of hugo 0.74.3 extended, and setup a new site with the clarity theme as a git submodule then copy the given exampleSite at the root.
The "Math Typesetting" page does not display math notation.

Desktop (please complete the following information):

• OS: Windows 10
• Browser: chrome and edge

Thanks

code block doesnt show all lines after clicking expansion button

Suggestion: Use Copyright Setting from config.toml for footer by default

As the title states I think it might be good to user {{ .Site.Copyright }} for the footer by default.

As a newbie to hugo I had to take out the trusted grep -ri hammer to find where the copyright notice is defined in the theme.

Title appears twice on home page

Featured posts parameter ignored

The front matter of the post archetype has a parameter named "featured" described as follows:

featured: false # Sets if post is a featured post, making appear on the home page side bar.

Setting this parameter to true does not cause the post to appear in the side bar. To make the post appear in the "Featured Posts" section of the sidebar a tag with name featured is required.

I believe this is because in the sidebar.html the code is looking at tags instead of parameters for creating the list of featured posts:

<h2 class="mt-4">Featured Posts</h2>
<ul>
{{ range .Site.Taxonomies.tags.featured }}
 {{- if ne $title .Title }}
  <li>
    <a href="{{ .Permalink }}" class="nav-link">{{ .Title }}</a>
  </li>
{{- end }}
{{ end }}
</ul>

Note that even with the featured parameter set to false, if the tag exists the post is show in the side bar.

Editing footer breaks links menu in header

Hi,

Firstly, awesome theme!

I've noticed that if you modify or remove the following code in footer.html: <span class = 'year'></span>, it breaks the links menu in the header. The links menu no longer folds out and will act as a home button when you click it.

I've been able to validate this locally by commenting out that part of the line (or the entire line).

Figuring out why this is happening is beyond my skills with Hugo but I wouldn't expect an edit in the footer to break something in the header, so it took a little while to track down.

How to edit the social icons.

Hello,
Lets say I want to use a different selfmade icon like I don't want linkedin and maybe want an email icon. How can I do it.

"Series" is not visible on the Side Bar

I have checked all the prerequisites below and I'm yet experiencing a problem

• [Yes ] Read the README.md
• [Yes] Have the extended version of Hugo installed
• [Yes ] Used the exampleSite's config.toml as a reference

Describe the bug
"Series" is not visible on the Side Bar. Categories and Tags are visible. But in the Demo URL, ont he Side Bar, Series is vivible. I tried to check various options in config.toml, but could not get to make it visible on my local version,

Desktop (please complete the following information):

• OS: [Windows 10]
• Browser [Chrome 85]

Asset variable paths assume particular directory structure

I have checked all the prerequisites below and I'm yet experiencing a problem

• Read the README.md
• Have the extended version of Hugo installed
• Used the exampleSite's config.toml as a reference

Describe the bug

_variables.sass has paths for fonts, icons and images with a leading ../. This assumes a particular directory structure in the rendered site. If, for instance, your blog posts have paths like posts/2020/09/01/blog-post-title, those asset paths are not going to be correct and the assets won't load.

It seems to me like these paths should be set either from the root directory (of the rendered website, not the Hugo root), or using the baseurl Hugo variable to give an accurate reference to the assets.

Desktop (please complete the following information):

• OS: Ubuntu 20.04
• Browser: Firefox 80.0.1

Should be able to define default colour mode from config.toml

Hi,
I think, we should be able to define default colour mode ( light or dark ) from config.toml
thank you for this theme.

rmarkdown support

Hi!

I'm using this awesome theme to blog via R's package {blogdown} (see example here) but for some reason all code features won't work (folding, line numbers etc). My guess is it occurs because of code block with rmarkdown are enclosed like

<pre class="r"><code>
## code goes here ##
</code>"

What should I change in code.js, _syntax.sass or elsewhere to enable r class and get it working?

obs.: .md theme's examples renders just fine

Coding style

I found that this theme contains different coding styles about HTML element property.

<!--no spaces delimiter-->
<meta property="foo" content="bar" />

<!--with spaces delimiter-->
<meta property = "fizz" content = "buzz" />

According to the standard, it doesn't matter. However, it is better to use the same coding style. So which one should be used when making a PR?

References:

• Using spaces before and after the = sign of HTML element attribute

If draft = true, it is not rendered. in development mode

draft = true is a valid post configuration.

this is used when writing a post but not having it generated with hugo build process. when draft = true the page is not rendered for preview on localhost:1313

this was tested in examplesite

Currently viewed post is filtered out of recent and featured lists

When a post in recent and featured list is viewed, it is filtered out of the recent and featured list. I think it would make more sense to keep these two lists consistent.
Thank you for your great work.

Light/Dark Mode Not Working on Rendered Site

I have checked all the prerequisites below and I'm yet experiencing a problem

• [X ] Read the README.md
• [X ] Have the extended version of Hugo installed
• Used the exampleSite's config.toml as a reference

Describe the bug

Regardless of what browser I use (Firefox, Brave, Edge, etc...) after building and deploying site into production, the toggle switch for Light/Dark mode ceases to work. I have no issue with localhost:1313, but once I upload the files to my server (https://mcalynn.com/), clicking the "sun" (☀) does nothing. No dark mode enabled.

C:\hugo>hugo env
Hugo Static Site Generator v0.74.3/extended windows/amd64 BuildDate: unknown
GOOS="windows"
GOARCH="amd64"
GOVERSION="go1.14.3"

C:\hugo\mcalynn>c:\hugo\hugo.exe server -v -w -t hugo-clarity
INFO 2020/08/31 14:06:23 No translation bundle found for default language "en"
INFO 2020/08/31 14:06:23 Translation func for language en not found, use default.
INFO 2020/08/31 14:06:23 i18n not initialized; if you need string translations, check that you have a bundle in /i18n that matches the site language or the default language.
INFO 2020/08/31 14:06:23 Using config file:
Building sites … INFO 2020/08/31 14:06:23 syncing static files to C:\hugo\mcalynn
WARN 2020/08/31 14:06:23 The []interface {} data from 'menu.yaml' overridden by higher precedence []interface {} data already in the data tree
WARN 2020/08/31 14:06:23 The []interface {} data from 'social.yaml' overridden by higher precedence []interface {} data already in the data tree

               | EN

-------------------+-----
Pages | 60
Paginator pages | 1
Non-page files | 1
Static files | 64
Processed images | 0
Aliases | 32
Sitemaps | 1
Cleaned | 0

Built in 159 ms
Watching for changes in C:\hugo\mcalynn{archetypes,content,data,layouts,static,themes}
Watching for config changes in C:\hugo\mcalynn\config.toml, C:\hugo\mcalynn\themes\hugo-clarity\config.toml
Environment: "development"
Serving pages from memory
Running in Fast Render Mode. For full rebuilds on change: hugo server --disableFastRender
Web Server is available at http://localhost:1313/ (bind address 127.0.0.1)
Press Ctrl+C to stop

Dropdown menus doen't work in some browsers.

I have checked all the prerequisites below and I'm yet experiencing a problem

• Read the README.md
• Have the extended version of Hugo installed
• Used the exampleSite's config.toml as a reference

Describe the bug

Preview: https://razonyang.com/en/

Desktop (please complete the following information):

• UC Browser V13.3.0.1302(Android)
• MicroSoft Edge(Windows 10)

Btw, is the theme not compatible with any version of IE?

Is there an easy way to set default theme to light?

I have checked all the prerequisites below and I'm yet experiencing a problem

• Read the README.md
• Have the extended version of Hugo installed
• Used the exampleSite's config.toml as a reference

Describe the bug

I really liked the hugo-clarity theme and would like to use for my blog but is there a way or global variable which i can set, so that the default theme layout is always light.

In the current setup it always defaults to dark theme and I somehow felt it light theme should have be the default one.

I know there has been an enhancement request to make it a part config.toml but for the time being if can be somehow controlled via variables.sass or base.sass?

Desktop (please complete the following information):

• OS: [e.g. Ubuntu]
• Browser [firefox 80.0.1]

Align with Clarity 4

Hugo-clarity theme should ultimately align with Clarity 4.0.0.

social urls missing from config.toml

social usernames for github/linkedin/twitter in header are missing from config.toml

README error regarding custom javascript

In the README, there is this text:

Going by the above 👆🏻 reason, we recommend adding custom css and js via this custom sass file and custom javascript file.

But the custom javascript link to: https://github.com/chipzoller/hugo-clarity/blob/master/assets/js/_custom.js gives a 404 error.

If possible, please document how to add javascript files to a blog using this theme, such that they end up in the bundled JS file.

Posts with future `date` in frontmatter invalid

If setting the date key in the post's frontmatter to a day in the future, Hugo won't render the page. Is this something we can allow? Main use case I can forsee is when someone wants to use a CD platform to publish a post on a given timer and flip draft from true to false simultaneously.

home page doesn't have any meta description content

I have checked all the prerequisites below and I'm yet experiencing a problem

• Read the README.md
• Have the extended version of Hugo installed
• Used the exampleSite's config.toml as a reference

Describe the bug

When sharing the root of a site, there is nothing but the title and an image:

The meta tags for description are empty:

<meta property = "og:locale" content = "en_US" />
<meta property="og:type" content="website">
<meta name="description" content="">
<meta name = "twitter:card" content = "summary" />
<meta name = "twitter:creator" content = "@adriandotgoins">
<meta name = "twitter:title" content = "" />
<meta property = "og:url" content = "https://adriandotgoins.com/" />
<meta property = "og:title" content = "" />
<meta property = "og:description" content = "" />
<meta property = "og:image" content = "https://adriandotgoins.com/images/profile-picture-250px.png" />

I was able to fix this with an if/then block, but that may not be the correct way:

{{- if .IsHome }}
<meta property="og:type" content="website">
<meta property = "og:title" content = "{{ $site }}" />
<meta name = "twitter:title" content = "{{ $site }}" />
<meta property = "og:description" content = "{{ .Site.Params.description | truncate 160 }}" />
<meta name="description" content="{{ .Site.Params.description | truncate 160 }}">
{{- else }}
<meta property = "og:description" content = "{{ $summary }}" />
<meta property = "og:title" content = "{{ $title }}" />
<meta property="og:type" content="article">
<meta name="description" content="{{ $summary }}">
<meta name = "twitter:title" content = "{{ .Title }}" />
{{- end }}

This allowed me to use a description field under [params] in config.toml that gets picked up on the home page.

Desktop (please complete the following information):

• OS: macOS Catalina
• Browser Firefox 80.0

when running hugo server locally, css does not work due to integrity.

to get it to work locally on my mac i had to disable the data integrity lines in baseof.html

Dark mode text colour & code fence highlighting colour

Hi,

Having played around with the theme for a few days, I have some usability suggestions:

1. In dark mode, I think the text colour of #FFFFFF can become a bit straining on the eyes. In clarity, the predominant text colour for dark mode is #ADBBC4, and I think making this the default (or making it configurable) would be an improvement.
2. When highlighting lines in a code fence with line numbers enabled, the line numbers are extremely difficult to read because the colours of the highlight and the line number are too similar. This is worse when in dark mode because the code fence highlight colour is lighter, reducing contrast even further. A possible solution would be to make the line number colour on a highlighted line the same colour as the text (#FFFFFF).

Thanks for the great work with the theme, it's awesome!

Twitter Share Link doesn't work by default.

I have checked all the prerequisites below and I'm yet experiencing a problem

• Read the README.md
• Have the extended version of Hugo installed
• Used the exampleSite's config.toml as a reference

Describe the bug

Twitter Share Link doesn't work by default.

To make it work I edited the layouts/partials/share.html and added | urlize behind the .Permalink entries.

Thumbnail image path for page bundles.

Hello and thank you for this amazing theme.
I'd like to ask 3 questions I couldn't find an answer for in the documentation:

1. I'm trying to keep posts and their resources (images, attachments, ecc) within the content folder, leveraging page bundles. One thing I noticed, the thumbnail image path apparently always points to the static folder. I couldn't manage to keep all the post's content within the same post folder "/content/post/2020-10-10-post-title-folder/"
   is there a way to do so? or am I missing something? what would be the best practice in terms of content management?

2. what would be the best way to customise the theme (color scheme, fonts, ecc)

3. I noticed the theme does not have "reading time" for articles and internal search option to search through the posts. I wonder a scenario where I have hundreds of posts in my blog and and I want to search for a word or a phrase. How would one achieve this?

Thanks and Regards,
Nicola

How do I change the site title?

I want to change the name of the theme to my website name? How?

Thansks.

Site doesn't build

I have checked all the prerequisites below and I'm yet experiencing a problem

• Read the README.md
• Have the extended version of Hugo installed
• Used the exampleSite's config.toml as a reference

Describe the bug

I tried to install this theme by following this procedure:

hugo new site mysite
cd mysite
git init
git submodule add https://github.com/chipzoller/hugo-clarity themes/hugo-clarity
cp -a themes/hugo-clarity/exampleSite/* .
hugo server

but immediately after executing hugo server I got the following error message:

$ hugo server
Start building sites …
ERROR 2020/10/23 23:52:10 Failed to get JSON resource "https://api.instagram.com/oembed/?url=https://www.instagram.com/p/BGvuInzyFAe/&maxwidth=640&omitscript=true": Failed to retrieve remote file: Bad Request
Built in 568 ms
Error: Error building site: logged 1 error(s)

Desktop (please complete the following information):

• OS: Windows 10 Version 10.0.19041.572
• hugo version: Hugo Static Site Generator v0.76.2/extended windows/amd64 BuildDate: unknown
• hugo-clarity: commit f59e0e1

consider renaming icons/ directory, as it clashes with some apache default configs

I'm getting 404 for everything in the icons/ directory after uploading it to my shared webspace. Turns out there is a name clash, as a icons/ directory in the root has a special meaning in some apache default confits. See https://electrictoolbox.com/apache-icons-directory/ or https://www.hosteurope.de/faq/webhosting/hochladen-von-webinhalten-ftp/verzeichnisnamen-mit-besonderer-funktion/ (german, sorry) for details – or google for something like ' "icons" directory webserver 404 '.

Hence please consider renaming the static/icons/ to something else.

Feature Request: Provide a git-trackable way to override theme variables/sass/js

In custom CSS and JS in the README you explain how to add Sass and JS to the theme, and how to override color variables: By editing files within the Hugo Clarity theme.

I appreciate that you created the custom.sass and custom.js files.

But modifying these files presents a problem: You either have to choose to continue using the theme as a git submodule (in which case you can't track modifications) or you have to commit the theme directory as a regular part of your own git repo (in which case you can't update the theme as a submodule).

Changing the color variables is worse: Now you're hacking the theme files themselves, meaning you have the problem above and if you ever update the theme, there will be merge conflicts.

Is there a way to provide support within the theme for custom Sass, JS and variable files within the parent project's directory? Perhaps in an assets directory of its own?

While it's true that right now you could override the CSS or JS in the parent project's directory, you can only do it by loading additional CSS/JS files (as you point out in that section of the README). And the only way to override the color variables -- because they're used throughout the theme's Sass files -- would be to replicate all the rendered CSS that those color variables touch.

What do you think?

All links opening in new tab

My site has all clickable links (internal and external) opening in a new tab. I'm fairly certain this has something to do with a URL setting like baseurl, but different options I have tried are not yielding any different results. Here is the first few lines of my config.toml file.

# set `baseurl` to your root domain
# if you set it to "/" share icons won't work properly on production
baseurl = "http://anticryptography.io/"  # Include trailing slash
title = "Anticryptography"
author = "Shawn Masters"
copyright = "Copyright © 2014–2020, Shawn Masters; all rights reserved."
canonifyurls = false
paginate = 10
theme = "hugo-clarity"

Add MailChimp Signup Form configuration

Dear author,

Thank you so much for this amazing theme. It would be great if you please provide the setting on config file for adding the the link of Sign up form provided by mail-chimp.

The requested setting is provided by another hugo theme.

Errors in sidebar.html

I am running hugo-clarity locally and receiving the following errors. I did clear the resources directory.

kevinbreit.net [new_theme●●] % hugo server -D
Building sites … ERROR 2020/08/03 16:35:01 render of "page" failed: execute of template failed: template: _default/single.html:24:6: executing "main" at <partial "sidebar" .>: error calling partial: "/Users/kbreit/Documents/Programming/kevinbreit.net/themes/hugo-clarity/layouts/partials/sidebar.html:35:45": execute of template failed: template: partials/sidebar.html:35:45: executing "partials/sidebar.html" at <first $numberOfTagsLimit>: error calling first: both limit and seq must be provided
ERROR 2020/08/03 16:35:01 render of "page" failed: execute of template failed: template: _default/single.html:24:6: executing "main" at <partial "sidebar" .>: error calling partial: "/Users/kbreit/Documents/Programming/kevinbreit.net/themes/hugo-clarity/layouts/partials/sidebar.html:35:45": execute of template failed: template: partials/sidebar.html:35:45: executing "partials/sidebar.html" at <first $numberOfTagsLimit>: error calling first: both limit and seq must be provided
ERROR 2020/08/03 16:35:01 render of "page" failed: execute of template failed: template: _default/single.html:24:6: executing "main" at <partial "sidebar" .>: error calling partial: "/Users/kbreit/Documents/Programming/kevinbreit.net/themes/hugo-clarity/layouts/partials/sidebar.html:35:45": execute of template failed: template: partials/sidebar.html:35:45: executing "partials/sidebar.html" at <first $numberOfTagsLimit>: error calling first: both limit and seq must be provided
ERROR 2020/08/03 16:35:01 render of "page" failed: execute of template failed: template: _default/single.html:24:6: executing "main" at <partial "sidebar" .>: error calling partial: "/Users/kbreit/Documents/Programming/kevinbreit.net/themes/hugo-clarity/layouts/partials/sidebar.html:35:45": execute of template failed: template: partials/sidebar.html:35:45: executing "partials/sidebar.html" at <first $numberOfTagsLimit>: error calling first: both limit and seq must be provided
Built in 165 ms
Error: Error building site: failed to render pages: render of "page" failed: execute of template failed: template: _default/single.html:24:6: executing "main" at <partial "sidebar" .>: error calling partial: "/Users/kbreit/Documents/Programming/kevinbreit.net/themes/hugo-clarity/layouts/partials/sidebar.html:35:45": execute of template failed: template: partials/sidebar.html:35:45: executing "partials/sidebar.html" at <first $numberOfTagsLimit>: error calling first: both limit and seq must be provided

Disqus shortname not enabling the inclusion

I've added the following shortcode to my config.toml

Disqus shortname

disqusShortname = "anticryptography"

and the generation step does not seem to be picking it up. There is no reference in any of the posts to Disqus. Does this require more than the shortname?