cupper-hugo-theme/README.md

142 lines
5.3 KiB
Markdown
Raw Normal View History

2019-02-04 21:55:40 +01:00
# Cupper
2019-02-13 03:22:28 +01:00
[![Netlify Status](https://api.netlify.com/api/v1/badges/bc8c4e51-37ee-419d-ad4f-b378010ee546/deploy-status)](https://app.netlify.com/sites/cupper-hugo-theme/deploys)
2019-02-13 06:13:39 +01:00
An accessibility-friendly Hugo theme, ported from the [original Cupper](https://github.com/ThePacielloGroup/cupper) project.
2019-02-01 01:19:20 +01:00
## Table of contents
2017-11-02 16:37:06 +01:00
2021-10-18 04:54:41 +02:00
<!-- toc -->
2019-02-13 16:41:11 +01:00
- [Demo](#demo)
2019-02-15 16:30:06 +01:00
- [Minimum Hugo version](#minimum-hugo-version)
2019-02-13 16:41:11 +01:00
- [Installation](#installation)
- [Updating](#updating)
- [Run example site](#run-example-site)
- [Configuration](#configuration)
2021-10-18 04:54:41 +02:00
- [Nav Title or Logo](#nav-title-or-logo)
2019-02-14 16:02:30 +01:00
- [Favicons](#favicons)
2019-02-13 16:41:11 +01:00
- [Shortcodes](#shortcodes)
2019-02-15 18:30:40 +01:00
- [Syntax highlighting](#syntax-highlighting)
2021-09-12 21:24:53 +02:00
- [Enable Table of Contents for a Blog Post](#enable-table-of-contents-for-a-blog-post)
- [Localization](#localization)
2020-11-17 03:32:11 +01:00
- [Custom CSS and JS](#custom-css-and-js)
- [Default to Dark Theme](#default-to-dark-theme)
2021-08-20 19:42:50 +02:00
- [Non-Git Repo](#non-git-repo)
2019-02-18 18:58:48 +01:00
- [Getting help](#getting-help)
2019-02-13 16:41:11 +01:00
- [Credits](#credits)
2019-02-01 01:19:20 +01:00
2021-10-18 04:54:41 +02:00
<!-- tocstop -->
2019-02-01 01:19:20 +01:00
## Demo
2019-02-13 06:13:39 +01:00
https://cupper-hugo-theme.netlify.com/
2019-02-01 01:19:20 +01:00
2019-02-15 16:30:06 +01:00
## Minimum Hugo version
2021-05-25 20:51:55 +02:00
Hugo version `0.81.0` or higher is required. View the [Hugo releases](https://github.com/gohugoio/hugo/releases) and download the binary for your OS.
2019-02-15 16:30:06 +01:00
2019-02-01 01:19:20 +01:00
## Installation
From the root of your site:
```
2019-02-01 01:38:14 +01:00
git submodule add https://github.com/zwbetz-gh/cupper-hugo-theme.git themes/cupper-hugo-theme
2019-02-01 01:19:20 +01:00
```
## Updating
From the root of your site:
```
git submodule update --remote --merge
```
## Run example site
2019-02-01 01:38:14 +01:00
From the root of `themes/cupper-hugo-theme/exampleSite`:
2019-02-01 01:19:20 +01:00
```
hugo server --themesDir ../..
```
## Configuration
2021-10-18 04:54:41 +02:00
Copy `config.yaml` from the [`exampleSite`](https://github.com/zwbetz-gh/cupper-hugo-theme/tree/master/exampleSite), then edit as desired.
2019-02-01 01:19:20 +01:00
2021-10-18 04:54:41 +02:00
## Nav Title or Logo
2019-02-13 19:53:34 +01:00
2021-10-18 04:54:41 +02:00
- 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
2019-02-13 20:05:10 +01:00
2019-02-14 16:02:30 +01:00
## Favicons
2019-02-13 20:05:10 +01:00
2021-10-18 04:54:41 +02:00
Upload your image to [RealFaviconGenerator](https://realfavicongenerator.net/) then copy-paste the generated favicon files under `static`.
2019-02-13 20:05:10 +01:00
2019-02-15 18:30:40 +01:00
## Shortcodes
See the [full list of supported shortcodes](https://cupper-hugo-theme.netlify.com/cupper-shortcodes/).
2019-02-13 21:50:51 +01:00
## Syntax highlighting
2019-02-14 18:27:35 +01:00
Syntax highlighting is provided by [Prism](https://prismjs.com/). See this [markdown code fences example](https://cupper-hugo-theme.netlify.com/cupper-shortcodes/#syntax-highlighting).
2019-02-13 21:50:51 +01:00
By default, only a few languages are supported. If you want to add more, follow these steps:
1. Select the languages you want from <https://prismjs.com/download.html>
1. Download the JS file, then copy it to `static/js/prism.js`
1. Download the CSS file, then copy it to `static/css/prism.css`
2019-02-01 01:19:20 +01:00
2021-09-12 21:24:53 +02:00
## Enable Table of Contents for a Blog Post
2019-02-01 01:38:14 +01:00
2021-09-12 21:24:53 +02:00
Set `toc` to `true`. For example:
2019-02-14 16:02:30 +01:00
```
---
title: "My page with a few headings"
2021-09-12 21:24:53 +02:00
toc: true
2019-02-14 16:02:30 +01:00
---
```
2019-02-01 01:38:14 +01:00
## Localization
2020-06-02 03:49:59 +02:00
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.](https://regisphilibert.com/blog/2018/08/hugo-multilingual-part-2-i18n-string-localization/)
2020-11-17 03:32:11 +01:00
## Custom CSS and JS
2020-11-17 03:32:11 +01:00
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`.
2020-11-17 03:32:11 +01:00
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](https://github.com/zwbetz-gh/cupper-hugo-theme/blob/master/exampleSite/config.yaml) for sample usage.
## Default to Dark Theme
In the site config file set the param `defaultDarkTheme` to true.
E.g. for `config.yaml`
```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.
2021-08-20 19:42:50 +02:00
## Non-Git Repo
If your site is **not** a git repo, then set `enableGitInfo` to `false` in your config file.
2019-02-18 18:58:48 +01:00
## Getting help
2020-04-23 17:07:45 +02:00
If you run into an issue that isn't answered by this documentation or the [`exampleSite`](https://github.com/zwbetz-gh/cupper-hugo-theme/tree/master/exampleSite), then visit the [Hugo forum](https://discourse.gohugo.io/). The folks there are helpful and friendly. **Before** asking your question, be sure to read the [requesting help guidelines](https://discourse.gohugo.io/t/requesting-help/9132).
2019-02-18 18:58:48 +01:00
2019-02-01 01:19:20 +01:00
## Credits
2021-10-18 04:54:41 +02:00
Thank you to [Heydon Pickering](http://www.heydonworks.com) and [The Paciello Group](https://www.paciellogroup.com/) for creating the original Cupper project.