406 lines
13 KiB
Markdown
406 lines
13 KiB
Markdown
|
---
|
||
|
|
title: Customization
|
||
|
|
description: Describes common Mainroad theme configuration parameters that can be adjusted via config file or via Front
|
||
|
|
Matter section.
|
||
|
|
lead: Describes common Mainroad theme configuration parameters that can be adjusted via config file or via Front Matter
|
||
|
|
section.
|
||
|
|
date: 2022-01-24T14:00:00.000Z
|
||
|
|
thumbnail:
|
||
|
|
src: "img/placeholder.png"
|
||
|
|
visibility:
|
||
|
|
- list
|
||
|
|
authorbox: false
|
||
|
|
sidebar: false
|
||
|
|
pager: false
|
||
|
|
weight: 2
|
||
|
|
menu: main
|
||
|
|
---
|
||
|
|
|
||
|
|
Customization page describes common Mainroad configuration parameters which can be specified via configuration file or
|
||
|
|
via Front Matter section. That includes logo section tuning, adding a sidebar with widgets, adjusting highlight color,
|
||
|
|
and more.
|
||
|
|
|
||
|
|
<!--more-->
|
||
|
|
|
||
|
|
This section will mainly cover customization settings that are unique to this theme. If something is not covered here,
|
||
|
|
there's a good chance it is covered somewhere in [Hugo docs](https://gohugo.io/documentation/).
|
||
|
|
|
||
|
|
### Logo
|
||
|
|
|
||
|
|
**Mainroad** allows you to set a custom logo in the site header. You may use text, or image, or both. Use the following
|
||
|
|
options in your site config:
|
||
|
|
|
||
|
|
```toml
|
||
|
|
[Params.logo]
|
||
|
|
image = "img/placeholder.png"
|
||
|
|
title = "Mainroad"
|
||
|
|
subtitle = "Just another site"
|
||
|
|
```
|
||
|
|
|
||
|
|
**Note:** logo image will display at a maximum width of 128 pixels and a maximum height of 128 pixels
|
||
|
|
when you use text and image simultaneously. When the only logo image is active, it will display at a maximum height of
|
||
|
|
256 pixels. Ideally, your logo image should be SVG.
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
If you don't set any of these variables, the theme uses the site title as a logo title. Don't need a logo section?
|
||
|
|
Disable it this way:
|
||
|
|
|
||
|
|
```toml
|
||
|
|
[Params.logo]
|
||
|
|
image = false
|
||
|
|
title = false
|
||
|
|
subtitle = false
|
||
|
|
```
|
||
|
|
|
||
|
|
### Highlight color
|
||
|
|
|
||
|
|
Mainroad uses `#e22d30` as a default highlight color, but you may choose and set any other color.
|
||
|
|
|
||
|
|
```toml
|
||
|
|
[Params.style.vars]
|
||
|
|
highlightColor = "#e22d30"
|
||
|
|
```
|
||
|
|
|
||
|
|
### Post meta
|
||
|
|
|
||
|
|
Post meta is a feature that refers to including additional meta information (such as author name, categories, date,
|
||
|
|
translations, etc.) on pages. It can be enabled via config using the `post_meta` key with a list of meta field names as
|
||
|
|
value. Order matters here: rearrange fields if you want to.
|
||
|
|
|
||
|
|
```toml
|
||
|
|
[Params]
|
||
|
|
post_meta = ["author", "date", "categories", "translations"]
|
||
|
|
```
|
||
|
|
|
||
|
|
Full list of available default post meta fields:
|
||
|
|
|
||
|
|
* `author`, `categories`, `date`, `translations`
|
||
|
|
|
||
|
|
In addition to the default meta fields, you can add your own by placing a custom partial under
|
||
|
|
`layouts/partials/post_meta/<name>.html`.
|
||
|
|
|
||
|
|
#### Post meta: `date` localization
|
||
|
|
|
||
|
|
With [Hugo v0.87.0](https://gohugo.io/news/0.87.0-relnotes/) (or later), `date` meta field shows localized dates (with
|
||
|
|
weekdays and months in the current language) by default. In most cases, such a transition is painless, but owners of
|
||
|
|
multilingual sites should be careful and check that everything translates as expected after the upgrade.
|
||
|
|
|
||
|
|
You can also use a predefined layout, like `:date_full`, and it will output localized dates or times. For additional
|
||
|
|
information about localized dates and possible date/time formatting layouts, please see
|
||
|
|
[Hugo: time.Format](https://gohugo.io/functions/dateformat/).
|
||
|
|
|
||
|
|
### Thumbnail visibility
|
||
|
|
|
||
|
|
By default, a thumbnail image has shown for a list and single pages simultaneously. In some cases, you may want to show
|
||
|
|
a thumbnail for list-like pages only and hide it on single pages (or vice versa). Control global thumbnail visibility
|
||
|
|
via config, use the key `visibility` with combination of valid values `"list"` and `"post"`.
|
||
|
|
|
||
|
|
```toml
|
||
|
|
[Params.thumbnail]
|
||
|
|
# Show thumbnail only for list items
|
||
|
|
visibility = ["list"]
|
||
|
|
```
|
||
|
|
|
||
|
|
Besides global configuration, you can change thumbnail visibility individually with extended thumbnail notation via
|
||
|
|
front matter block.
|
||
|
|
|
||
|
|
```yaml
|
||
|
|
thumbnail:
|
||
|
|
src: "img/placeholder.png"
|
||
|
|
visibility:
|
||
|
|
- list
|
||
|
|
- post
|
||
|
|
```
|
||
|
|
|
||
|
|
This page is an example of list-only thumbnail visibility.
|
||
|
|
|
||
|
|
### Sidebar
|
||
|
|
|
||
|
|
**Mainroad** comes with a configurable sidebar that can be on the left, on the right, or disabled. The default layout
|
||
|
|
can be specified in the `[Params.sidebar]` section of the configuration. The position can be specified for home, list
|
||
|
|
and single pages individually. Use the keys `home`, `list` and `single` with values `"left"`, `"right"` or `false`.
|
||
|
|
|
||
|
|
```toml
|
||
|
|
[Params.sidebar]
|
||
|
|
home = "right"
|
||
|
|
list = "right"
|
||
|
|
single = "right"
|
||
|
|
```
|
||
|
|
|
||
|
|
The layout can be configured per page, by setting the `sidebar` parameter with one of the same values (`"left"`,
|
||
|
|
`"right"` or `false`) in the page's front matter.
|
||
|
|
|
||
|
|
```yaml
|
||
|
|
sidebar: "left" # Enable sidebar (on the left side) per page
|
||
|
|
```
|
||
|
|
|
||
|
|
The sidebar consists of multiple widgets. Widgets can be enabled individually using the `widgets` key with a list of
|
||
|
|
widget names as value. You can add your own widgets, by placing a template under `layouts/partials/widgets/<name>.html`.
|
||
|
|
|
||
|
|
```toml
|
||
|
|
[Params.sidebar]
|
||
|
|
# Enable widgets in given order
|
||
|
|
widgets = ["search", "recent", "categories", "taglist", "social", "languages"]
|
||
|
|
```
|
||
|
|
|
||
|
|
The list of widgets can be overwritten from a page's front matter.
|
||
|
|
|
||
|
|
```yaml
|
||
|
|
# Enable sidebar widgets in given order
|
||
|
|
widgets:
|
||
|
|
- "search"
|
||
|
|
- "recent"
|
||
|
|
- "taglist"
|
||
|
|
```
|
||
|
|
|
||
|
|
Full list of available default widgets:
|
||
|
|
|
||
|
|
* `search`, `ddg-search`, `recent`, `categories`, `taglist`, `social`, `languages`
|
||
|
|
|
||
|
|
**Note**: DuckDuckGo widget (`ddg-search`) deprecated in favor of `search` widget.
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
Some of our widgets respect optional configuration. Have a look at the `[Params.widgets]` and `[Params.widgets.social]`
|
||
|
|
sections in the example below.
|
||
|
|
|
||
|
|
```toml
|
||
|
|
[Params.widgets]
|
||
|
|
recent_num = 5 # Set the number of articles in the "Recent articles" widget
|
||
|
|
categories_counter = false # Enable counter for each category in "Categories" widget
|
||
|
|
tags_counter = false # Enable counter for each tag in "Tags" widget
|
||
|
|
```
|
||
|
|
|
||
|
|
```toml
|
||
|
|
[Params.widgets.social]
|
||
|
|
# Enable parts of social widget
|
||
|
|
facebook = "username"
|
||
|
|
twitter = "username"
|
||
|
|
instagram = "username"
|
||
|
|
linkedin = "username"
|
||
|
|
telegram = "username"
|
||
|
|
github = "username"
|
||
|
|
gitlab = "username"
|
||
|
|
bitbucket = "username"
|
||
|
|
email = "example@example.com"
|
||
|
|
```
|
||
|
|
|
||
|
|
### Widget caching
|
||
|
|
|
||
|
|
Sidebar strongly affects overall build time, especially if you are using all of our widgets or even more. Widget caching
|
||
|
|
can significantly improve the generation time. Cached partials remain the same for all affected pages and are not
|
||
|
|
generated multiple times by Hugo. All built-in widgets (`search`, `recent`, `categories`, `taglist`, `social`,
|
||
|
|
`languages`) support caching.
|
||
|
|
|
||
|
|
Add `cached = true` inside the corresponding widget's dictionary table to activate caching. For example, to cache the
|
||
|
|
`recent` widget:
|
||
|
|
|
||
|
|
```toml
|
||
|
|
[Params.widgets.recent]
|
||
|
|
cached = true
|
||
|
|
```
|
||
|
|
|
||
|
|
The following sample configuration extract shows how to cache all standard widgets and generate your website faster:
|
||
|
|
|
||
|
|
```toml
|
||
|
|
[Params.widgets.search]
|
||
|
|
cached = true
|
||
|
|
|
||
|
|
[Params.widgets.recent]
|
||
|
|
cached = true
|
||
|
|
|
||
|
|
[Params.widgets.categories]
|
||
|
|
cached = true
|
||
|
|
|
||
|
|
[Params.widgets.taglist]
|
||
|
|
cached = true
|
||
|
|
|
||
|
|
[Params.widgets.social]
|
||
|
|
cached = true
|
||
|
|
|
||
|
|
[Params.widgets.languages]
|
||
|
|
cached = true
|
||
|
|
```
|
||
|
|
|
||
|
|
Not all widgets are cacheable. If a widget contains (can contain) different data for different pages (e.g., for TOC
|
||
|
|
generation), then it should not be cached. Always check that your modified/customized widget is cached correctly.
|
||
|
|
|
||
|
|
### Social Widget: custom links
|
||
|
|
|
||
|
|
**Mainroad** contains built-in social links in the social widget. In addition to default social links, you may set
|
||
|
|
custom links by adding `Params.widgets.social.custom` to your `config.toml`. Here is an example:
|
||
|
|
|
||
|
|
```toml
|
||
|
|
[[Params.widgets.social.custom]]
|
||
|
|
title = "My Home Page"
|
||
|
|
url = "https://example.com"
|
||
|
|
```
|
||
|
|
|
||
|
|
If you want to display an icon of your social link, you need to put SVG icon file in `layouts/partials` directory under
|
||
|
|
your site's root. The `icon` key filed, which is optional, should be a path relative to `layouts/partials`.
|
||
|
|
|
||
|
|
```toml
|
||
|
|
[[Params.widgets.social.custom]]
|
||
|
|
title = "Youtube"
|
||
|
|
url = "https://youtube.com/user/username"
|
||
|
|
icon = "youtube.svg"
|
||
|
|
```
|
||
|
|
|
||
|
|
**Note:** *Only* SVG files are supported to be used as custom social icons. If you use any other files, PNG for example,
|
||
|
|
a compile error will be raised by Hugo. Moreover, not every SVG icon can be used. For better results, it should be
|
||
|
|
one-color SVG file with a special class attribute `{{ with .class }}{{ . }} {{ end }}` and 24x24 size. At a minimum,
|
||
|
|
custom SVG icon needs these attributes:
|
||
|
|
|
||
|
|
```html
|
||
|
|
<svg class="{{ with .class }}{{ . }} {{ end }} icon" width="24" height="24">...</svg>
|
||
|
|
```
|
||
|
|
|
||
|
|
You can also specify the `rel` attribute for the link. By default, the attribute value is `"noopener noreferrer"`. You can remove the attribute completely by setting its value to `false`.
|
||
|
|
|
||
|
|
```toml
|
||
|
|
[[Params.widgets.social.custom]]
|
||
|
|
title = "My Home Page"
|
||
|
|
url = "https://example.com"
|
||
|
|
rel = "me"
|
||
|
|
|
||
|
|
[[Params.widgets.social.custom]]
|
||
|
|
title = "Youtube"
|
||
|
|
url = "https://youtube.com/user/username"
|
||
|
|
rel = false
|
||
|
|
```
|
||
|
|
|
||
|
|
### Search box widget
|
||
|
|
|
||
|
|
The search box widget can refer to the results of Google, Bing, and DuckDuckGo searches. By default, Mainroad uses
|
||
|
|
Google search if no additional configuration options are specified.
|
||
|
|
|
||
|
|
To use a different search engine, first of all, check that the search widget is enabled. Then set the search parameters
|
||
|
|
(`Site.Params.widgets.search` section) according to the data below.
|
||
|
|
|
||
|
|
**Google (default)**:
|
||
|
|
|
||
|
|
```toml
|
||
|
|
[Params.widgets.search]
|
||
|
|
url = "https://google.com/search"
|
||
|
|
[Params.widgets.search.input]
|
||
|
|
name = "sitesearch"
|
||
|
|
pre = ""
|
||
|
|
```
|
||
|
|
|
||
|
|
**DuckDuckGo**:
|
||
|
|
|
||
|
|
```toml
|
||
|
|
[Params.widgets.search]
|
||
|
|
url = "https://duckduckgo.com/"
|
||
|
|
[Params.widgets.search.input]
|
||
|
|
name = "sites"
|
||
|
|
pre = ""
|
||
|
|
```
|
||
|
|
|
||
|
|
**Bing**:
|
||
|
|
|
||
|
|
```toml
|
||
|
|
[Params.widgets.search]
|
||
|
|
url = "https://www.bing.com/search"
|
||
|
|
[Params.widgets.search.input]
|
||
|
|
name = "q1"
|
||
|
|
pre = "site:"
|
||
|
|
```
|
||
|
|
|
||
|
|
**Google PSE**:
|
||
|
|
|
||
|
|
```toml
|
||
|
|
[Params.widgets.search]
|
||
|
|
url = "/search/"
|
||
|
|
[Params.widgets.search.input]
|
||
|
|
name = false
|
||
|
|
pre = ""
|
||
|
|
```
|
||
|
|
|
||
|
|
Note that Google PSE requires additional steps to work correctly.
|
||
|
|
See [Creating a Programmable Search Engine](https://developers.google.com/custom-search/docs/tutorial/creatingcse) and
|
||
|
|
especially our [FAQ]({{< relref "/docs/faq.md" >}} "Mainroad FAQ") for more instructions.
|
||
|
|
|
||
|
|
### Menus
|
||
|
|
|
||
|
|
**Mainroad** supports multiple menus. The `main` menu is fully responsive and displayed right under the site header. The
|
||
|
|
secondary menus `side` and `footer` are displayed in a sidebar widget and the page footer respectively. To add a page to
|
||
|
|
a menu, add a `menu: <menu>` parameter to the page's front matter:
|
||
|
|
|
||
|
|
```yaml
|
||
|
|
menu: main # Add page to a main menu
|
||
|
|
```
|
||
|
|
|
||
|
|
**Note:** Don't forget to enable the `sidemenu` widget in the `widgets` configuration param if you want to use the
|
||
|
|
`side` menu.
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
You can also add a page to multiple menus by providing a list:
|
||
|
|
|
||
|
|
```yaml
|
||
|
|
# Add page to a main, side, and footer menu
|
||
|
|
menu:
|
||
|
|
- main
|
||
|
|
- side
|
||
|
|
- footer
|
||
|
|
```
|
||
|
|
|
||
|
|
**Note:** Please keep in mind that Mainroad menus don't support nested items i.e. submenus.
|
||
|
|
|
||
|
|
See [Menus](https://gohugo.io/content-management/menus/#readout) from official Hugo documentation for more info.
|
||
|
|
|
||
|
|
### Custom Google Fonts support
|
||
|
|
|
||
|
|
Mainroad uses Open Sans from Google Fonts as a main font. But you can use any other font from Google Fonts if you'd
|
||
|
|
like. Beware, in most cases, such changes require manual CSS adjustment because every set of fonts is different and
|
||
|
|
might not look as good as our default font.
|
||
|
|
|
||
|
|
Follow the procedure below.
|
||
|
|
|
||
|
|
1. Open Google Fonts, choose font(s) that you prefer and copy href font link. For this particular example, we choose
|
||
|
|
[Roboto with 3 different styles](https://fonts.google.com/share?selection.family=Roboto:ital,wght@0,400;0,700;1,400;1,700).
|
||
|
|
Our href font link:
|
||
|
|
|
||
|
|
```
|
||
|
|
https://fonts.googleapis.com/css2?family=Roboto:ital,wght@0,400;0,700;1,400&display=swap
|
||
|
|
```
|
||
|
|
|
||
|
|
1. Set `googleFontsLink` site's config param value to your href font link. For example:
|
||
|
|
|
||
|
|
```toml
|
||
|
|
[Params]
|
||
|
|
googleFontsLink = "https://fonts.googleapis.com/css2?family=Roboto:ital,wght@0,400;0,700;1,400&display=swap"
|
||
|
|
```
|
||
|
|
|
||
|
|
1. Override default font-family set(s):
|
||
|
|
|
||
|
|
```toml
|
||
|
|
[Params.style.vars]
|
||
|
|
fontFamilyPrimary = "'Roboto', sans-serif"
|
||
|
|
```
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
It is possible to disable Google Fonts and use system font stack instead.
|
||
|
|
|
||
|
|
1. Disable Google Fonts include. Set `googleFontsLink` site's config param value to `false`:
|
||
|
|
|
||
|
|
```toml
|
||
|
|
[Params]
|
||
|
|
googleFontsLink = false
|
||
|
|
```
|
||
|
|
|
||
|
|
1. Override font-family sets:
|
||
|
|
|
||
|
|
```toml
|
||
|
|
[Params.style.vars]
|
||
|
|
# Override font-family sets. Take care of different quotes OR escaping symbols in these params if necessary
|
||
|
|
fontFamilyPrimary = "system-ui, -apple-system, 'Segoe UI', Roboto, 'Helvetica Neue', Arial, 'Noto Sans', 'Liberation Sans', sans-serif, 'Apple Color Emoji', 'Segoe UI Emoji', 'Segoe UI Symbol', 'Noto Color Emoji'"
|
||
|
|
# Secondary font-family set responsible for pre, code, kbd, and samp tags font
|
||
|
|
fontFamilySecondary = "SFMono-Regular, Menlo, Monaco, Consolas, 'Liberation Mono', 'Courier New', monospace"
|
||
|
|
```
|
||
|
|
|
||
|
|
[Edit this page on GitHub](https://github.com/vimux/mainroad/blob/master/exampleSite/content/docs/customization.md)
|