hugo-theme-relearn/exampleSite/content/basics/customization/_index.en.md

116 lines
6.4 KiB
Markdown
Raw Normal View History

+++
categories = ["custom", "theming"]
title = "Customization"
weight = 25
+++
2017-09-04 17:14:13 +00:00
The Relearn theme has been built to be as configurable as possible by defining multiple [partials](https://gohugo.io/templates/partials/)
2017-09-04 17:14:13 +00:00
In `themes/hugo-theme-relearn/layouts/partials/`, you will find all the partials defined for this theme. If you need to overwrite something, don't change the code directly. Instead [follow this page](https://gohugo.io/themes/customizing/). You'd create a new partial in the `layouts/partials` folder of your local project. This partial will have the priority.
2017-09-04 17:14:13 +00:00
This theme defines the following partials :
- `header.html`: the header of the page. See [output-formats](#output-formats)
- `footer.html`: the footer of the page. See [output-formats](#output-formats)
- `body.html`: the body of the page. The body may contain of one or many articles. See [output-formats](#output-formats)
- `article.html`: the output for a single article, can contain elements around your content. See [output-formats](#output-formats)
- `menu.html`: left menu. _Not meant to be overwritten_
- `search.html`: search box. _Not meant to be overwritten_
- `custom-header.html`: custom headers in page. Meant to be overwritten when adding CSS imports. Don't forget to include `style` HTML tag directive in your file.
2022-10-31 11:10:36 +00:00
- `custom-footer.html`: custom footer in page. Meant to be overwritten when adding JavaScript. Don't forget to include `javascript` HTML tag directive in your file.
2022-02-14 20:44:01 +00:00
- `favicon.html`: the favicon
2022-10-31 11:10:36 +00:00
- `heading-pre.html`: side-wide configuration to prepend to pages title headings. If you override this, it is your responsibility to take the page's `headingPre` setting into account.
- `heading-post.html`: side-wide configuration to append to pages title headings. If you override this, it is your responsibility to take the page's `headingPost` setting into account.
2022-02-14 20:44:01 +00:00
- `logo.html`: the logo, on top left hand corner
- `meta.html`: HTML meta tags, if you want to change default behavior
2022-10-31 11:10:36 +00:00
- `menu-pre.html`: side-wide configuration to prepend to menu items. If you override this, it is your responsibility to take the page's `menuPre` setting into account.
- `menu-post.html`: side-wide configuration to append to menu items. If you override this, it is your responsibility to take the page's `menuPost` setting into account.
2022-02-14 20:44:01 +00:00
- `menu-footer.html`: footer of the the left menu
- `toc.html`: table of contents
2022-10-31 11:10:36 +00:00
- `content.html`: the content page itself. This can be overridden if you want to display page's meta data above or below the content.
- `content-header.html`: header above the title, has a default implementation but you can overwrite it if you don't like it.
- `content-footer.html`: footer below the content, has a default implementation but you can overwrite it if you don't like it.
2017-09-04 17:14:13 +00:00
## Change the logo
Create a new file in `layouts/partials/` named `logo.html`. Then write any HTML you want.
You could use an `img` HTML tag and reference an image created under the *static* folder, or you could paste a SVG definition!
2017-09-04 17:14:13 +00:00
{{% notice note %}}
The size of the logo will adapt automatically
{{% /notice %}}
## Change the favicon
2022-10-31 11:10:36 +00:00
If your favicon is a SVG, PNG or ICO, just drop off your image in your local `static/images/` folder and name it `favicon.svg`, `favicon.png` or `favicon.ico` respectively.
2021-10-30 20:00:46 +00:00
If no favicon file is found, the theme will lookup the alternative filename `logo` in the same location and will repeat the search for the list of supported file types.
2017-09-04 17:14:13 +00:00
If you need to change this default behavior, create a new file in `layouts/partials/` named `favicon.html`. Then write something like this:
```html
2022-10-02 22:24:37 +00:00
<link rel="icon" href="/images/favicon.bmp" type="image/bmp">
2017-09-04 17:14:13 +00:00
```
2022-02-21 23:04:16 +00:00
## Change the colors {#theme-variant}
2017-09-04 17:14:13 +00:00
2022-02-21 23:18:56 +00:00
The Relearn theme lets you choose between some predefined color variants in light or dark mode, but feel free to add one yourself!
2021-07-01 14:25:08 +00:00
2022-02-21 23:04:16 +00:00
You can preview the shipped variants by changing them in the variant selector at the bottom of the menu.
2021-07-01 14:25:08 +00:00
2022-02-21 23:04:16 +00:00
### Single variant
2017-09-04 17:14:13 +00:00
2022-02-21 23:04:16 +00:00
Set the `themeVariant` value with the name of your theme file. That's it!
2017-09-04 17:14:13 +00:00
```toml
[params]
2022-02-21 23:04:16 +00:00
themeVariant = "relearn-light"
2017-09-04 17:14:13 +00:00
```
2022-10-31 11:10:36 +00:00
In the above example your theme file has to be named `theme-relearn-light.css`
2022-02-13 00:53:23 +00:00
### Multiple variants
2022-10-31 11:10:36 +00:00
You can also set multiple variants. In this case, the first variant is the default chosen on first view and a variant switch will be shown in the menu footer.
2022-02-13 00:53:23 +00:00
```toml
[params]
2022-02-14 20:44:01 +00:00
# Change default color scheme with a variant one.
themeVariant = [ "relearn-light", "relearn-dark" ]
2022-02-13 00:53:23 +00:00
```
{{% notice tip %}}
2022-10-31 11:10:36 +00:00
If you want to switch the syntax highlighting theme together with your color variant, generate a syntax highlighting stylesheet and configure your installation [according to Hugo's documentation](https://gohugo.io/content-management/syntax-highlighting/), and `@import` this stylesheet in your color variant stylesheet. For an example, take a look into `theme-relearn-light.css` and `config.toml` of the exampleSite.
{{% /notice %}}
2022-02-21 23:04:16 +00:00
### Adjust to OS Settings
You can also cause the site to adjust to your OS settings for light/dark mode. Just set the `themeVariant` to `auto`. That's it.
If you've set multiple variants, you can drop `auto` at any position, but usually it makes sense to set it in the first position and make it the default.
```toml
[params]
themeVariant = [ "auto", "red" ]
```
If you don't configure anything else, the theme will use `relearn-light` for light mode and `relearn-dark` for dark mode.
If you don't like that, you can set `themeVariantAuto`. The first element is the variant for light mode, the second for dark mode
```toml
[params]
themeVariantAuto = [ "learn", "neon" ]
```
2023-02-04 22:38:09 +00:00
{{% notice note %}}
This is not supported for Internet Explorer 11, which still displays in the `relearn-light` variant.
{{% /notice %}}
2022-02-21 23:04:16 +00:00
### Roll your own
If you are not happy with the shipped variants you can either copy and rename one of the shipped files from `themes/hugo-theme-relearn/static/css` to `static/css`, edit them afterwards to your liking in a text editor and configure the `themeVariant` parameter in your `config.toml` or just use the [interactive variant generator]({{%relref "basics/generator" %}}).
### Output formats
Certain parts of the theme can be changed for support of your own [output formats](https://gohugo.io/templates/output-formats/). Eg. if you define a new output format `PLAINTEXT` in your `config.toml`, you can add a file `layouts/partials/header.plaintext.html` to change the way, the page header should look like for that output format.