.. | ||
archetypes | ||
assets | ||
data | ||
i18n | ||
images | ||
layouts | ||
static | ||
.gitignore | ||
LICENSE | ||
netlify.toml | ||
README.md | ||
theme.toml |
⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️
WARNING: This repo is no longer maintained. It's archived and read-only.
⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️
Cupper
An accessibility-friendly Hugo theme, ported from the original Cupper project.
Table of contents
- Demo
- Minimum Hugo version
- Installation
- Updating
- Run example site
- Configuration
- Nav Title or Logo
- Favicons
- Shortcodes
- Syntax highlighting
- Enable Table of Contents for a Blog Post
- Localization
- Custom CSS and JS
- Default to Dark Theme
- Enable utterances
- Non-Git Repo
- Getting help
- Credits
Demo
https://cupper-hugo-theme.netlify.app/
Minimum Hugo version
Hugo version 0.81.0
or higher is required. View the Hugo releases and download the binary for your OS.
Installation
From the root of your site:
git submodule add https://github.com/zwbetz-gh/cupper-hugo-theme.git themes/cupper-hugo-theme
Updating
From the root of your site:
git submodule update --remote --merge
Run example site
From the root of themes/cupper-hugo-theme/exampleSite
:
hugo server --themesDir ../..
Configuration
Copy config.yaml
from the exampleSite
, then edit as desired.
Nav Title or Logo
- The
navTitleText
param will be checked in your config file. If this param exists, the text value will be used as the nav title - Otherwise, a logo will be used as the nav title. Place your SVG logo at
static/images/logo.svg
. If you don't provide a logo, then the default theme logo will be used
Favicons
Upload your image to RealFaviconGenerator then copy-paste the generated favicon files under static
.
Shortcodes
See the full list of supported shortcodes.
Syntax highlighting
Syntax highlighting is provided by Prism. See this markdown code fences example.
By default, only a few languages are supported. If you want to add more, follow these steps:
- Select the languages you want from https://prismjs.com/download.html
- Download the JS file, then copy it to
static/js/prism.js
- Download the CSS file, then copy it to
static/css/prism.css
Enable Table of Contents for a Blog Post
Set toc
to true
. For example:
---
title: "My page with a few headings"
toc: true
---
Localization
The strings in the templates of this theme can be localized. Make a copy of <THEME_BASE_FOLDER>/i18n/en.yaml
to <YOUR_SITE_FOLDER>/i18n/<YOUR_SITE_LANGUAGE>.yaml
, and translate one by one, changing the translation
field.
Here is a tutorial that goes more in depth about this.
Custom CSS and JS
You can provide an optional list of custom CSS files, which must be placed inside the static
dir. These will load after the theme CSS loads. So, static/css/custom_01.css
translates to css/custom_01.css
.
You can provide an optional list of custom JS files, which must be placed inside the static
dir. These will load after the theme JS loads. So, static/js/custom_01.js
translates to js/custom_01.js
.
See the example site config file for sample usage.
Default to Dark Theme
In the site config file set the param defaultDarkTheme
to true.
E.g. for config.yaml
params:
defaultDarkTheme: true
Note that the default of light or dark theme only applies to the first visit to a site using this theme. Once the site is visited the choice of dark or light theme is stored in 'local storage' in the browser.
To reset to a 'first visit' scenario (e.g. for testing), one needs to either browse in private mode (aka Incognito/InPrivate/etc) or delete 'local storage' for this site. The easiest way to do that, but which affects other sites as well, is to use the 'Clear History' feature of the browser.
Check your browser's help or documentation for details.
Enable utterances
utterances
is a lightweight comments widget built on GitHub issues.
Firstly, choose the repository utterances will connect to:
- Make sure the repo is public, otherwise your readers will not be able to view the issues/comments.
- Make sure the utterances app is installed on the repo, otherwise users will not be able to post comments.
- If your repo is a fork, navigate to its settings tab and confirm the issues feature is turned on.
Secondly,In the site config file set the param utterances.repo
to enable it.
E.g. for config.yaml
params:
utterances:
repo: username/username.github.io
issueTerm: title
theme: github-light
Refer to utterances for more information!
Non-Git Repo
If your site is not a git repo, then set enableGitInfo
to false
in your config file.
Getting help
If you run into an issue that isn't answered by this documentation or the exampleSite
, then visit the Hugo forum. The folks there are helpful and friendly. Before asking your question, be sure to read the requesting help guidelines.
Credits
Thank you to Heydon Pickering and The Paciello Group for creating the original Cupper project.