cupper-hugo-theme/README.md

108 lines
3.7 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
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)
2019-02-14 16:02:30 +01:00
- [Logo](#logo)
- [Favicons](#favicons)
2019-02-13 16:41:11 +01:00
- [Shortcodes](#shortcodes)
2019-02-15 18:30:40 +01:00
- [Syntax highlighting](#syntax-highlighting)
2019-02-14 16:02:30 +01:00
- [Disable toc for a blog post](#disable-toc-for-a-blog-post)
- [Localization](#localization)
- [Custom css](#custom-css)
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
## 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
2019-12-11 04:06:02 +01:00
Hugo version `0.60.1` 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
2019-12-11 04:06:02 +01: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
2019-02-14 16:02:30 +01:00
## Logo
2019-02-13 19:53:34 +01:00
2019-02-23 20:59:08 +01:00
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
2019-02-14 16:02:30 +01: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
2019-02-01 01:19:20 +01:00
2019-02-14 16:02:30 +01:00
## Disable toc for a blog post
2019-02-01 01:38:14 +01:00
2019-02-14 16:02:30 +01:00
Blog posts that have two or more subheadings (`<h2>`s) automatically get a table of contents. To disable this set `toc` to `false`. For example:
```
---
title: "My page with a few headings"
toc: false
---
```
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/)
## Custom css
2020-06-01 20:50:55 +02:00
Instead of copying the theme's css file to your own installation and modifying this large file, you can provide a list of css files that will be loaded after the theme's one. This enables you to override individual style while getting theme updates when they come.
2020-06-02 03:49:59 +02:00
Please see the params section of the example site `config.yaml` for more details.
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
2019-02-14 04:18:32 +01:00
Thank you to [Heydon Pickering](http://www.heydonworks.com) and [The Paciello Group](https://www.paciellogroup.com/) for creating the original Cupper project.