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. Test.
Light Mode | Dark Mode |
---|---|
![]() |
![]() |
Light Mode | Dark Mode |
---|---|
![]() |
![]() |
-
Blog with tagging and category options
-
Deeplinks
-
Native Image Lazy Loading
-
Customizable (see config)
-
Dark Mode (with UI controls for user preference setting)
-
Toggleable table of contents
-
Flexible image configuration
-
Logo alignment
-
Mobile support with configurable menu alignment
-
Syntax Highlighting
-
Rich code block functions including:
- Copy to clipboard
- Toggle line wrap (dynamic)
- Toggle line numbers
- Language label
- Toggle block expansion/contraction (dynamic)
To put it all in context, here is a preview showing all functionality.
Firstly, ensure you have installed the extended version of Hugo. See installation steps from Hugo's official docs.
There are at least two ways of quickly getting started with Hugo and the VMware Clarity theme:
Generate a new Hugo site and add this theme as a Git submodule inside your themes folder:
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/ .
Then run
hugo server
Hurray!
You can run your site directly from the exampleSite
. To do so, use the following commands:
git clone https://github.com/chipzoller/hugo-clarity
cd hugo-clarity/exampleSite/
hugo server --themesDir ../..
Although, option 2 is great for quick testing, it is somewhat problematic when you want to update your theme. You would need to be careful not to overwrite your changes.
Once set, jump over to the config.toml
file and start configuring your site.
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.
These options set global values that some pages or all pages in the site use by default.
Parameter | Value Type | Overidable on Page |
---|---|---|
author | string | no |
string | no | |
largeTwitterCard | boolean | no |
ga_analytics | string | no |
introDescription | string | no |
numberOfTagsShown | integer | no |
fallBackOgImage | file path (string) | no |
codeMaxLines | integer | yes |
codeLineNumbers | boolean | yes |
mainSections | array/string | no |
centerLogo | boolean | no |
logo | file 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 |
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 |
draft | boolean | N/A |
featured | boolean | N/A |
tags | array/string | N/A |
categories | array/string | N/A |
toc | boolean | N/A |
thumbnail | file path (string) | N/A |
featureImage | file path (string) | N/A |
shareImage | file path (string) | N/A |
codeMaxLines | integer | yes |
codeLineNumbers | boolean | yes |
figurePositionShow | boolean | yes |
figurePositionLabel | string | no |
To add, remove, or reorganize top menu items, edit this YAML file. These menu items also display any categories (taxonomies) that might be configured for articles.
To edit your social media profile links, edit this YAML file.
Edit the config.toml
file and change the mainSections
key. Values will be directories where the blogs reside.
[params]
...
mainSections = ["posts", "docs", "blogs"]
...
For more info, see the Hugo docs.
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.
...
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]
...
numberOfTagsShownPerArticle = 4 # Applies for categories & custom taxonomies. e.g brands
...
You have the option of adding captions to images in blog posts and automatically prepending a desired string such as "Figure N" to the alt text. This is controlled via two global settings.
figurePositionLabel
is a string which will be prepended to any alt text of an article image. By default, this is set to "Figure." And figurePositionShow
controls, globally, whether to show this label. It does not affect whether to show the image alt text, only the prefix figure caption. For more granular control, figurePositionShow
can be overridden at the article level if desired.
The number will be automatically calculated and assigned after the figurePositionLabel
text starting from the top of the article and counting down. Featured images will be excluded from this figuration.
In this example, figurePositionLabel
is set to "Figure" in config.toml
and this is the first image in a given article.
![Antrea Kubernetes nodes prepared](./images/image-figure.png)
To make a blog image inline, append :inline
to its alt text. Typically, inline images will have no alt text associated with them.
<!-- some image without alt text -->
![:inline](someImageUrl)
<!-- some image with alt text -->
![some alt text:inline](someOtherImageUrl)
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.
<!-- some image without alt text -->
![:left](someImageUrl)
<!-- some image with alt text -->
![some alt text:left](someOtherImageUrl)
To add a class image to the left, append ::<classname>
to its alt text. You can also add multiple classes to an image separated by space. ::<classname1> <classname2>
.
<!-- some image without alt text -->
![::img-medium](someImageUrl)
<!-- some image with alt text -->
![some alt text::img-large img-shadow](someOtherImageUrl)
Blog articles can specify a thumbnail image which will be displayed to the left of the card on the home page. Thumbnails should be square (height:width ratio of 1:1
). They will be specified using a frontmatter variable as follows:
...
thumbnail: "images/2020-04/capv-overview/thumbnail.jpg"
...
The thumbnail image will take precedence on opengraph share tags if the shareImage parameter is not specified.
Each article can specify an image that appears at the top of the content. When sharing the blog article on social media, if a thumnail is not specified, the featured image will be used as a fallback on opengraph share tags.
...
featureImage: "images/2020-04/capv-overview/featured.jpg"
...
Sometimes, you want to explicitly set the image that will be used in the preview when you share an article on social media. You can do so in the front matter.
...
shareImage = "images/theImageToBeUsedOnShare.png"
...
Note that if a share image is not specified, the order of precedence that will be used to determine which image applies is thumbnail
=> featureImage
=> fallbackOgImage
. When sharing a link to the home page address of the site (as opposed to a specific article), the fallbackOgImage
will be used.
You can left align or center your site's logo.
...
centerLogo = true # Change to false to align left
...
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.
...
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.
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.
To minimize http requests per page, we would recommend loading css styles and javasript helpers in single bundles. That's 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 this custom sass file and custom javascript file.
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 static
directory.
[params]
...
customCSS = ["css/custom.css"] # Include custom CSS files
customJS = ["js/custom.js"] # Include custom JS files
...
Pro Tip: You can change the theme colors via the this variables' sass file