mirror of
https://github.com/McShelby/hugo-theme-relearn.git
synced 2025-01-18 10:50:24 +00:00
docs: first draft chapter 2 #567
This commit is contained in:
Sören Weber
parent
1ee0b86b6b
commit
ba81589107
91 changed files with 1023 additions and 579 deletions
26
README.md
26
README.md
|
|
@ -16,31 +16,31 @@ The Relearn theme is an enhanced fork of the popular [Learn theme](https://githu
|
|||
- Responsive design for mobile devices
|
||||
- Looks nice on paper (if it has to)
|
||||
- Usable offline with no external dependencies
|
||||
- [Usable from your local file system without a web server via `file://` protocol](https://mcshelby.github.io/hugo-theme-relearn/configuration/customization#file-system)
|
||||
- [Usable from your local file system without a web server via `file://` protocol](https://mcshelby.github.io/hugo-theme-relearn/configuration/siteorganization/deploymentscenarios/)
|
||||
- Integration with the [VSCode Front Matter extension](https://github.com/estruyf/vscode-front-matter) for on-premise CMS capabilities
|
||||
|
||||
- **Customizable Appearance**
|
||||
- [Flexible brand image configuration](https://mcshelby.github.io/hugo-theme-relearn/configuration/branding#change-the-logo)
|
||||
- [Automatic light/dark mode switching based on OS settings](https://mcshelby.github.io/hugo-theme-relearn/configuration/branding#adjust-to-os-settings)
|
||||
- [Flexible brand image configuration](https://mcshelby.github.io/hugo-theme-relearn/configuration/appearance/branding#change-the-logo)
|
||||
- [Automatic light/dark mode switching based on OS settings](https://mcshelby.github.io/hugo-theme-relearn/configuration/appearance/branding#adjust-to-os-settings)
|
||||
- Pre-defined color schemes and variants
|
||||
- [User-selectable theme variants](https://mcshelby.github.io/hugo-theme-relearn/configuration/branding#multiple-variants)
|
||||
- [Built-in stylesheet generator](https://mcshelby.github.io/hugo-theme-relearn/configuration/generator)
|
||||
- [User-selectable theme variants](https://mcshelby.github.io/hugo-theme-relearn/configuration/appearance/branding#multiple-variants)
|
||||
- [Built-in stylesheet generator](https://mcshelby.github.io/hugo-theme-relearn/configuration/appearance/generator)
|
||||
- [Customizable syntax highlighting](https://mcshelby.github.io/hugo-theme-relearn/shortcodes/highlight)
|
||||
|
||||
- **Advanced Functionality**
|
||||
- [Chapter and site-wide printing capabilities](https://mcshelby.github.io/hugo-theme-relearn/configuration/customization#activate-print-support)
|
||||
- [Versatile search options: in-page, popup, and dedicated search page](https://mcshelby.github.io/hugo-theme-relearn/configuration/customization#configure-search)
|
||||
- [Customizable top bar buttons](https://mcshelby.github.io/hugo-theme-relearn/configuration/topbar)
|
||||
- [Chapter and site-wide printing capabilities](https://mcshelby.github.io/hugo-theme-relearn/configuration/appearance/topbar/#print-support)
|
||||
- [Versatile search options: in-page, popup, and dedicated search page](https://mcshelby.github.io/hugo-theme-relearn/configuration/sidebar/search/)
|
||||
- [Customizable top bar buttons](https://mcshelby.github.io/hugo-theme-relearn/configuration/modifications/topbar/)
|
||||
- [Unlimited nested menu structure](https://mcshelby.github.io/hugo-theme-relearn/content/organization)
|
||||
- [Configurable menu shortcuts](https://mcshelby.github.io/hugo-theme-relearn/configuration/menushortcuts)
|
||||
- [Configurable menu shortcuts](https://mcshelby.github.io/hugo-theme-relearn/configuration/sidebar/shortcutmenu/)
|
||||
- Support for hidden pages
|
||||
- [Comprehensive taxonomy support](https://mcshelby.github.io/hugo-theme-relearn/content/taxonomy)
|
||||
- [Social media integration](https://mcshelby.github.io/hugo-theme-relearn/configuration/customization#social-media-meta-tags)
|
||||
- [Social media integration](https://mcshelby.github.io/hugo-theme-relearn/configuration/content/image/)
|
||||
|
||||
- **Multilingual Support**
|
||||
- [Full right-to-left (RTL) language support](https://mcshelby.github.io/hugo-theme-relearn/configuration/i18n)
|
||||
- [Extensive list of supported languages](https://mcshelby.github.io/hugo-theme-relearn/configuration/i18n#basic-configuration): Arabic, Chinese (Simplified and Traditional), Czech, Dutch, English, Finnish, French, German, Hindi, Hungarian, Indonesian, Italian, Japanese, Korean, Polish, Portuguese, Romanian, Russian, Spanish, Swahili, Turkish, Vietnamese
|
||||
- [Multilingual content search capabilities](https://mcshelby.github.io/hugo-theme-relearn/configuration/i18n#search)
|
||||
- [Full right-to-left (RTL) language support](https://mcshelby.github.io/hugo-theme-relearn/configuration/siteorganization/multilingual/)
|
||||
- [Extensive list of supported languages](https://mcshelby.github.io/hugo-theme-relearn/configuration/siteorganization/multilingual): Arabic, Chinese (Simplified and Traditional), Czech, Dutch, English, Finnish, French, German, Hindi, Hungarian, Indonesian, Italian, Japanese, Korean, Polish, Portuguese, Romanian, Russian, Spanish, Swahili, Turkish, Vietnamese
|
||||
- [Multilingual content search capabilities](https://mcshelby.github.io/hugo-theme-relearn/configuration/sidebar/search/#search-with-mixed-language-support)
|
||||
|
||||
- **Enhanced Markdown Features**
|
||||
- [GitHub Flavored Markdown (GFM) support](https://mcshelby.github.io/hugo-theme-relearn/content/markdown)
|
||||
|
|
|
|||
|
|
@ -26,7 +26,7 @@ weight = -0
|
|||
|
||||
- {{% badge style="info" icon="plus-circle" title=" " %}}New{{% /badge %}} You can define the expansion state of your menus in the frontmatter. Please see further [documentation](content/frontmatter#override-expand-state-rules-for-menu-entries) for possible values and default behavior.
|
||||
|
||||
- {{% badge style="info" icon="plus-circle" title=" " %}}New{{% /badge %}} New partials for defining pre/post content for menu items and the content. See [documentation](configuration/customization#partials) for further reading.
|
||||
- {{% badge style="info" icon="plus-circle" title=" " %}}New{{% /badge %}} New partials for defining pre/post content for menu items and the content. See [documentation](configuration/modifications/partials/) for further reading.
|
||||
|
||||
- {{% badge style="info" icon="plus-circle" title=" " %}}New{{% /badge %}} Shortcode [`children`](shortcodes/children) with new parameter `containerstyle`.
|
||||
|
||||
|
|
|
|||
|
|
@ -10,4 +10,4 @@ weight = -6
|
|||
|
||||
### New
|
||||
|
||||
- {{% badge style="info" icon="plus-circle" title=" " %}}New{{% /badge %}} Your site can now be served from a subdirectory if you set `baseURL` in your `hugo.toml`. See the [documentation](configuration/customization#public-web-server-from-subdirectory) for a detailed example.
|
||||
- {{% badge style="info" icon="plus-circle" title=" " %}}New{{% /badge %}} Your site can now be served from a subdirectory if you set `baseURL` in your `hugo.toml`. See the [documentation](configuration/siteorganization/deploymentscenarios/) for a detailed example.
|
||||
|
|
|
|||
|
|
@ -14,6 +14,6 @@ weight = -8
|
|||
|
||||
### New
|
||||
|
||||
- {{% badge style="info" icon="plus-circle" title=" " %}}New{{% /badge %}} The theme now supports favicons served from `static/images/` named as `favicon` or `logo` in SVG, PNG or ICO format [out of the box](configuration/branding#change-the-favicon). An overridden partial `layouts/partials/favicon.html` may not be necessary anymore in most cases.
|
||||
- {{% badge style="info" icon="plus-circle" title=" " %}}New{{% /badge %}} The theme now supports favicons served from `static/images/` named as `favicon` or `logo` in SVG, PNG or ICO format [out of the box](configuration/appearance/branding#change-the-favicon). An overridden partial `layouts/partials/favicon.html` may not be necessary anymore in most cases.
|
||||
|
||||
- {{% badge style="info" icon="plus-circle" title=" " %}}New{{% /badge %}} You can hide the table of contents menu for the whole site by setting the `disableToc` option in your `hugo.toml`. For an example see [the example configuration](configuration/options).
|
||||
|
|
|
|||
|
|
@ -10,13 +10,13 @@ weight = -0
|
|||
|
||||
### Breaking
|
||||
|
||||
- {{% badge style="warning" title=" " %}}Breaking{{% /badge %}} We made changes to the menu footer. If you have your `menu-footer.html` [partial overridden](configuration/customization#partials), you may have to review the styling (eg. margins/paddings) in your partial. For a reference take a look into the `menu-footer.html` partial that is coming with the exampleSite.
|
||||
- {{% badge style="warning" title=" " %}}Breaking{{% /badge %}} We made changes to the menu footer. If you have your `menu-footer.html` [partial overridden](configuration/modifications/partials/), you may have to review the styling (eg. margins/paddings) in your partial. For a reference take a look into the `menu-footer.html` partial that is coming with the exampleSite.
|
||||
|
||||
This change was made to allow your own menu footer to be placed right after the so called prefooter that comes with the theme (containing the language switch and _Clear history_ functionality).
|
||||
|
||||
- {{% badge style="warning" title=" " %}}Breaking{{% /badge %}} We have changed the default colors from the original Learn theme (the purple menu header) to the Relearn defaults (the light green menu header) as used in the official documentation.
|
||||
|
||||
This change will only affect your installation if you've not set the `themeVariant` parameter in your `hugo.toml`. [If you still want to use the Learn color variant](configuration/branding#theme-variant), you have to explicitly set `themeVariant="learn"` in your `hugo.toml`.
|
||||
This change will only affect your installation if you've not set the `themeVariant` parameter in your `hugo.toml`. [If you still want to use the Learn color variant](configuration/appearance/branding#theme-variant), you have to explicitly set `themeVariant="learn"` in your `hugo.toml`.
|
||||
|
||||
Note, that this will also affect your site if viewed with Internet Explorer 11 but in this case it can not be reconfigured as Internet Explorer does not support CSS variables.
|
||||
|
||||
|
|
@ -30,12 +30,12 @@ weight = -0
|
|||
|
||||
- {{% badge style="info" icon="plus-circle" title=" " %}}New{{% /badge %}} With this release you are now capable to define your own _dark mode_ variants.
|
||||
|
||||
To make this possible, we have introduced a lot more color variables you can use in [your color variants](configuration/branding#theme-variant). Your old variants will still work and don't need to be changed as appropriate fallback values are used by the theme. Nevertheless, the new colors allow for much more customization.
|
||||
To make this possible, we have introduced a lot more color variables you can use in [your color variants](configuration/appearance/branding#theme-variant). Your old variants will still work and don't need to be changed as appropriate fallback values are used by the theme. Nevertheless, the new colors allow for much more customization.
|
||||
|
||||
To see what's now possible, see the new variants `relearn-dark` and `neon` that are coming with this release.
|
||||
|
||||
- {{% badge style="info" icon="plus-circle" title=" " %}}New{{% /badge %}} To make the creation of new variants easier for you, we've added a new interactive [theme variant generator](configuration/generator). This feature will not work with Internet Explorer 11.
|
||||
- {{% badge style="info" icon="plus-circle" title=" " %}}New{{% /badge %}} To make the creation of new variants easier for you, we've added a new interactive [theme variant generator](configuration/appearance/generator). This feature will not work with Internet Explorer 11.
|
||||
|
||||
- {{% badge style="info" icon="plus-circle" title=" " %}}New{{% /badge %}} You can now configure multiple color variants in your `hugo.toml`. In this case, the first variant is the default chosen on first view and a variant selector will be shown in the menu footer. See the [documentation](configuration/branding#multiple-variants) for configuration.
|
||||
- {{% badge style="info" icon="plus-circle" title=" " %}}New{{% /badge %}} You can now configure multiple color variants in your `hugo.toml`. In this case, the first variant is the default chosen on first view and a variant selector will be shown in the menu footer. See the [documentation](configuration/appearance/branding#multiple-variants) for configuration.
|
||||
|
||||
Note, that the new variant selector will not work with Internet Explorer 11 as it does not support CSS variables. Therefore, the variant selector will not be displayed with Internet Explorer 11.
|
||||
|
|
|
|||
|
|
@ -16,7 +16,7 @@ weight = -2
|
|||
|
||||
- {{% badge style="note" title=" " %}}Change{{% /badge %}} In this release the Mermaid JavaScript library will only be loaded on demand if the page contains a Mermaid shortcode or is using Markdown codefences. This changes the behavior of `disableMermaid` config option as follows: If a Mermaid shortcode or Markdown codefence is found, the option will be ignored and Mermaid will be loaded regardlessly.
|
||||
|
||||
The option is still useful in case you are using scripting to set up your graph. In this case no shortcode or Markdown codefence is involved and the library is not loaded by default. In this case you can set `disableMermaid=false` in your frontmatter to force the library to be loaded. See the [theme variant generator](configuration/generator) of the exampleSite for an example.
|
||||
The option is still useful in case you are using scripting to set up your graph. In this case no shortcode or Markdown codefence is involved and the library is not loaded by default. In this case you can set `disableMermaid=false` in your frontmatter to force the library to be loaded. See the [theme variant generator](configuration/appearance/generator) of the exampleSite for an example.
|
||||
|
||||
### New
|
||||
|
||||
|
|
|
|||
|
|
@ -10,6 +10,6 @@ weight = -3
|
|||
|
||||
### New
|
||||
|
||||
- {{% badge style="info" icon="plus-circle" title=" " %}}New{{% /badge %}} Introduction of new CSS variables to set the font. The theme distinguishes between `--MAIN-font` for all content text and `--CODE-font` for inline or block code. There are additional overrides for all headings. See the [theme variant generator](configuration/generator) of the exampleSite for all available variables.
|
||||
- {{% badge style="info" icon="plus-circle" title=" " %}}New{{% /badge %}} Introduction of new CSS variables to set the font. The theme distinguishes between `--MAIN-font` for all content text and `--CODE-font` for inline or block code. There are additional overrides for all headings. See the [theme variant generator](configuration/appearance/generator) of the exampleSite for all available variables.
|
||||
|
||||
- {{% badge style="info" icon="plus-circle" title=" " %}}New{{% /badge %}} The new shortcode `swagger` is available to include a UI for REST OpenAPI specifications. See the [documentation](shortcodes/openapi) for available features. This feature will not work with Internet Explorer 11.
|
||||
|
|
|
|||
|
|
@ -16,6 +16,6 @@ weight = -4
|
|||
|
||||
- {{% badge style="info" icon="plus-circle" title=" " %}}New{{% /badge %}} If you prefer expandable/collapsible menu items, you can now set `collapsibleMenu=true` in your `hugo.toml`. This will add arrows to all menu items that contain sub menus. The menu will expand/collapse without navigation if you click on an arrow.
|
||||
|
||||
- {{% badge style="info" icon="plus-circle" title=" " %}}New{{% /badge %}} You can activate [print support](configuration/customization#activate-print-support) in your `hugo.toml` to add the capability to print whole chapters or even the complete site.
|
||||
- {{% badge style="info" icon="plus-circle" title=" " %}}New{{% /badge %}} You can activate [print support](configuration/appearance/topbar/#print-support) in your `hugo.toml` to add the capability to print whole chapters or even the complete site.
|
||||
|
||||
- {{% badge style="info" icon="plus-circle" title=" " %}}New{{% /badge %}} Translation into Traditional Chinese.
|
||||
|
|
|
|||
|
|
@ -10,4 +10,4 @@ weight = -1
|
|||
|
||||
### New
|
||||
|
||||
- {{% badge style="info" icon="plus-circle" title=" " %}}New{{% /badge %}} While fixing issues with the search functionality for non Latin languages, you can now [configure to have multiple languages on a single page](configuration/i18n#search-with-mixed-language-support).
|
||||
- {{% badge style="info" icon="plus-circle" title=" " %}}New{{% /badge %}} While fixing issues with the search functionality for non Latin languages, you can now [configure to have multiple languages on a single page](configuration/sidebar/search/#search-with-mixed-language-support).
|
||||
|
|
|
|||
|
|
@ -22,7 +22,7 @@ weight = -11
|
|||
|
||||
The default setting of `on`, in effect since 1.1.0, changed back to `off` as there was interference with scrolling on mobile and big pages.
|
||||
|
||||
- {{% badge style="note" title=" " %}}Change{{% /badge %}} The theme is now capable to visually [adapt to your OS's light/dark mode setting](configuration/branding#adjust-to-os-settings).
|
||||
- {{% badge style="note" title=" " %}}Change{{% /badge %}} The theme is now capable to visually [adapt to your OS's light/dark mode setting](configuration/appearance/branding#adjust-to-os-settings).
|
||||
|
||||
This is also the new default setting if you haven't configured `themeVariant` in your `hugo.toml`.
|
||||
|
||||
|
|
|
|||
|
|
@ -26,4 +26,4 @@ weight = -16
|
|||
|
||||
Additionally the `name` parameter was renamed to `title` but you don't need to change anything yet as the old name will be used as a fallback. Nevertheless you will get deprecation warnings while executing Hugo.
|
||||
|
||||
- {{% badge style="info" icon="plus-circle" title=" " %}}New{{% /badge %}} The theme now optionally supports [separate favicons](configuration/branding#change-the-favicon) for light & dark mode.
|
||||
- {{% badge style="info" icon="plus-circle" title=" " %}}New{{% /badge %}} The theme now optionally supports [separate favicons](configuration/appearance/branding#change-the-favicon) for light & dark mode.
|
||||
|
|
|
|||
|
|
@ -14,7 +14,7 @@ weight = -19
|
|||
|
||||
- {{% badge style="info" icon="plus-circle" title=" " %}}New{{% /badge %}} The theme has added two new color variants `zen-light` and `zen-dark`. Check it out!
|
||||
|
||||
- {{% badge style="info" icon="plus-circle" title=" " %}}New{{% /badge %}} The theme now [dispatches the custom event](configuration/customization#react-to-variant-switches-in-javascript) `themeVariantLoaded` on the `document` when the variant is fully loaded either initially or by switching the variant manually with the variant selector.
|
||||
- {{% badge style="info" icon="plus-circle" title=" " %}}New{{% /badge %}} The theme now [dispatches the custom event](configuration/modifications/dependencies/#react-to-variant-switches-in-javascript) `themeVariantLoaded` on the `document` when the variant is fully loaded either initially or by switching the variant manually with the variant selector.
|
||||
|
||||
- {{% badge style="info" icon="plus-circle" title=" " %}}New{{% /badge %}} The theme has updated its Mermaid dependency to 10.3.1. This adds support for the [sankey diagram type](shortcodes/mermaid#sankey) and now comes with full support for YAML inside Mermaid graphs (previously, the theme ignored explicit Mermaid theme settings in YAML).
|
||||
|
||||
|
|
|
|||
|
|
@ -10,10 +10,10 @@ weight = -21
|
|||
|
||||
### Change
|
||||
|
||||
- {{% badge style="note" title=" " %}}Change{{% /badge %}} We made changes to the menu footer to improve alignment with the menu items in most cases. Care was taken not to break your existing overwritten footer. Anyways, if you have your `menu-footer.html` [partial overridden](configuration/customization#partials), you may want to review the styling (eg. margins/paddings) of your partial.
|
||||
- {{% badge style="note" title=" " %}}Change{{% /badge %}} We made changes to the menu footer to improve alignment with the menu items in most cases. Care was taken not to break your existing overwritten footer. Anyways, if you have your `menu-footer.html` [partial overridden](configuration/modifications/partials/), you may want to review the styling (eg. margins/paddings) of your partial.
|
||||
|
||||
### New
|
||||
|
||||
- {{% badge style="info" icon="plus-circle" title=" " %}}New{{% /badge %}} This release comes with an awesome new feature, that allows you to customize your topbar buttons, change behavior, reorder them or define entirely new ones, unique to your installation. See [the documentation](configuration/topbar) for further details.
|
||||
- {{% badge style="info" icon="plus-circle" title=" " %}}New{{% /badge %}} This release comes with an awesome new feature, that allows you to customize your topbar buttons, change behavior, reorder them or define entirely new ones, unique to your installation. See [the documentation](configuration/modifications/topbar/) for further details.
|
||||
|
||||
- {{% badge style="info" icon="plus-circle" title=" " %}}New{{% /badge %}} The theme has updated its Swagger dependency to 5.7.2 for the [`openapi` shortcode](shortcodes/openapi). This brings support for OpenAPI Specification 3.1.
|
||||
|
|
|
|||
|
|
@ -18,7 +18,7 @@ weight = -22
|
|||
|
||||
This can come in handy, if content for such a section page doesn't make much sense to you. See [the documentation](content/frontmatter#disable-section-pages) for how to do this.
|
||||
|
||||
This feature may require you to make changes to your existing installation if you are already using _[shortcuts to pages inside of your project](configuration/menushortcuts#shortcuts-to-pages-inside-of-your-project)_ with a _headless branch parent_.
|
||||
This feature may require you to make changes to your existing installation if you are already using _[shortcuts to pages inside of your project](configuration/sidebar/shortcutmenu/#shortcuts-to-pages-inside-of-your-project)_ with a _headless branch parent_.
|
||||
|
||||
In this case it is advised to remove the `title` from the headless branch parent's frontmatter, as it will otherwise appear in your breadcrumbs.
|
||||
|
||||
|
|
|
|||
|
|
@ -34,13 +34,13 @@ weight = -23
|
|||
|
||||
- {{% badge style="info" icon="plus-circle" title=" " %}}New{{% /badge %}} It is now possible to print custom taxonomies anywhere in your page. [See the docs](content/taxonomy#customization).
|
||||
|
||||
- {{% badge style="info" icon="plus-circle" title=" " %}}New{{% /badge %}} It is now possible to adjust the menu width for your whole site. [See the docs](configuration/customization#change-the-menu-width).
|
||||
- {{% badge style="info" icon="plus-circle" title=" " %}}New{{% /badge %}} It is now possible to adjust the menu width for your whole site. [See the docs](configuration/sidebar/width/).
|
||||
|
||||
- {{% badge style="info" icon="plus-circle" title=" " %}}New{{% /badge %}} This release adds social media meta tags for the Open Graph protocol and Twitter Cards to your site. [See the docs](configuration/customization#social-media-meta-tags).
|
||||
- {{% badge style="info" icon="plus-circle" title=" " %}}New{{% /badge %}} This release adds social media meta tags for the Open Graph protocol and Twitter Cards to your site. [See the docs](configuration/content/image/).
|
||||
|
||||
- {{% badge style="info" icon="plus-circle" title=" " %}}New{{% /badge %}} This release comes with additional sort options for the menu and the [`children` shortcode](shortcodes/children). Both will now accept the following values: `weight`, `title`, `linktitle`, `modifieddate`, `expirydate`, `publishdate`, `date`, `length` or `default` (adhering to Hugo's default sort order).
|
||||
|
||||
- {{% badge style="info" icon="plus-circle" title=" " %}}New{{% /badge %}} The theme now provides a mechanism to load further JavaScript dependencies defined by you only if it is needed. This comes in handy if you want to add own shortcodes that depend on additional JavaScript code to be loaded. [See the docs](configuration/customization#own-shortcodes-with-javascript-dependencies).
|
||||
- {{% badge style="info" icon="plus-circle" title=" " %}}New{{% /badge %}} The theme now provides a mechanism to load further JavaScript dependencies defined by you only if it is needed. This comes in handy if you want to add own shortcodes that depend on additional JavaScript code to be loaded. [See the docs](configuration/modifications/dependencies/).
|
||||
|
||||
- {{% badge style="info" icon="plus-circle" title=" " %}}New{{% /badge %}} The theme has updated its Mermaid dependency to 10.6.0. This adds support for the [xychart type](shortcodes/mermaid#xychart).
|
||||
|
||||
|
|
@ -56,10 +56,10 @@ weight = -23
|
|||
|
||||
| link | description |
|
||||
| ---------------------------------- | ------------------------------------------- |
|
||||
| `[generator](en/configuration/generator)` | absolute from your project root (multilang) |
|
||||
| `[generator](/en/configuration/generator)`| absolute from your project root (multilang) |
|
||||
| `[generator](configuration/generator)` | absolute from your current language root |
|
||||
| `[generator](/configuration/generator)` | absolute from your current language root |
|
||||
| `[generator](en/configuration/appearance/generator)` | absolute from your project root (multilang) |
|
||||
| `[generator](/en/configuration/appearance/generator)`| absolute from your project root (multilang) |
|
||||
| `[generator](configuration/appearance/generator)` | absolute from your current language root |
|
||||
| `[generator](/configuration/appearance/generator)` | absolute from your current language root |
|
||||
| `[generator](./../generator)` | relative from the current page |
|
||||
| `[generator](../generator)` | relative from the current page |
|
||||
|
||||
|
|
|
|||
|
|
@ -18,7 +18,7 @@ weight = -24
|
|||
|
||||
- {{% badge style="note" title=" " %}}Change{{% /badge %}} The frontmatter option `menuTitle` is now deprecated in favor for Hugo's own `linkTitle`. You don't need to change anything as the old `menuTitle` option is still supported.
|
||||
|
||||
- {{% badge style="note" title=" " %}}Change{{% /badge %}} The light themes have a bit more contrast for content text and headings. Also the syntaxhighlighting was changed to the more colorful MonokaiLight. This brings the syntaxhighlighting in sync with the corresponding dark theme variants, which are using Monokai. If you dislike this, you can create your own color variant file as [described here](configuration/branding#modify-shipped-variants).
|
||||
- {{% badge style="note" title=" " %}}Change{{% /badge %}} The light themes have a bit more contrast for content text and headings. Also the syntaxhighlighting was changed to the more colorful MonokaiLight. This brings the syntaxhighlighting in sync with the corresponding dark theme variants, which are using Monokai. If you dislike this, you can create your own color variant file as [described here](configuration/appearance/branding#modify-shipped-variants).
|
||||
|
||||
### New
|
||||
|
||||
|
|
@ -28,17 +28,17 @@ weight = -24
|
|||
|
||||
Please note that an image link will generate false negatives if the file resides in your `static` directory.
|
||||
|
||||
- {{% badge style="info" icon="plus-circle" title=" " %}}New{{% /badge %}} You now can configure additional options for every theme variant in your `hugo.toml`. This allows for optional [advanced functionality](configuration/branding#theme-variant-advanced). You don't need to change anything as the old configuration options will still work (but may generate warnings now).
|
||||
- {{% badge style="info" icon="plus-circle" title=" " %}}New{{% /badge %}} You now can configure additional options for every theme variant in your `hugo.toml`. This allows for optional [advanced functionality](configuration/appearance/branding#theme-variant-advanced). You don't need to change anything as the old configuration options will still work (but may generate warnings now).
|
||||
|
||||
The advanced functionality allows you to set an explicit name for a theme variant and now allows for multiple auto mode variants that adjust to the light/dark preference of your OS settings.
|
||||
|
||||
- {{% badge style="info" icon="plus-circle" title=" " %}}New{{% /badge %}} New partial for defining the heading. See [documentation](configuration/customization#partials) for further reading.
|
||||
- {{% badge style="info" icon="plus-circle" title=" " %}}New{{% /badge %}} New partial for defining the heading. See [documentation](configuration/modifications/partials/) for further reading.
|
||||
|
||||
- {{% badge style="info" icon="plus-circle" title=" " %}}New{{% /badge %}} Support for Hugo's built-in [`figure` shortcode](https://gohugo.io/content-management/shortcodes/#figure).
|
||||
|
||||
- {{% badge style="info" icon="plus-circle" title=" " %}}New{{% /badge %}} On taxonomy and term pages you can now use prev/next navigation as within the normal page structure.
|
||||
|
||||
- {{% badge style="info" icon="plus-circle" title=" " %}}New{{% /badge %}} In additiion to the existing [menu width customization](configuration/customization#change-the-menu-width), it is now also possible to set the width of the menu flyout for small screen sizes with the `--MENU-WIDTH-S` CSS property.
|
||||
- {{% badge style="info" icon="plus-circle" title=" " %}}New{{% /badge %}} In additiion to the existing [menu width customization](configuration/sidebar/width/), it is now also possible to set the width of the menu flyout for small screen sizes with the `--MENU-WIDTH-S` CSS property.
|
||||
|
||||
- {{% badge style="info" icon="plus-circle" title=" " %}}New{{% /badge %}} Improvements for accessibility when tabbing through the page for images, links and tab handles.
|
||||
|
||||
|
|
@ -48,4 +48,4 @@ weight = -24
|
|||
|
||||
- {{% badge style="info" icon="plus-circle" title=" " %}}New{{% /badge %}} Restored compatibility with Hugo versions {{% badge color="fuchsia" icon="fa-fw fab fa-hackerrank" title=" " %}}0.121.0{{% /badge %}} or higher for the [`highlight` shortcode](shortcodes/highlight). This does not change the minimum required Hugo version.
|
||||
|
||||
- {{% badge style="info" icon="plus-circle" title=" " %}}New{{% /badge %}} Restored compatibility with Hugo versions {{% badge color="fuchsia" icon="fa-fw fab fa-hackerrank" title=" " %}}0.123.0{{% /badge %}} or higher for theme specific [output formats](configuration/customization) and handling of taxonomy and term titles. This does not change the minimum required Hugo version.
|
||||
- {{% badge style="info" icon="plus-circle" title=" " %}}New{{% /badge %}} Restored compatibility with Hugo versions {{% badge color="fuchsia" icon="fa-fw fab fa-hackerrank" title=" " %}}0.123.0{{% /badge %}} or higher for theme specific output formats and handling of taxonomy and term titles. This does not change the minimum required Hugo version.
|
||||
|
|
|
|||
|
|
@ -12,7 +12,7 @@ weight = -26
|
|||
|
||||
- {{% badge style="info" icon="plus-circle" title=" " %}}New{{% /badge %}} The lazy loading of images is now configurable by using the new `lazy` [image effect](content/imageeffects). The default value hasn't changed in comparison to older versions, you don't need to change anything.
|
||||
|
||||
- {{% badge style="info" icon="plus-circle" title=" " %}}New{{% /badge %}} It is now possible to [adjust the max width of the main area](configuration/customization#change-the-main-areas-max-width), eg. in case you want to use the full page width for your content.
|
||||
- {{% badge style="info" icon="plus-circle" title=" " %}}New{{% /badge %}} It is now possible to [adjust the max width of the main area](configuration/content/width/), eg. in case you want to use the full page width for your content.
|
||||
|
||||
- {{% badge style="info" icon="plus-circle" title=" " %}}New{{% /badge %}} Images and Markdown codefences are now respecting [Hugo's Markdown attributes](https://gohugo.io/content-management/markdown-attributes/).
|
||||
|
||||
|
|
|
|||
|
|
@ -16,7 +16,7 @@ weight = -27
|
|||
|
||||
- {{% badge style="note" title=" " %}}Change{{% /badge %}} If the theme is configured to generate warnings or errors during build by setting `image.errorlevel` to either `warning` or `error` in your `hugo.toml`, it will now also generate output if a link fragment is not found in the target page.
|
||||
|
||||
- {{% badge style="note" title=" " %}}Change{{% /badge %}} The [dependency loader](configuration/customization#own-shortcodes-with-javascript-dependencies) was made more versatile.
|
||||
- {{% badge style="note" title=" " %}}Change{{% /badge %}} The [dependency loader](configuration/modifications/dependencies/) was made more versatile.
|
||||
|
||||
The configuration in your `hugo.toml` does not require the `location` parameter anymore. If you still use it, the theme will work as before but will generate a warning. So you don't need to change anything, yet.
|
||||
|
||||
|
|
|
|||
|
|
@ -16,4 +16,4 @@ weight = -3
|
|||
|
||||
- {{% badge style="info" icon="plus-circle" title=" " %}}New{{% /badge %}} [Image formatting](content/markdown#css-classes) has two new classes to align images to the `left` or `right`. Additionally, the already existing `inline` option is now documented.
|
||||
|
||||
- {{% badge style="info" icon="plus-circle" title=" " %}}New{{% /badge %}} Printing for the [`swagger` shortcode](shortcodes/openapi) was optimized to expand sections that are usually closed in interactive mode. This requires [print support](configuration/customization#activate-print-support) to be configured.
|
||||
- {{% badge style="info" icon="plus-circle" title=" " %}}New{{% /badge %}} Printing for the [`swagger` shortcode](shortcodes/openapi) was optimized to expand sections that are usually closed in interactive mode. This requires [print support](configuration/appearance/topbar/#print-support) to be configured.
|
||||
|
|
|
|||
|
|
@ -10,7 +10,7 @@ weight = -4
|
|||
|
||||
### Change
|
||||
|
||||
- {{% badge style="note" title=" " %}}Change{{% /badge %}} [With the proper settings](configuration/customization#file-system) in your `hugo.toml` your page is now servable from the local file system using `file://` URLs.
|
||||
- {{% badge style="note" title=" " %}}Change{{% /badge %}} [With the proper settings](configuration/siteorganization/deploymentscenarios/) in your `hugo.toml` your page is now servable from the local file system using `file://` URLs.
|
||||
|
||||
Please note that the searchbox will only work for this if you reconfigure your outputformat for the homepage in your `hugo.toml` from `json` to `search`. The now deprecated `json` outputformat still works as before, so there is no need to reconfigure your installation if it is only served from `http://` or `https://`.
|
||||
|
||||
|
|
|
|||
|
|
@ -12,7 +12,7 @@ weight = -6
|
|||
|
||||
- {{% badge style="info" icon="plus-circle" title=" " %}}New{{% /badge %}} This release introduces an additional dedicated search page. On this page, displayed search results have more space making it easier scanning through large number of results.
|
||||
|
||||
To activate this feature, you need to [configure it](configuration/customization#configure-search) in your `hugo.toml` as a new outputformat `searchpage` for the home page. If you don't configure it, no dedicated search page will be accessible and the theme works as before.
|
||||
To activate this feature, you need to [configure it](configuration/sidebar/search/) in your `hugo.toml` as a new outputformat `searchpage` for the home page. If you don't configure it, no dedicated search page will be accessible and the theme works as before.
|
||||
|
||||
You can access the search page by either clicking on the magnifier glass or pressing enter inside of the search box.
|
||||
|
||||
|
|
|
|||
|
|
@ -14,7 +14,7 @@ weight = -9
|
|||
|
||||
It was later discovered, that this causes pages only meant to be displayed in the `More` section of the menu and stored directly inside your `content` directory to now show up in the menu as well.
|
||||
|
||||
To [get rid](configuration/menushortcuts#shortcuts-to-pages-inside-of-your-project) of this undesired behavior you have two choices:
|
||||
To [get rid](configuration/sidebar/shortcutmenu/#shortcuts-to-pages-inside-of-your-project) of this undesired behavior you have two choices:
|
||||
|
||||
1. Make the page file a [headless branch bundle](https://gohugo.io/content-management/page-bundles/#headless-bundle) (contained in its own subdirectory and called `_index.md`) and add the following frontmatter configuration to the file (see exampleSite's `content/showcase/_index.en.md`). This causes its content to **not** be ontained in the sitemap.
|
||||
|
||||
|
|
|
|||
|
|
@ -30,7 +30,7 @@ weight = -0
|
|||
|
||||
- {{% badge style="warning" title=" " %}}Breaking{{% /badge %}} Search support for the `json` outputformat [deprecated in 5.4.0](basics/releasenotes/5/#5-4-0) was removed.
|
||||
|
||||
Change it to `search` for the homepage in your `hugo.toml`. See the docs for [detailed configuration](configuration/customization#configure-search).
|
||||
Change it to `search` for the homepage in your `hugo.toml`. See the docs for [detailed configuration](configuration/sidebar/search/).
|
||||
|
||||
- {{% badge style="warning" title=" " %}}Breaking{{% /badge %}} The frontmatter option `menuTitle` [deprecated in 5.24.0](basics/releasenotes/5/#5-24-0) was removed in favor for Hugo's own `linkTitle`.
|
||||
|
||||
|
|
|
|||
|
|
@ -14,7 +14,7 @@ weight = -2
|
|||
|
||||
If you now click on it, not only is the link copied to the clipboard (previous behavior) but also the heading scrolls to the top of the page.
|
||||
|
||||
If you dislike the new behavior, you can deactivate it by setting `disableAnchorScrolling=true` in your `hugo.toml`. See the [docs for further options](configuration/customization#change-heading-anchor-behavior).
|
||||
If you dislike the new behavior, you can deactivate it by setting `disableAnchorScrolling=true` in your `hugo.toml`. See the [docs for further options](configuration/content/headings/).
|
||||
|
||||
### New
|
||||
|
||||
|
|
|
|||
|
|
@ -50,4 +50,4 @@ weight = -0
|
|||
|
||||
In addition you are now able to overwrite the default file name of the search index and the default page name of the dedicated search page by changing `searchIndexURL` and `searchPageURL` respectively in your `hugo.toml`.
|
||||
|
||||
See the [updated documentation](configuration/customization#configure-search) for reference.
|
||||
See the [updated documentation](configuration/sidebar/search/) for reference.
|
||||
|
|
|
|||
|
|
@ -0,0 +1,8 @@
|
|||
+++
|
||||
alwaysopen = false
|
||||
description = "Change colors, logos and the general appearance of your site"
|
||||
title = "Appearance"
|
||||
weight = 2
|
||||
+++
|
||||
|
||||
{{% children containerstyle="div" style="h2" description=true %}}
|
||||
|
|
@ -0,0 +1,7 @@
|
|||
+++
|
||||
alwaysopen = false
|
||||
description = "Change colors, logos and the general appearance of your site"
|
||||
title = "Appearance"
|
||||
weight = 2
|
||||
+++
|
||||
{{< piratify >}}
|
||||
|
|
@ -1,33 +1,37 @@
|
|||
+++
|
||||
categories = ["custom", "theming"]
|
||||
description = "How to configure colors, fonts, favicon and logo"
|
||||
title = "Branding"
|
||||
weight = 2
|
||||
weight = 1
|
||||
+++
|
||||
|
||||
The Relearn theme provides configuration options to change your site's colors, favicon and logo. This allows you to easily align your site visuals to your desired style. Most of these options are exposed through so called color variants.
|
||||
The Relearn theme provides settings to change your site's colors, fonts, favicon and logo. These settings are bundled in so called color variants that are contained of a CSS file and optional configuration options in your `hugo.toml`.
|
||||
|
||||
A color variant lets you customize various visual effects of your site like almost any color, used fonts, color schemes of print, syntax highligtning, Mermaid and the OpenAPI shortcode, etc. It contains of a CSS file and optional configuration options in your `hugo.toml`.
|
||||
|
||||
The Relearn theme ships with a wide set of different color variants. You can use them as-is, copy them over and use them as a starting point for your customizations or just create completely new variants unique to your site. The [interactive variant generator](configuration/generator) may help you with this task.
|
||||
The Relearn theme ships with a set of predefined color variants. You can use them as-is, copy them over and use them as a starting point for your customizations or just create completely new variants unique to your site. The [interactive variant generator](configuration/appearance/generator) may help you with this task.
|
||||
|
||||
Once configured in your `hugo.toml`, you can select them with the variant selector at the bottom of the menu.
|
||||
|
||||
## Change the Variant (Simple) {#theme-variant}
|
||||
|
||||
{{% notice tip %}}
|
||||
The theme provides an advanced configuration mode, combining the functionality for multiple variants with the possibility of adjusting to your OS settings and syntax highlighting and even more!
|
||||
|
||||
Although all options documented here are still working, the advanced configuration options are the recommended way to configure your color variants. [See below](#theme-variant-advanced).
|
||||
{{% /notice %}}
|
||||
|
||||
### Single Variant
|
||||
|
||||
Set the `themeVariant` value to the name of your theme file. That's it! Your site will be displayed in this variant only.
|
||||
Set the `themeVariant` value to the name of your theme CSS file. That's it! Your site will be displayed in this variant only.
|
||||
|
||||
{{< multiconfig file=hugo >}}
|
||||
[params]
|
||||
themeVariant = "relearn-light"
|
||||
{{< /multiconfig >}}
|
||||
|
||||
{{% notice note %}}
|
||||
Your theme variant file must reside in your site's `assets/css` directory and the file name must start with `theme-` and end in `.css`. In the above example, the path of your theme file must be `assets/css/theme-relearn-light.css`.
|
||||
Your theme variant file must either reside in your site's `assets/css` directory or in the similar location of the theme at `themes/hugo-theme-relearn/assets/css`. The file name must start with `theme-` and end in `.css`.
|
||||
|
||||
If you want to make changes to a shipped color variant, create a copy in your site's `assets/css` directory. Don't edit the file in the theme's directory!
|
||||
{{% /notice %}}
|
||||
In the above example, the path of your theme file must be `assets/css/theme-relearn-light.css` or `themes/hugo-theme-relearn/assets/css/theme-relearn-light.css`.
|
||||
|
||||
If you want to make changes to a shipped color variant, [see your choices below](#modify-shipped-variants).
|
||||
|
||||
### Multiple Variants
|
||||
|
||||
|
|
@ -38,15 +42,9 @@ You can also set multiple variants. In this case, the first variant is the defau
|
|||
themeVariant = [ "relearn-light", "relearn-dark" ]
|
||||
{{< /multiconfig >}}
|
||||
|
||||
{{% notice tip %}}
|
||||
The theme provides an advanced configuration mode, combining the functionality for multiple variants with the below possibilities of adjusting to your OS settings and syntax highlighting and even more!
|
||||
### Adjust to OS Settings
|
||||
|
||||
Although all options documented here are still working, the advanced configuration options are the recommended way to configure your color variants. [See below](#theme-variant-advanced).
|
||||
{{% /notice %}}
|
||||
|
||||
## 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` to become an auto mode variant. That's it.
|
||||
You can also cause the site to adjust to your OS settings for light/dark mode. Just set the `params.themeVariant` to `auto` to become an auto mode variant. That's it.
|
||||
|
||||
You can use the `auto` value with the single or multiple variants option. If you are using multiple variants, you can drop `auto` at any position in the option's array, but usually it makes sense to set it in the first position and make it the default.
|
||||
|
||||
|
|
@ -55,50 +53,20 @@ You can use the `auto` value with the single or multiple variants option. If you
|
|||
themeVariant = [ "auto", "red" ]
|
||||
{{< /multiconfig >}}
|
||||
|
||||
If you don't configure anything else, the theme will default to use `relearn-light` for light mode and `relearn-dark` for dark mode. These defaults are overwritten by the first two non-auto options of your `themeVariant` option if present.
|
||||
If you don't configure anything else, the theme will default to use `relearn-light` for light mode and `relearn-dark` for dark mode. These defaults are overwritten by the first two non-auto options of your `params.themeVariant` option if present.
|
||||
|
||||
In the above example, you would end with `red` for light mode and the default of `relearn-dark` for dark mode.
|
||||
|
||||
If you don't like that behavior, you can explicitly set `themeVariantAuto`. The first entry in the array is the color variant for light mode, the second for dark mode.
|
||||
If you don't like that behavior, you can explicitly set `params.themeVariantAuto`. The first entry in the array is the color variant for light mode, the second for dark mode.
|
||||
|
||||
{{< multiconfig file=hugo >}}
|
||||
[params]
|
||||
themeVariantAuto = [ "learn", "neon" ]
|
||||
{{< /multiconfig >}}
|
||||
|
||||
## Change the Favicon
|
||||
|
||||
If your favicon is a SVG, PNG or ICO, just drop your image in your site's `static/images/` directory and name it `favicon.svg`, `favicon.png` or `favicon.ico` respectively.
|
||||
|
||||
If you want to adjust your favicon according to your OS settings for light/dark mode, add the image files `static/images/favicon-light.svg` and `static/images/favicon-dark.svg` to your site's directory, respectively, corresponding to your file format. In case some of the files are missing, the theme falls back to `favicon.svg` for each missing file. All supplied favicons must be of the same file format.
|
||||
|
||||
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.
|
||||
|
||||
If you need to change this default behavior, create a new file `layouts/partials/favicon.html` in your site's directory and write something like this:
|
||||
|
||||
````html {title="layouts/partials/favicon.html"}
|
||||
<link rel="icon" href="/images/favicon.bmp" type="image/bmp">
|
||||
````
|
||||
|
||||
## Change the Logo
|
||||
|
||||
Create a new file in `layouts/partials/logo.html` of your site. Then write any HTML you want. You could use an `img` HTML tag and reference an image created under the _static_ directory, or you could paste a SVG definition!
|
||||
|
||||
{{% notice note %}}
|
||||
The size of the logo will adapt automatically.
|
||||
{{% /notice %}}
|
||||
|
||||
## Syntax Highlighting
|
||||
|
||||
If you want to switch the syntax highlighting theme together with your color variant, you need to configure your installation [according to Hugo's documentation](https://gohugo.io/content-management/syntax-highlighting/) and provide a syntax highlighting stylesheet file.
|
||||
|
||||
You can use a one of the shipped stylesheet files or use Hugo to generate a file for you. The file must be written to `assets/css/chroma-<NAME>.css`. To use it with your color variant you have to define `--CODE-theme: <NAME>` in the color variant stylesheet file.
|
||||
|
||||
For an example, take a look into [`theme-relearn-light.css`](https://github.com/McShelby/hugo-theme-relearn/blob/main/assets/css/theme-relearn-light.css) and [`hugo.toml`](https://github.com/McShelby/hugo-theme-relearn/blob/main/exampleSite/config/_default/hugo.toml) of the exampleSite.
|
||||
|
||||
## Change the Variant (Advanced) {#theme-variant-advanced}
|
||||
|
||||
The theme offers a new way to configure theme variants and all of the aspects above inside of a single configuration item. This comes with some features previously unsupported.
|
||||
The theme offers an advanced way to configure theme variants and all of the aspects above inside of a single configuration item. This comes with some features previously unsupported.
|
||||
|
||||
Like with the [multiple variants](#multiple-variants) option, you are defining your theme variants in an array but now _not by simple strings_ **but in a table with suboptions**.
|
||||
|
||||
|
|
@ -132,34 +100,27 @@ The `identifier` option is mandatory and equivalent to the string in the first e
|
|||
### Example Configuration of This Site
|
||||
|
||||
{{< multiconfig file=hugo >}}
|
||||
[params]
|
||||
[[params.themeVariant]]
|
||||
identifier = "relearn-auto"
|
||||
name = "Relearn Light/Dark"
|
||||
auto = []
|
||||
[[params.themeVariant]]
|
||||
identifier = "relearn-light"
|
||||
[[params.themeVariant]]
|
||||
identifier = "relearn-dark"
|
||||
[[params.themeVariant]]
|
||||
identifier = "zen-auto"
|
||||
name = "Zen Light/Dark"
|
||||
auto = [ "zen-light", "zen-dark" ]
|
||||
[[params.themeVariant]]
|
||||
identifier = "zen-light"
|
||||
[[params.themeVariant]]
|
||||
identifier = "zen-dark"
|
||||
[[params.themeVariant]]
|
||||
identifier = "neon"
|
||||
themeVariant = [
|
||||
{ identifier = "relearn-auto", name = "Relearn Light/Dark", auto = [] },
|
||||
{ identifier = "relearn-light" },
|
||||
{ identifier = "relearn-dark" },
|
||||
{ identifier = "relearn-bright" },
|
||||
{ identifier = "zen-auto", name = "Zen Light/Dark", auto = [ "zen-light", "zen-dark" ] },
|
||||
{ identifier = "zen-light" },
|
||||
{ identifier = "zen-dark" },
|
||||
{ identifier = "retro-auto", name = "Retro Learn/Neon", auto = [ "learn", "neon" ] },
|
||||
{ identifier = "neon" },
|
||||
{ identifier = "learn" }
|
||||
]
|
||||
{{< /multiconfig >}}
|
||||
|
||||
## Modify Shipped Variants
|
||||
|
||||
In case you like a shipped variant but only want to tweak some aspects, you have two choices:
|
||||
In case you like a shipped variant but only want to tweak some aspects, you have some choices. **Don't edit the file in the theme's directory!** You will loose the ability to later easily upgrade your theme to a newer version.
|
||||
|
||||
1. Copy and change
|
||||
|
||||
You can copy the shipped variant file from the theme's `assets/css` directory to the site's `assets/css` directory and either store it with the same name or give it a new name. Edit the settings and save the new file. Afterwards you can use it in your `hugo.toml` by the chosen name.
|
||||
You can copy the shipped variant file from the theme's `themes/hugo-theme-relearn/assets/css` directory to the site's `assets/css` directory and either store it with the same name or give it a new name. Edit the settings and save the new file. Afterwards you can use it in your `hugo.toml` by the chosen name.
|
||||
|
||||
2. Create and import
|
||||
|
||||
|
|
@ -185,3 +146,46 @@ In case you like a shipped variant but only want to tweak some aspects, you have
|
|||
{{< /multiconfig >}}
|
||||
|
||||
In comparison to _copy and change_, this has the advantage that you profit from any adjustments to the `relearn-light` variant but keep your modifications.
|
||||
|
||||
## Syntax Highlighting
|
||||
|
||||
If you want to switch the syntax highlighting theme together with your color variant, first you need to configure your installation [according to Hugo's documentation](https://gohugo.io/content-management/syntax-highlighting/#generate-syntax-highlighter-css) to provide a syntax highlighting stylesheet file
|
||||
|
||||
{{< multiconfig file=hugo >}}
|
||||
markup.highlight.noClasses=false
|
||||
{{< /multiconfig >}}
|
||||
|
||||
You can use one of the shipped stylesheet files or use Hugo to generate a file for you
|
||||
|
||||
````shell
|
||||
hugo gen chromastyles --style=monokai > chroma-mycode.css
|
||||
````
|
||||
|
||||
The file must be written to `assets/css/chroma-<NAME>.css`. To use it with your color variant you have to modify `--CODE-theme: <NAME>` in the color variant stylesheet file
|
||||
|
||||
````css {title="assets/css/theme-my-branding.css"}
|
||||
@import "theme-relearn-light.css";
|
||||
:root {
|
||||
--CODE-theme: mycode; /* name of the chroma stylesheet file */
|
||||
}
|
||||
````
|
||||
|
||||
## Change the Favicon
|
||||
|
||||
If your favicon is a SVG, PNG or ICO, just drop your image in your site's `static/images/` directory and name it `favicon.svg`, `favicon.png` or `favicon.ico` respectively.
|
||||
|
||||
If you want to adjust your favicon according to your OS settings for light/dark mode, add the image files `static/images/favicon-light.svg` and `static/images/favicon-dark.svg` to your site's directory, respectively, corresponding to your file format. In case some of the files are missing, the theme falls back to `favicon.svg` for each missing file. All supplied favicons must be of the same file format.
|
||||
|
||||
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.
|
||||
|
||||
If you need to change this default behavior, create a new file `layouts/partials/favicon.html` in your site's directory and write something like this:
|
||||
|
||||
````html {title="layouts/partials/favicon.html"}
|
||||
<link rel="icon" href="/images/favicon.bmp" type="image/bmp">
|
||||
````
|
||||
|
||||
## Change the Logo
|
||||
|
||||
Create a new file in `layouts/partials/logo.html` of your site. Then write any HTML you want. You could use an `img` HTML tag and reference an image or you could paste a SVG definition!
|
||||
|
||||
The size of the logo will adapt automatically.
|
||||
|
|
@ -0,0 +1,6 @@
|
|||
+++
|
||||
description = "How to configure colors, fonts, favicon and logo"
|
||||
title = "Brrrand'n"
|
||||
weight = 1
|
||||
+++
|
||||
{{< piratify >}}
|
||||
|
|
@ -1,8 +1,8 @@
|
|||
+++
|
||||
categories = "theming"
|
||||
description = "An interactive tool to generate color variant stylesheets"
|
||||
disableMermaid = false
|
||||
title = "Stylesheet Generator"
|
||||
weight = 6
|
||||
weight = 9
|
||||
+++
|
||||
|
||||
This interactive tool may help you to generate your own color variant stylesheet.
|
||||
|
|
@ -22,7 +22,7 @@ Once you are satisfied, you can download the new variants file and copy it into
|
|||
|
||||
Eg. if your new variants file is named `theme-my-custom-variant.css`, you have to set `themeVariant='my-custom-variant'` to use it.
|
||||
|
||||
See the docs for [further configuration options](configuration/branding)
|
||||
See the docs for [further configuration options](configuration/appearance/branding)
|
||||
{{% /expand %}}
|
||||
|
||||
{{% button style="secondary" icon="download" href="javascript:window.variants&&variants.getStylesheet();this.blur();" %}}Download variant{{% /button %}}
|
||||
|
|
@ -0,0 +1,6 @@
|
|||
+++
|
||||
description = "An interactive tool to generate color variant stylesheets"
|
||||
title = "Stylesheet Generrrat'r"
|
||||
weight = 9
|
||||
+++
|
||||
{{< piratify >}}
|
||||
|
|
@ -0,0 +1,50 @@
|
|||
+++
|
||||
description = "Configure the site's topbar"
|
||||
title = "Topbar"
|
||||
weight = 3
|
||||
+++
|
||||
|
||||
This page is about how to configure supported options for the topbar. If you want to add further buttons or functionality, [see this section](configuration/modifications/topbar).
|
||||
|
||||
## Table of Contents
|
||||
|
||||
Set `params.disableToc=true` to hide the TOC button on all pages. If the button is hidden, also the keyboard shortcut is disabled. This can be overridden in a page's front matter.
|
||||
|
||||
## Breadcrumbs
|
||||
|
||||
Set `params.disableBreadcrumb=true` to hide the breadcrumb in the topbar.
|
||||
|
||||
Further, you can override the breadcrumb separator by using `params.breadcrumbSeparator="/"`. This separator will also be used in the breadcrumbs of the search results and taxonomy pages.
|
||||
|
||||
Set `params.disableRootBreadcrumb=true` to remove the root breadcrumb which often feels redundant. This will also apply to the breadcrumbs of the search results and taxonomy pages.
|
||||
|
||||
## Edit Button
|
||||
|
||||
If `editURL` is set to a URL, an edit button will be shown in the topbar. If the button is hidden, also the keyboard shortcut is disabled.
|
||||
|
||||
The value can contain the macro `${FilePath}` which will be replaced by the file path of your displayed page. If no `${FilePath}` is given in the value, the value is treated as if the `${FilePath}` was appended at the end of the value. This can be overridden in the pages frontmatter.
|
||||
|
||||
Eg. this site is using `editURL="https://github.com/McShelby/hugo-theme-relearn/edit/main/exampleSite/content/${FilePath}"`
|
||||
|
||||
## Print Support
|
||||
|
||||
You can activate print support to add the capability to print whole chapters or even the complete site. Just add the `print` output format to your home, section and page in your `hugo.toml` similar to the below:
|
||||
|
||||
{{< multiconfig file=hugo >}}
|
||||
[outputs]
|
||||
home = ["html", "rss", "print"]
|
||||
section = ["html", "rss", "print"]
|
||||
page = ["html", "rss", "print"]
|
||||
{{< /multiconfig >}}
|
||||
|
||||
This will add a little printer icon in the top bar. It will switch the page to print preview when clicked. You can then send this page to the printer by using your browser's usual print functionality.
|
||||
|
||||
{{% notice note %}}
|
||||
The resulting URL will not be [configured ugly](https://gohugo.io/templates/output-formats/#configure-output-formats) in terms of [Hugo's URL handling](https://gohugo.io/content-management/urls/#ugly-urls) even if you've set `uglyURLs=true` in your `hugo.toml`. This is due to the fact that for one mime type only one suffix can be configured.
|
||||
|
||||
Nevertheless, if you're unhappy with the resulting URLs you can manually redefine `outputFormats.print` in your own `hugo.toml` to your liking.
|
||||
{{% /notice %}}
|
||||
|
||||
## Arrow Navigation
|
||||
|
||||
You can hide the previous/next buttons by setting `params.disableNextPrev=true`. If the buttons are hidden, also the keyboard shortcuts are disabled.
|
||||
|
|
@ -0,0 +1,6 @@
|
|||
+++
|
||||
description = "Configure the site's topbar"
|
||||
title = "Topbarrr"
|
||||
weight = 3
|
||||
+++
|
||||
{{< piratify >}}
|
||||
|
|
@ -1,6 +0,0 @@
|
|||
+++
|
||||
categories = ["custom", "theming"]
|
||||
title = "Brrrand'n"
|
||||
weight = 2
|
||||
+++
|
||||
{{< piratify >}}
|
||||
8
exampleSite/content/configuration/content/_index.en.md
Normal file
8
exampleSite/content/configuration/content/_index.en.md
Normal file
|
|
@ -0,0 +1,8 @@
|
|||
+++
|
||||
alwaysopen = false
|
||||
description = "Configure the content area of your site"
|
||||
title = "Content"
|
||||
weight = 4
|
||||
+++
|
||||
|
||||
{{% children containerstyle="div" style="h2" description=true %}}
|
||||
7
exampleSite/content/configuration/content/_index.pir.md
Normal file
7
exampleSite/content/configuration/content/_index.pir.md
Normal file
|
|
@ -0,0 +1,7 @@
|
|||
+++
|
||||
alwaysopen = false
|
||||
description = "Configure the content area of your site"
|
||||
title = "Content"
|
||||
weight = 4
|
||||
+++
|
||||
{{< piratify >}}
|
||||
|
|
@ -0,0 +1,23 @@
|
|||
+++
|
||||
description = "How to configure heading anchors"
|
||||
title = "Headings"
|
||||
weight = 3
|
||||
+++
|
||||
|
||||
Each heading may have an anchor link that is displayed when the heading is hovered.
|
||||
|
||||
The behavior what should happen if the anchor icon is clicked is configurable in your `hugo.toml`. By default all options are activated. If you deactivate all options, no link will be shown on hover.
|
||||
|
||||
{{< multiconfig file=hugo >}}
|
||||
[params]
|
||||
disableAnchorCopy = false
|
||||
disableAnchorScrolling = false
|
||||
{{< /multiconfig >}}
|
||||
|
||||
## Copy Anchor Links to Clipboard
|
||||
|
||||
If you set `params.disableAnchorCopy=true`, no anchor link will be copied to the clipboard when the anchor icon is pressed.
|
||||
|
||||
## Scroll to Heading
|
||||
|
||||
If you set `params.disableAnchorScrolling=true`, the page will not scroll to the beginning of the heading when the anchor icon is clicked.
|
||||
|
|
@ -0,0 +1,6 @@
|
|||
+++
|
||||
description = "How to configure heading anchors"
|
||||
title = "Headings"
|
||||
weight = 3
|
||||
+++
|
||||
{{< piratify >}}
|
||||
|
|
@ -0,0 +1,27 @@
|
|||
+++
|
||||
description = "Learn about the hiddes pages feature"
|
||||
title = "Hidden Pages"
|
||||
weight = 5
|
||||
+++
|
||||
|
||||
The theme provides the concept of hidden pages.
|
||||
|
||||
While Hugo has the `draft` option to not create a page at all, a hidden page is created but not shown in the navigation. Just set `hidden=true` in your pages front matter. This can be useful if you want to have a page that is only accessible via a link.
|
||||
|
||||
If you access a hidden page via its URL, it will be revealed in the navigation menu.
|
||||
|
||||
Hidden pages can even contain hidden subpages.
|
||||
|
||||
By default, a hidden page is only hidden from a human user of your site. Crawlers may still see the URLs advertised in the sitemap, etc. You can avoid this by the following options
|
||||
|
||||
## Hide from Search
|
||||
|
||||
To hide hidden pages from search results of the search popup and dedicated search page, set `params.disableSearchHiddenPages=true`.
|
||||
|
||||
## Hide from Crawlers
|
||||
|
||||
To hide hidden pages from crawlers by removing links from the sitemap and rss feed, set `params.disableSearchHiddenPages=true`.
|
||||
|
||||
## Hide from Taxonomies
|
||||
|
||||
To hide hidden pages from showing up on the taxonomy and term pages, set `params.disableTagHiddenPages=true`. If this reduces term counters to zero, an empty but unlinked term page will be created anyhow.
|
||||
|
|
@ -0,0 +1,6 @@
|
|||
+++
|
||||
description = "Learn about the hiddes pages feature"
|
||||
title = "Hidden Pages"
|
||||
weight = 5
|
||||
+++
|
||||
{{< piratify >}}
|
||||
|
|
@ -0,0 +1,7 @@
|
|||
+++
|
||||
description = "Featured Images for social media"
|
||||
title = "Featured Images"
|
||||
weight = 2
|
||||
+++
|
||||
|
||||
The theme adds social media meta tags including feature images for the [Open Graph](https://gohugo.io/templates/internal/#open-graph) protocol and [Twitter Cards](https://gohugo.io/templates/internal/#twitter-cards) to your site. These are configured as mentioned in the linked Hugo docs.
|
||||
|
|
@ -0,0 +1,6 @@
|
|||
+++
|
||||
description = "Featured Images for social media"
|
||||
title = "Featured Images"
|
||||
weight = 2
|
||||
+++
|
||||
{{< piratify >}}
|
||||
|
|
@ -0,0 +1,30 @@
|
|||
+++
|
||||
description = "How to use and extend layouts"
|
||||
title = "Custom Layouts"
|
||||
weight = 4
|
||||
+++
|
||||
|
||||
The Relearn theme provides a few layouts for you to use. Namely these are `home`, `chapter` and `default`. All are accessible as so called [archetypes](content/layouts) for an author of your site.
|
||||
|
||||
You can manually use them by defining the `type` option accordingly in your page's front matter.
|
||||
|
||||
These layouts will use the general framework of the theme as defined in `themes/hugo-theme-learn/layouts/_default/baseof.html` but be modify the appearance of the content inside of the page.
|
||||
|
||||
### Defining Layouts
|
||||
|
||||
To provide your own custom layout, you need to choose a name, say `mylayout`. Create a file `layouts/mylayout/views/article.html` with the following content
|
||||
|
||||
````html {title="layouts/mylayout/views/article.html"}
|
||||
<article class="mylayout">
|
||||
<header class="headline">
|
||||
{{ partial "content-header.html" . }}
|
||||
</header>
|
||||
{{ partial "heading-pre.html" . }}{{ partial "heading.html" . }}{{ partial "heading-post.html" . }}
|
||||
{{ partial "article-content.html" . }}
|
||||
<footer class="footline">
|
||||
{{ partial "content-footer.html" . }}
|
||||
</footer>
|
||||
</article>
|
||||
````
|
||||
|
||||
In this file, you can do what ever you want. Usually, you want to at least set some `class` identifier to add custom CSS styles for your layout and call the partial `article-content.html` to render the content of your page.
|
||||
|
|
@ -0,0 +1,6 @@
|
|||
+++
|
||||
description = "How to use and extend layouts"
|
||||
title = "Custom Layouts"
|
||||
weight = 4
|
||||
+++
|
||||
{{< piratify >}}
|
||||
23
exampleSite/content/configuration/content/width/_index.en.md
Normal file
23
exampleSite/content/configuration/content/width/_index.en.md
Normal file
|
|
@ -0,0 +1,23 @@
|
|||
+++
|
||||
description = "Changing the width the content area"
|
||||
title = "Width"
|
||||
weight = 1
|
||||
+++
|
||||
|
||||
The theme reacts to browser resizes and adjusts the menu and content width accordingly.
|
||||
|
||||
If you dislike the default behavior, you can link to a CSS stylesheet or change it in your `layouts/partials/custom-header.html`.
|
||||
|
||||
## Change the Main Area's Max Width
|
||||
|
||||
By default the main area width will only grow to a certain extent if more vertical screen space is available. This is done for readability purposes as long lines are usually harder to read.
|
||||
|
||||
If you are unhappy with the default, you can define the following CSS variable and set the value to your liking. If you want to use all available space, select a really big value like `1000rem`;
|
||||
|
||||
````html {title="layouts/partials/custom-header.html"}
|
||||
<style>
|
||||
:root {
|
||||
--MAIN-WIDTH-MAX: 80.25rem;
|
||||
}
|
||||
</style>
|
||||
````
|
||||
|
|
@ -0,0 +1,6 @@
|
|||
+++
|
||||
description = "Changing the width of menu and content area"
|
||||
title = "Page Width"
|
||||
weight = 1
|
||||
+++
|
||||
{{< piratify >}}
|
||||
|
|
@ -1,277 +0,0 @@
|
|||
+++
|
||||
title = "Customization"
|
||||
weight = 1
|
||||
+++
|
||||
|
||||
## Usage scenarios
|
||||
|
||||
The theme is usable in different scenarios, requiring the following mandatory settings in your `hugo.toml`. All settings not mentioned can be set to your liking.
|
||||
|
||||
### Public Web Server from Root
|
||||
|
||||
{{< multiconfig file=hugo >}}
|
||||
baseURL = "https://example.com/"
|
||||
{{< /multiconfig >}}
|
||||
|
||||
### Public Web Server from Subdirectory
|
||||
|
||||
{{< multiconfig file=hugo >}}
|
||||
baseURL = "https://example.com/mysite/"
|
||||
relativeURLs = false
|
||||
{{< /multiconfig >}}
|
||||
|
||||
### Private Web Server (LAN)
|
||||
|
||||
The same settings as with any of the public web server usage scenarios or
|
||||
|
||||
{{< multiconfig file=hugo >}}
|
||||
baseURL = "/"
|
||||
relativeURLs = true
|
||||
{{< /multiconfig >}}
|
||||
|
||||
### File System
|
||||
|
||||
{{< multiconfig file=hugo >}}
|
||||
baseURL = "/"
|
||||
relativeURLs = true
|
||||
{{< /multiconfig >}}
|
||||
|
||||
{{% notice warning %}}
|
||||
Using a `baseURL` with a subdirectory and `relativeURLs=true` are mutually exclusive due to the fact, that [Hugo does not apply the `baseURL` correctly](https://github.com/gohugoio/hugo/issues/12130).
|
||||
|
||||
If you need both, you have to generate your site twice but with different settings into separate directories.
|
||||
{{% /notice %}}
|
||||
|
||||
{{% notice note %}}
|
||||
Sublemental pages (like `sitemap.xml`, `rss.xml`) and generated social media links inside of your pages will always be generated with absolute URLs and will not work if you set `relativeURLs=true`.
|
||||
{{% /notice %}}
|
||||
|
||||
{{% notice info %}}
|
||||
If you are using `uglyURLs=false` (Hugo's default), the theme will append an additional `index.html` to all page links to make your site be servable from the file system. If you don't care about the file system and only serve your page via a web server you can generate the links without this:
|
||||
|
||||
{{< multiconfig file=hugo >}}
|
||||
[params]
|
||||
disableExplicitIndexURLs = true
|
||||
{{< /multiconfig >}}
|
||||
{{% /notice %}}
|
||||
|
||||
## Configure Search
|
||||
|
||||
The theme comes with three levels of search, all provided through the search form in the menu
|
||||
|
||||
- in-page search: a search term will be marked if found in the currently displayed page
|
||||
- search popup: a popup will open during typing if the term is found in other pages of your site
|
||||
- dedicated search page: you can access a dedicated search page by either clicking on the magnifier glass or by typing and pressing <kbd>ENTER</kbd>
|
||||
|
||||
Each level depends on the previous level to be enabled, eg. the dedicated search page is only available, if you have search popup and in-page search enabled.
|
||||
|
||||
By default all three levels are enabled. You can disable each level by the following settings in your `hugo.toml`:
|
||||
|
||||
- in-page search: `disableSearch=true`
|
||||
- search popup: `disableSearchIndex=true`
|
||||
- dedicated search page: `disableSearchPage=true`
|
||||
|
||||
By default the following files will be created, relative to each languages home page but can be overwritten:
|
||||
|
||||
- search popup: `searchindex.js`, configured by `searchIndexURL`
|
||||
- dedicated search page: `search/index.html`, configured by `searchPageURL`
|
||||
|
||||
{{% notice note %}}
|
||||
You only need to reconfigure the file / page URLs if you have own content at those URLs in your project. Eg. this can happen if you set `uglyURLs=true` in your `hugo.toml` and defining a Markdown file `content/search.md`.
|
||||
|
||||
To make sure, there is no duplicate content for any given URL of your project, run `hugo --printPathWarnings`.
|
||||
{{% /notice %}}
|
||||
|
||||
## Activate print support
|
||||
|
||||
You can activate print support to add the capability to print whole chapters or even the complete site. Just add the `print` output format to your home, section and page in your `hugo.toml` as seen below:
|
||||
|
||||
{{< multiconfig file=hugo >}}
|
||||
[outputs]
|
||||
home = ["html", "rss", "print"]
|
||||
section = ["html", "rss", "print"]
|
||||
page = ["html", "rss", "print"]
|
||||
{{< /multiconfig >}}
|
||||
|
||||
This will add a little printer icon in the top bar. It will switch the page to print preview when clicked. You can then send this page to the printer by using your browser's usual print functionality.
|
||||
|
||||
{{% notice note %}}
|
||||
The resulting URL will not be [configured ugly](https://gohugo.io/templates/output-formats/#configure-output-formats) in terms of [Hugo's URL handling](https://gohugo.io/content-management/urls/#ugly-urls) even if you've set `uglyURLs=true` in your `hugo.toml`. This is due to the fact that for one mime type only one suffix can be configured.
|
||||
|
||||
Nevertheless, if you're unhappy with the resulting URLs you can manually redefine `outputFormats.print` in your own `hugo.toml` to your liking.
|
||||
{{% /notice %}}
|
||||
|
||||
## Home Button Configuration
|
||||
|
||||
If the `disableLandingPageButton` option is set to `false`, a Home button will appear
|
||||
on the left menu. It is an alternative for clicking on the logo. To edit the
|
||||
appearance, you will have to configure the `landingPageName` for the defined languages:
|
||||
|
||||
{{< multiconfig file=hugo >}}
|
||||
[languages]
|
||||
[languages.en]
|
||||
[languages.en.params]
|
||||
landingPageName = "<i class='fa-fw fas fa-home'></i> Home"
|
||||
[languages.pir]
|
||||
[languages.pir.params]
|
||||
landingPageName = "<i class='fa-fw fas fa-home'></i> Arrr! Homme"
|
||||
{{< /multiconfig >}}
|
||||
|
||||
If this option is not configured for a specific language, they will get their default values:
|
||||
|
||||
{{< multiconfig >}}
|
||||
landingPageName = "<i class='fa-fw fas fa-home'></i> Home"
|
||||
{{< /multiconfig >}}
|
||||
|
||||
The home button is going to look like this:
|
||||
|
||||
|
||||
|
||||
## Social Media Meta Tags
|
||||
|
||||
You can add social media meta tags for the [Open Graph](https://gohugo.io/templates/internal/#open-graph) protocol and [Twitter Cards](https://gohugo.io/templates/internal/#twitter-cards) to your site. These are configured as mentioned in the Hugo docs.
|
||||
|
||||
## Change the Menu Width
|
||||
|
||||
The menu width adjusts automatically for different screen sizes.
|
||||
|
||||
| Name | Screen Width | Menu Width |
|
||||
| ---- | ------------- | ---------- |
|
||||
| S | < 48rem | 14.375rem |
|
||||
| M | 48rem - 60rem | 14.375rem |
|
||||
| L | >= 60rem | 18.75rem |
|
||||
|
||||
The values for the screen width breakpoints aren't configurable.
|
||||
|
||||
If you want to adjust the menu width you can define the following CSS variables in your `custom-header.html`. Note that `--MENU-WIDTH-S` applies to the menu flyout width in mobile mode for small screen sizes.
|
||||
|
||||
````css
|
||||
:root {
|
||||
--MENU-WIDTH-S: 14.375rem;
|
||||
--MENU-WIDTH-M: 14.375rem;
|
||||
--MENU-WIDTH-L: 18.75rem;
|
||||
}
|
||||
````
|
||||
|
||||
## Change the Main Area's Max Width
|
||||
|
||||
By default the main area width will only grow to a certain extent if more vertical screen space is available. This is done for readability purposes as long line are usually harder to read.
|
||||
|
||||
If you are unhappy with the default, you can define the following CSS variable in your `custom-header.html` and set the value to your liking. If you want to use all available space, select a really big value like `1000rem`;
|
||||
|
||||
````css
|
||||
:root {
|
||||
--MAIN-WIDTH-MAX: 80.25rem;
|
||||
}
|
||||
````
|
||||
|
||||
## Change Heading Anchor Behavior
|
||||
|
||||
Each heading may have an anchor link that is displayed when the heading is hovered.
|
||||
|
||||
The behavior what should happen if the anchor icon is clicked is configurable in your `hugo.toml`. By default all options are activated. If you deactivate all options, no link will be shown on hover.
|
||||
|
||||
{{< multiconfig file=hugo >}}
|
||||
[params]
|
||||
disableAnchorCopy = false
|
||||
disableAnchorScrolling = false
|
||||
{{< /multiconfig >}}
|
||||
|
||||
### `disableAnchorCopy`
|
||||
|
||||
If set to `true`, this disables the copying of anchor links to the clipboard.
|
||||
|
||||
### `disableAnchorScrolling`
|
||||
|
||||
If set to `true`, this disables the scrolling to the beginning of the heading when clicked.
|
||||
|
||||
## Own Shortcodes with JavaScript Dependencies
|
||||
|
||||
Certain shortcodes make use of additional dependencies like JavaScript and CSS files. The theme only loads these dependencies if the shortcode is used. To do so correctly the theme adds management code in various files.
|
||||
|
||||
You can you use this mechanism in your own shortcodes. Say you want to add a shortcode `myshortcode` that also requires the `jquery` JavaScript library.
|
||||
|
||||
1. Write the shortcode file `layouts/shortcodes/myshortcode.html` and add the following line
|
||||
|
||||
````go {title="layouts/shortcodes/myshortcode.html"}
|
||||
{{- .Page.Store.Set "hasMyShortcode" true }}
|
||||
````
|
||||
|
||||
1. Add the following snippet to your `hugo.toml`
|
||||
|
||||
{{< multiconfig file=hugo >}}
|
||||
[params.relearn.dependencies]
|
||||
[params.relearn.dependencies.myshortcode]
|
||||
name = "MyShortcode"
|
||||
{{< /multiconfig >}}
|
||||
|
||||
1. Add the dependency loader file `layouts/partials/dependencies/myshortcode.html`. The loader file will be called from multiple locations inside of the theme with the parameter `page` containing the current [page](https://gohugo.io/methods/page/) variable and `location` with one of the currently defined locations
|
||||
|
||||
* `header`: if called at the end of the HTML `head` element
|
||||
* `footer`: if called at the end of the HTML `body` element
|
||||
|
||||
````go {title="layouts/partials/dependencies/myshortcode.html"}
|
||||
{{- if eq .location "footer" }}
|
||||
<script src="https://www.unpkg.com/jquery/dist/jquery.js"></script>
|
||||
{{- end }}
|
||||
````
|
||||
|
||||
Character casing is relevant!
|
||||
|
||||
- the `name` setting in your `hugo.toml` must match the key (that needs to be prefixed with a `has`) you used for the store in your `layouts/shortcodes/myshortcode.html`.
|
||||
- the key on `params.relearn.dependencies` in your `hugo.toml` must match the base file name of your loader file.
|
||||
|
||||
See the `math`, `mermaid` and `openapi` shortcodes for examples.
|
||||
|
||||
{{% notice note %}}
|
||||
If you are really into customization of the theme and want to use the dependency loader for your own locations, you can do this by simply calling it from inside of your overriden partials
|
||||
|
||||
````go
|
||||
{{- partial "dependencies.gotmpl" (dict "page" . "location" "mylocation") }}
|
||||
````
|
||||
|
||||
{{% /notice %}}
|
||||
|
||||
## 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 `hugo.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.
|
||||
|
||||
## React to Variant Switches in JavaScript
|
||||
|
||||
Once a color variant is fully loaded, either initially or by switching the color variant manually with the variant selector, the custom event `themeVariantLoaded` on the `document` will be dispatched. You can add an event listener and react to changes.
|
||||
|
||||
````javascript
|
||||
document.addEventListener( 'themeVariantLoaded', function( e ){
|
||||
console.log( e.detail.variant ); // `relearn-light`
|
||||
});
|
||||
````
|
||||
|
||||
## Partials
|
||||
|
||||
The Relearn theme has been built to be as configurable as possible by defining multiple [partials](https://gohugo.io/templates/partials/)
|
||||
|
||||
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` directory of your local project. This partial will have the priority.
|
||||
|
||||
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.
|
||||
- `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.
|
||||
- `favicon.html`: the favicon
|
||||
- `heading.html`: side-wide configuration to change the pages title headings.
|
||||
- `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.
|
||||
- `logo.html`: the logo, on top left hand corner
|
||||
- `meta.html`: HTML meta tags, if you want to change default behavior
|
||||
- `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.
|
||||
- `menu-footer.html`: footer of the left menu
|
||||
- `toc.html`: table of contents
|
||||
- `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.
|
||||
|
|
@ -1,5 +0,0 @@
|
|||
+++
|
||||
title = "Customizat'n"
|
||||
weight = 1
|
||||
+++
|
||||
{{< piratify >}}
|
||||
|
|
@ -1,6 +0,0 @@
|
|||
+++
|
||||
categories = "theming"
|
||||
title = "Stylesheet Generrrat'r"
|
||||
weight = 6
|
||||
+++
|
||||
{{< piratify >}}
|
||||
|
|
@ -1,102 +0,0 @@
|
|||
+++
|
||||
linktitle = "Multilingual"
|
||||
title = "Multilingual and i18n"
|
||||
weight = 4
|
||||
+++
|
||||
|
||||
The Relearn theme is fully compatible with Hugo multilingual mode.
|
||||
|
||||
- Available languages: Arabic, Simplified Chinese, Traditional Chinese, Czech, Dutch, English, Finnish, French, German, Hindi, Hungarian, Indonesian, Italian, Japanese, Korean, Polish, Portuguese, Romanian, Russian, Spanish, Swahili, Turkish, Vietnamese. Feel free to contribute!
|
||||
- Full support for languages written right to left
|
||||
- Automatic menu generation from multilingual content
|
||||
- In-browser language switching
|
||||
|
||||
|
||||
|
||||
## Basic configuration
|
||||
|
||||
After learning [how Hugo handle multilingual websites](https://gohugo.io/content-management/multilingual), define your languages in your `hugo.toml` file.
|
||||
|
||||
For example with current English and Piratized English website.
|
||||
|
||||
{{% notice note %}}
|
||||
Make sure your default language is defined as the first one in the `[languages]` array, as the theme needs to make assumptions on it
|
||||
{{% /notice %}}
|
||||
|
||||
{{< multiconfig file=hugo >}}
|
||||
defaultContentLanguage = "en"
|
||||
|
||||
[languages]
|
||||
[languages.en]
|
||||
title = "Hugo Relearn Theme"
|
||||
weight = 1
|
||||
languageName = "English"
|
||||
|
||||
[languages.pir]
|
||||
title = "Cap'n Hugo Relearrrn Theme"
|
||||
weight = 2
|
||||
languageName = "Arrr! Pirrrates"
|
||||
{{< /multiconfig >}}
|
||||
|
||||
Then, for each new page, append the _id_ of the language to the file.
|
||||
|
||||
- Single file `my-page.md` is split in two files:
|
||||
- in English: `my-page.md`
|
||||
- in Piratized English: `my-page.pir.md`
|
||||
- Single file `_index.md` is split in two files:
|
||||
- in English: `_index.md`
|
||||
- in Piratized English: `_index.pir.md`
|
||||
|
||||
{{% notice info %}}
|
||||
Be aware that only translated pages are displayed in menu. It's not replaced with default language content.
|
||||
{{% /notice %}}
|
||||
|
||||
{{% notice tip %}}
|
||||
Use [slug](https://gohugo.io/content-management/multilingual/#translate-your-content) frontmatter parameter to translate urls too.
|
||||
{{% /notice %}}
|
||||
|
||||
## Search
|
||||
|
||||
In case each page's content is written in one single language only, the above configuration will already configure the site's search functionality correctly.
|
||||
|
||||
{{% notice warning %}}
|
||||
Although the theme supports a wide variety of supported languages, the site's search via the [Lunr](https://lunrjs.com) search library does not.
|
||||
You'll see error reports in your browsers console log for each unsupported language. Currently unsupported are:
|
||||
|
||||
- Czech
|
||||
- Indonesian
|
||||
- Polish
|
||||
- Swahili
|
||||
{{% /notice %}}
|
||||
|
||||
### Search with mixed language support
|
||||
|
||||
In case your page's content contains text in multiple languages (e.g. you are writing a Russian documentation for your english API), you can add those languages to your `hugo.toml` to broaden search.
|
||||
|
||||
{{< multiconfig file=hugo >}}
|
||||
[params]
|
||||
additionalContentLanguage = [ "en" ]
|
||||
{{< /multiconfig >}}
|
||||
|
||||
As this is an array, you can add multiple additional languages.
|
||||
|
||||
{{% notice note %}}
|
||||
Keep in mind that the language code required here, is the base language code. E.g. if you have additional content in `zh-CN`, you have to add just `zh` to this parameter.
|
||||
{{% /notice %}}
|
||||
|
||||
## Overwrite translation strings
|
||||
|
||||
Translations strings are used for common default values used in the theme (_Edit_ button, _Search placeholder_ and so on). Translations are available in English and Piratized English but you may use another language or want to override default values.
|
||||
|
||||
To override these values, create a new file in your local i18n directory `i18n/<idlanguage>.toml` and inspire yourself from the theme `themes/hugo-theme-relearn/i18n/en.toml`
|
||||
|
||||
## Disable language switching
|
||||
|
||||
Switching the language in the browser is a great feature, but for some reasons you may want to disable it.
|
||||
|
||||
Just set `disableLanguageSwitchingButton=true` in your `hugo.toml`
|
||||
|
||||
{{< multiconfig file=hugo >}}
|
||||
[params]
|
||||
disableLanguageSwitchingButton = true
|
||||
{{< /multiconfig >}}
|
||||
|
|
@ -1,6 +0,0 @@
|
|||
+++
|
||||
linktitle = "Multilingual"
|
||||
title = "Multilingual an' i18n"
|
||||
weight = 4
|
||||
+++
|
||||
{{< piratify >}}
|
||||
Binary file not shown.
|
Before Width: | Height: | Size: 74 KiB |
|
|
@ -1,5 +0,0 @@
|
|||
+++
|
||||
title = "Menu Shorrrtcuts"
|
||||
weight = 5
|
||||
+++
|
||||
{{< piratify >}}
|
||||
|
|
@ -0,0 +1,8 @@
|
|||
+++
|
||||
alwaysopen = false
|
||||
description = "Edit files for advanced configuration"
|
||||
title = "File Modifications"
|
||||
weight = 5
|
||||
+++
|
||||
|
||||
{{% children containerstyle="div" style="h2" description=true %}}
|
||||
|
|
@ -0,0 +1,7 @@
|
|||
+++
|
||||
alwaysopen = false
|
||||
description = "Edit files for advanced configuration"
|
||||
title = "File Modifications"
|
||||
weight = 5
|
||||
+++
|
||||
{{< piratify >}}
|
||||
|
|
@ -0,0 +1,68 @@
|
|||
+++
|
||||
description = "Add 3rd-party dependencies to your site"
|
||||
title = "Extending Client Code"
|
||||
weight = 3
|
||||
+++
|
||||
|
||||
## Adding JavaScript or Stylesheets Unconditionally
|
||||
|
||||
If you simply want to add additional JavaScript files or CSS stylesheets on every page of your site, you can do so by either adding them in your `layouts/partials/custom-header.html` or `layouts/partials/custom-footer.html` partial.
|
||||
|
||||
Sometimes this just bloats up your site when only in a few cases those files are really needed. See the [next section](#own-shortcodes-with-javascript-dependencies), on how to conditionally add those dependencies.
|
||||
|
||||
## Own Shortcodes with JavaScript Dependencies
|
||||
|
||||
Certain shortcodes make use of additional dependencies like JavaScript and CSS files. The theme only loads these dependencies if the shortcode is used. To do so correctly the theme adds management code in various files.
|
||||
|
||||
You can you use this mechanism in your own shortcodes. Say you want to add a shortcode `myshortcode` that also requires the `jquery` JavaScript library.
|
||||
|
||||
1. Write the shortcode file `layouts/shortcodes/myshortcode.html` and add the following line
|
||||
|
||||
````go {title="layouts/shortcodes/myshortcode.html"}
|
||||
{{- .Page.Store.Set "hasMyShortcode" true }}
|
||||
````
|
||||
|
||||
1. Add the following snippet to your `hugo.toml`
|
||||
|
||||
{{< multiconfig file=hugo >}}
|
||||
[params.relearn.dependencies]
|
||||
[params.relearn.dependencies.myshortcode]
|
||||
name = "MyShortcode"
|
||||
{{< /multiconfig >}}
|
||||
|
||||
1. Add the dependency loader file `layouts/partials/dependencies/myshortcode.html`. The loader file will be called from multiple locations inside of the theme with the parameter `page` containing the current [page](https://gohugo.io/methods/page/) variable and `location` with one of the currently defined locations
|
||||
|
||||
* `header`: if called at the end of the HTML `head` element
|
||||
* `footer`: if called at the end of the HTML `body` element
|
||||
|
||||
````go {title="layouts/partials/dependencies/myshortcode.html"}
|
||||
{{- if eq .location "footer" }}
|
||||
<script src="https://www.unpkg.com/jquery/dist/jquery.js"></script>
|
||||
{{- end }}
|
||||
````
|
||||
|
||||
Character casing is relevant!
|
||||
|
||||
- the `name` setting in your `hugo.toml` must match the key (that needs to be prefixed with a `has`) you used for the store in your `layouts/shortcodes/myshortcode.html`.
|
||||
- the key on `params.relearn.dependencies` in your `hugo.toml` must match the base file name of your loader file.
|
||||
|
||||
See the `math`, `mermaid` and `openapi` shortcodes for examples.
|
||||
|
||||
{{% notice note %}}
|
||||
If you are really into customization of the theme and want to use the dependency loader for your own locations, you can do this by simply calling it from inside of your overriden partials
|
||||
|
||||
````go
|
||||
{{- partial "dependencies.gotmpl" (dict "page" . "location" "mylocation") }}
|
||||
````
|
||||
|
||||
{{% /notice %}}
|
||||
|
||||
## React to Variant Switches in JavaScript
|
||||
|
||||
Once a color variant is fully loaded, either initially or by switching the color variant manually with the variant selector, the custom event `themeVariantLoaded` on the `document` will be dispatched. You can add an event listener and react to changes.
|
||||
|
||||
````javascript
|
||||
document.addEventListener( 'themeVariantLoaded', function( e ){
|
||||
console.log( e.detail.variant ); // `relearn-light`
|
||||
});
|
||||
````
|
||||
|
|
@ -0,0 +1,6 @@
|
|||
+++
|
||||
description = "Add 3rd-party dependencies to your site"
|
||||
title = "Extending Client Code"
|
||||
weight = 3
|
||||
+++
|
||||
{{< piratify >}}
|
||||
|
|
@ -0,0 +1,24 @@
|
|||
+++
|
||||
description = "Adding Custom Output Formats"
|
||||
title = "Custom Output Formats"
|
||||
weight = 4
|
||||
+++
|
||||
|
||||
Besides the `print` output format supoorted by the theme, you can write your own [output formats](https://gohugo.io/templates/output-formats/).
|
||||
|
||||
## From Scratch
|
||||
|
||||
Suppoe you want to add a new output format `myformat` that outputs HTML. You want to ignore everything the theme provides and implement the whole format by yourself.
|
||||
|
||||
For that, add a file `layouts/_default/baseof.myformat.html` and implement everything from scratch.
|
||||
|
||||
## Using the Theme's Frame
|
||||
|
||||
If you want to keep the general framework and want to change only aspects of it, you can override some of following files
|
||||
|
||||
- `layouts/_default/views/article.html` - how one page content, including the title heading should be displayed
|
||||
- `layouts/_default/views/body.html` - how the body of the page should be composed; usually you either call `bodys/single.html` to show a single page's content or `bodys/tree.html` to show the page's content and the content of every subpages recursivley
|
||||
- `layouts/_default/views/menu.html` - how the sidebar menu should be assembled
|
||||
- `layouts/_default/views/storeOutputFormat.html` - this stores the name of the output format in a variable to later be used by the framework; this makes it possible to write CSS specific to your output format
|
||||
|
||||
For an live example, see the implementations for the shipped `print` output format, that overrides [`layouts/_default/views/body.print.html`](https://github.com/McShelby/hugo-theme-relearn/blob/main/layouts/_default/views/body.print.html), [`layouts/_default/views/menu.print.html`](https://github.com/McShelby/hugo-theme-relearn/blob/main/layouts/_default/views/menu.print.html) and [`layouts/_default/views/storeOutputFormat.print.html`](https://github.com/McShelby/hugo-theme-relearn/blob/main/layouts/_default/views/storeOutputFormat.print.html).
|
||||
|
|
@ -0,0 +1,6 @@
|
|||
+++
|
||||
description = "Adding Custom Output Formats"
|
||||
title = "Custom Output Formats"
|
||||
weight = 4
|
||||
+++
|
||||
{{< piratify >}}
|
||||
|
|
@ -0,0 +1,45 @@
|
|||
+++
|
||||
description = "Modifying partials to your needs"
|
||||
title = "Partials"
|
||||
weight = 2
|
||||
+++
|
||||
|
||||
## Customizable Partials
|
||||
|
||||
The Relearn theme has been built to be as configurable as possible by defining multiple partials that can be overridden by you to customize the theme.
|
||||
|
||||
As a rule of thumb, the less code a partial of the theme contains, the less likely you will have trouble updating the theme to a future version.
|
||||
|
||||
Following is a list of partials that are save to be overridden
|
||||
|
||||
- `layouts/partials/content.html`: the content of a page itself, can be overridden if you want to display page's meta data above or below the content
|
||||
|
||||
- `layouts/partials/content-header.html`: header above the title, has a default implementation to display the tags taxonomy but you can override it if you don't like it
|
||||
|
||||
- `layouts/partials/content-footer.html`: footer below the content, has a default implementation to display author information, modification dates and category taxonomy but you can override it if you don't like it
|
||||
|
||||
- `layouts/partials/custom-header.html`: custom headers in page; meant to be overridden when adding CSS imports; don't forget to include `style` HTML tag directive in your file
|
||||
|
||||
- `layouts/partials/custom-footer.html`: custom footer in page; meant to be overridden when adding JavaScript; don't forget to include `javascript` HTML tag directive in your file
|
||||
|
||||
- `layouts/partials/favicon.html`: the favicon; definitely meant to be overridden
|
||||
|
||||
- `layouts/partials/heading.html`: the pages title headings
|
||||
|
||||
- `layouts/partials/heading-pre.html`: prepend something to pages title headings; if you override this, it is your responsibility to take the page's `headingPre` setting into account
|
||||
|
||||
- `layouts/partials/heading-post.html`: append something to pages title headings; if you override this, it is your responsibility to take the page's `headingPost` setting into account
|
||||
|
||||
- `layouts/partials/logo.html`: the logo on the top left corner; definitely meant to be overridden
|
||||
|
||||
- `layouts/partials/menu-pre.html`: prepend something to a menu item; if you override this, it is your responsibility to take the page's `menuPre` setting into account
|
||||
|
||||
- `layouts/partials/menu-post.html`: append something to a menu item; if you override this, it is your responsibility to take the page's `menuPost` setting into account
|
||||
|
||||
- `layouts/partials/menu-footer.html`: footer of the left menu
|
||||
|
||||
You may override other partials from the directory `themes/hugo-relearn-themes/` besides `themes/hugo-relearn-themes/layouts/partials/_relearn`. Just be aware that this may become a hassle with future updates.
|
||||
|
||||
## Usable Partials
|
||||
|
||||
You may use other partials from the directory `themes/hugo-relearn-themes/` besides the ones contained in `themes/hugo-relearn-themes/layouts/partials/_relearn`. Just be aware that using other partials besides [the ones mentioned above](#customizable-partials) may become a hassle with future updates.
|
||||
|
|
@ -0,0 +1,6 @@
|
|||
+++
|
||||
description = "Modifying partials to your needs"
|
||||
title = "Partials"
|
||||
weight = 2
|
||||
+++
|
||||
{{< piratify >}}
|
||||
|
|
@ -1,13 +1,14 @@
|
|||
+++
|
||||
description = "How to extend the topbar"
|
||||
title = "Topbar Modification"
|
||||
weight = 3
|
||||
weight = 1
|
||||
+++
|
||||
|
||||
The theme comes with a reasonably configured topbar.
|
||||
The theme comes with a reasonably configured topbar. You can learn how to [configure the defaults in this section](configuration/appearance/topbar).
|
||||
|
||||
|
||||
|
||||
Nevertheless, your requirements may differ from this configuration. Luckily the theme got you covered as the themebar, its buttons and the functionality behind these buttons is fully configurable by you.
|
||||
Nevertheless, your requirements may differ from this configuration. Luckily the theme got you covered as the topbar, its buttons and the functionality behind these buttons is fully configurable by you.
|
||||
|
||||
{{% notice tip %}}
|
||||
All mentioned file names below can be clicked and show you the implementation for a better understanding.
|
||||
|
|
@ -32,7 +33,7 @@ The theme ships with the following predefined buttons (from left to right in the
|
|||
- {{% button style="transparent" icon="bars" %}}{{% /button %}} [**sidebar**](https://github.com/McShelby/hugo-theme-relearn/blob/main/layouts/partials/topbar/button/sidebar.html): opens the sidebar flyout if in mobile layout
|
||||
- {{% button style="transparent" icon="list-alt" %}}{{% /button %}} [**toc**](https://github.com/McShelby/hugo-theme-relearn/blob/main/layouts/partials/topbar/button/toc.html): opens the table of contents in an overlay
|
||||
- {{% button style="transparent" icon="pen" %}}{{% /button %}} [**edit**](https://github.com/McShelby/hugo-theme-relearn/blob/main/layouts/partials/topbar/button/edit.html): browses to the editable page if the `editURL` [parameter is set](configuration/options)
|
||||
- {{% button style="transparent" icon="print" %}}{{% /button %}} [**print**](https://github.com/McShelby/hugo-theme-relearn/blob/main/layouts/partials/topbar/button/print.html): browses to the chapters printable page if [print support](configuration/customization#activate-print-support) was activated
|
||||
- {{% button style="transparent" icon="print" %}}{{% /button %}} [**print**](https://github.com/McShelby/hugo-theme-relearn/blob/main/layouts/partials/topbar/button/print.html): browses to the chapters printable page if [print support](configuration/appearance/topbar/#print-support) was activated
|
||||
- {{% button style="transparent" icon="chevron-left" %}}{{% /button %}} [**prev**](https://github.com/McShelby/hugo-theme-relearn/blob/main/layouts/partials/topbar/button/prev.html): browses to the previous page if there is one
|
||||
- {{% button style="transparent" icon="chevron-right" %}}{{% /button %}} [**next**](https://github.com/McShelby/hugo-theme-relearn/blob/main/layouts/partials/topbar/button/next.html): browses to the next page if there is one
|
||||
- {{% button style="transparent" icon="ellipsis-v" %}}{{% /button %}} [**more**](https://github.com/McShelby/hugo-theme-relearn/blob/main/layouts/partials/topbar/button/more.html): opens the overlay for the _more_ area
|
||||
|
|
@ -1,5 +1,6 @@
|
|||
+++
|
||||
description = "How to extend the topbar"
|
||||
title = "Topbarrr Modificat'n"
|
||||
weight = 3
|
||||
weight = 1
|
||||
+++
|
||||
{{< piratify >}}
|
||||
|
Before Width: | Height: | Size: 12 KiB After Width: | Height: | Size: 12 KiB |
|
Before Width: | Height: | Size: 7.7 KiB After Width: | Height: | Size: 7.7 KiB |
|
|
@ -1,17 +1,18 @@
|
|||
+++
|
||||
tags = ["config"]
|
||||
description = "All configuration options of the Relearn theme"
|
||||
tags = ["reference"]
|
||||
title = "Options Reference"
|
||||
weight = 7
|
||||
weight = 6
|
||||
+++
|
||||
|
||||
On top of [Hugo's global configuration options](https://gohugo.io/overview/configuration/), the Relearn theme lets you define further options unique to the theme in your `hugo.toml`.
|
||||
On top of [Hugo's global configuration options](https://gohugo.io/overview/configuration/), you can set further options unique to the theme in your `hugo.toml`.
|
||||
|
||||
Note that some of these options are explained in detail in other sections of this documentation.
|
||||
This is the complete list of theme options. Note that all these options are explained in detail in other sections of this documentation.
|
||||
|
||||
The values shown here, reflect the options active in this documentation. The default values can be taken from the [annotated example](#annotated-config-options) below.
|
||||
|
||||
## All config options
|
||||
|
||||
The values reflect the options active in this documentation. The defaults can be taken from the [annotated example](#annotated-config-options) below.
|
||||
|
||||
{{< multiconfig file=hugo >}}
|
||||
[params]
|
||||
{{% include "config/_default/params.toml" %}}
|
||||
|
|
|
|||
|
|
@ -1,6 +1,7 @@
|
|||
+++
|
||||
tags = ["config"]
|
||||
description = "All configuration options of the Relearn theme"
|
||||
tags = ["reference"]
|
||||
title = "Options Reference"
|
||||
weight = 7
|
||||
weight = 6
|
||||
+++
|
||||
{{< piratify >}}
|
||||
8
exampleSite/content/configuration/sidebar/_index.en.md
Normal file
8
exampleSite/content/configuration/sidebar/_index.en.md
Normal file
|
|
@ -0,0 +1,8 @@
|
|||
+++
|
||||
alwaysopen = false
|
||||
description = "Configure the sidebar"
|
||||
title = "Sidebar"
|
||||
weight = 3
|
||||
+++
|
||||
|
||||
{{% children containerstyle="div" style="h2" description=true %}}
|
||||
7
exampleSite/content/configuration/sidebar/_index.pir.md
Normal file
7
exampleSite/content/configuration/sidebar/_index.pir.md
Normal file
|
|
@ -0,0 +1,7 @@
|
|||
+++
|
||||
alwaysopen = false
|
||||
description = "Configure the sidebar"
|
||||
title = "Sidebar"
|
||||
weight = 3
|
||||
+++
|
||||
{{< piratify >}}
|
||||
|
|
@ -0,0 +1,40 @@
|
|||
+++
|
||||
description = "Configure the header and footer of the sidebar"
|
||||
title = "Header & Footer"
|
||||
weight = 2
|
||||
+++
|
||||
|
||||
## Home Button Configuration
|
||||
|
||||
If `disableLandingPageButton=true`, the Home button will be hidden on the left menu.
|
||||
|
||||
If you display the Home button, it is an alternative for clicking on the logo. To edit its logo or text, you will have to configure the `landingPageName` for the defined languages
|
||||
|
||||
{{< multiconfig file=hugo >}}
|
||||
[languages]
|
||||
[languages.en]
|
||||
[languages.en.params]
|
||||
landingPageName = "<i class='fa-fw fas fa-home'></i> Home"
|
||||
[languages.pir]
|
||||
[languages.pir.params]
|
||||
landingPageName = "<i class='fa-fw fas fa-home'></i> Arrr! Homme"
|
||||
{{< /multiconfig >}}
|
||||
|
||||
If this option is not configured for a specific language, they will get their default values of
|
||||
|
||||
{{< multiconfig >}}
|
||||
[params]
|
||||
landingPageName = "<i class='fa-fw fas fa-home'></i> Home"
|
||||
{{< /multiconfig >}}
|
||||
|
||||
The home button is going to look like this:
|
||||
|
||||
|
||||
|
||||
## History
|
||||
|
||||
Set `params.showVisitedLinks=true` to show checkmarks for visited pages of the main menu. This also causes the display of the `Clear History` entry in the lower part of the menu to remove all checkmarks. The checkmarks will also been removed if you regenerate your site as the used ids are not stable.
|
||||
|
||||
## Footer
|
||||
|
||||
You can change the menu footer by overriding the partial `layouts/partials/menu-footer.html`. See the [Partials section](configuration/modifications/partials) for more customization options.
|
||||
|
|
@ -0,0 +1,6 @@
|
|||
+++
|
||||
description = "Configure the header and footer of the sidebar"
|
||||
title = "Header & Footer"
|
||||
weight = 2
|
||||
+++
|
||||
{{< piratify >}}
|
||||
|
Before Width: | Height: | Size: 7.4 KiB After Width: | Height: | Size: 7.4 KiB |
|
|
@ -0,0 +1,35 @@
|
|||
+++
|
||||
description = "Default behavior of the navigation menu"
|
||||
title = "Navigation Menu"
|
||||
weight = 4
|
||||
+++
|
||||
|
||||
The navigation menu is automatically generated from [your content files](content/organization).
|
||||
|
||||
You can define certain settings globally in your `hugo.toml`. These are inherited to all pages as their default values but can be overwritten in their front matter.
|
||||
|
||||
## Expand State of Nested Sections
|
||||
|
||||
Use `params.alwaysopen` to set the initial expand state of submenus. This controls whether submenus will be expanded (`true`), or collapsed (`false`) in the menu. If not set, the first menu level is set to false, all others levels are set to true.
|
||||
|
||||
This can be overridden individually for each page in its front matter.
|
||||
|
||||
If the _displayed_ page has submenus, they will always been displayed expanded regardless of this option.
|
||||
|
||||
## Expander for Nested Sections
|
||||
|
||||
Set `params.collapsibleMenu=true` to show an expander for submenus. If set to `true`, submenus in the sidebar will be displayed as collapsible trees and a clickable expander is set in front of those entries.
|
||||
|
||||
> [!WARNING]
|
||||
> Setting this option to `true` may cause your build to significantly slow down and degrade built performance, depending on your machine and the amount of pages.
|
||||
>
|
||||
> We've observed this with 1000+ pages with a built time of around 2min. With 5000+ pages it was unbearable slow taking the built half an hour to complete.
|
||||
>
|
||||
> This is because for each page being added, every other pages needs to be visited once. This results in quadratic built time. In an already slow environment, adding just one single new page may result in unbearable built times afterwards.
|
||||
>
|
||||
|
||||
## Default Sort By
|
||||
|
||||
Set `params.ordersectionsby` to set the sorting criterium of navigation menus. Defaults to `weight`. Menus can be ordered by `weight`, `title`, `linktitle`, `modifieddate`, `expirydate`, `publishdate`, `date`, `length` or `default` (adhering to Hugo's default sort order).
|
||||
|
||||
This can be overridden individually for each page in its front matter.
|
||||
|
|
@ -0,0 +1,6 @@
|
|||
+++
|
||||
description = "Default behavior of the navigation menu"
|
||||
title = "Navigation Menu"
|
||||
weight = 4
|
||||
+++
|
||||
{{< piratify >}}
|
||||
|
|
@ -0,0 +1,61 @@
|
|||
+++
|
||||
description = "Configure search and the search form"
|
||||
title = "Search"
|
||||
weight = 3
|
||||
+++
|
||||
|
||||
## Configure Search
|
||||
|
||||
The theme comes with three levels of search, all provided through the search form in the menu
|
||||
|
||||
- in-page search: a search term will be marked if found in the currently displayed page
|
||||
- search popup: a popup will open during typing if the term is found in other pages of your site
|
||||
- dedicated search page: you can access a dedicated search page by either clicking on the magnifier glass or by typing and pressing <kbd>ENTER</kbd>
|
||||
|
||||
Each level depends on the previous level to be enabled, eg. the dedicated search page is only available, if you have search popup and in-page search enabled. If no search level is configured, the search form will not be displayed.
|
||||
|
||||
By default all three levels are enabled. You can disable each level by the following settings in your `hugo.toml`:
|
||||
|
||||
- in-page search: `disableSearch=true`
|
||||
- search popup: `disableSearchIndex=true`
|
||||
- dedicated search page: `disableSearchPage=true`
|
||||
|
||||
By default the following files will be created, relative to each languages home page but can be overwritten:
|
||||
|
||||
- search popup: `searchindex.js`, configured by `searchIndexURL`
|
||||
- dedicated search page: `search/index.html`, configured by `searchPageURL`
|
||||
|
||||
{{% notice note %}}
|
||||
You only need to reconfigure the file / page URLs if you have own content at those URLs in your project. Eg. this can happen if you set `uglyURLs=true` in your `hugo.toml` and defining a Markdown file `content/search.md`.
|
||||
|
||||
To make sure, there is no duplicate content for any given URL of your project, run `hugo --printPathWarnings`.
|
||||
{{% /notice %}}
|
||||
|
||||
## Supported Languages
|
||||
|
||||
In case each page's content is written in one single language only, the above configuration will already configure the site's search functionality correctly.
|
||||
|
||||
{{% notice warning %}}
|
||||
Although the theme supports a wide variety of supported languages, the site's search via the [Lunr](https://lunrjs.com) search library does not.
|
||||
You'll see error reports in your browsers console log for each unsupported language. Currently unsupported are:
|
||||
|
||||
- Czech
|
||||
- Indonesian
|
||||
- Polish
|
||||
- Swahili
|
||||
{{% /notice %}}
|
||||
|
||||
### Search with Mixed Language Support
|
||||
|
||||
In case your page's content contains text in multiple languages (e.g. you are writing a Russian documentation for your english API), you can add those languages to your `hugo.toml` to broaden search.
|
||||
|
||||
{{< multiconfig file=hugo >}}
|
||||
[params]
|
||||
additionalContentLanguage = [ "en" ]
|
||||
{{< /multiconfig >}}
|
||||
|
||||
As this is an array, you can add multiple additional languages.
|
||||
|
||||
{{% notice note %}}
|
||||
Keep in mind that the language code required here, is the base language code. E.g. if you have additional content in `zh-CN`, you have to add just `zh` to this parameter.
|
||||
{{% /notice %}}
|
||||
|
|
@ -0,0 +1,6 @@
|
|||
+++
|
||||
description = "Configure search and the search form"
|
||||
title = "Search"
|
||||
weight = 3
|
||||
+++
|
||||
{{< piratify >}}
|
||||
|
|
@ -1,15 +1,27 @@
|
|||
+++
|
||||
title = "Menu Shortcuts"
|
||||
description = "Add additional shortcut links to the sidebar"
|
||||
title = "Shortcut Menu"
|
||||
weight = 5
|
||||
+++
|
||||
|
||||
You can define additional menu entries or shortcuts in the navigation menu without any link to content.
|
||||
The sidebar contains the navigation menu of your content files but you can also add additional menu entries or shortcuts below the navigation menu.
|
||||
|
||||
## Basic configuration
|
||||
You can read more about [Hugo's menu configuration](https://gohugo.io/content-management/menus/#define-in-site-configuration) in its documenation.
|
||||
|
||||
Edit the website configuration `hugo.toml` and add a `[[menu.shortcuts]]` entry for each link your want to add.
|
||||
## Title
|
||||
|
||||
Example from the current website:
|
||||
By default, the shortcut menu is preceded by a title. This title can be disabled by setting `params.disableShortcutsTitle=true`. However, if you want to keep the title but change its value, it can be overridden by changing your local i18n translation string configuration.
|
||||
|
||||
For example, in your local `i18n/en.toml` file, add the following content
|
||||
|
||||
````toml {title="en.toml"}
|
||||
[Shortcuts-Title]
|
||||
other = "Other Great Stuff"
|
||||
````
|
||||
|
||||
## Single Language Example
|
||||
|
||||
Edit the `hugo.toml` and add a `[[menu.shortcuts]]` entry for each link your want to add.
|
||||
|
||||
{{< multiconfig file=hugo >}}
|
||||
[[menu.shortcuts]]
|
||||
|
|
@ -40,24 +52,10 @@ url = "tags/"
|
|||
weight = 40
|
||||
{{< /multiconfig >}}
|
||||
|
||||
By default, shortcuts are preceded by a title. This title can be disabled by setting `disableShortcutsTitle=true`.
|
||||
However, if you want to keep the title but change its value, it can be overridden by changing your local i18n translation string configuration.
|
||||
|
||||
For example, in your local `i18n/en.toml` file, add the following content
|
||||
|
||||
````toml {title="en.toml"}
|
||||
[Shortcuts-Title]
|
||||
other = "<Your value>"
|
||||
````
|
||||
|
||||
Read more about [hugo menu](https://gohugo.io/extras/menus/) and [hugo i18n translation strings](https://gohugo.io/content-management/multilingual/#translation-of-strings)
|
||||
|
||||
## Configuration for Multilingual mode {#i18n}
|
||||
## Multilingual Example
|
||||
|
||||
When using a multilingual website, you can set different menus for each language. In the `hugo.toml` file, prefix your menu configuration by `Languages.<language-id>`.
|
||||
|
||||
Example from the current website:
|
||||
|
||||
{{< multiconfig file=hugo >}}
|
||||
[languages]
|
||||
[languages.en]
|
||||
|
|
@ -129,13 +127,11 @@ Example from the current website:
|
|||
weight = 40
|
||||
{{< /multiconfig >}}
|
||||
|
||||
Read more about [hugo menu](https://gohugo.io/extras/menus/) and [hugo multilingual menus](https://gohugo.io/content-management/multilingual/#menus)
|
||||
## Shortcuts to Pages Inside of your Project
|
||||
|
||||
## Shortcuts to pages inside of your project
|
||||
If you have shortcuts to pages inside of your project and you don't want them to show up in your navigation menu, you have two choices:
|
||||
|
||||
If you have shortcuts to pages inside of your project and you don't want them to show up in page menu section, you have two choices:
|
||||
|
||||
1. Make the page file for the shortcut a [headless branch bundle](https://gohugo.io/content-management/page-bundles/#headless-bundle) (contained in its own subdirectory and called `_index.md`) and add the following frontmatter configuration to the file (see exampleSite's `content/showcase/_index.en.md`). This causes its content to **not** be ontained in the sitemap.
|
||||
1. Make the page file for the shortcut a [headless branch bundle](https://gohugo.io/content-management/page-bundles/#headless-bundle) (contained in its own subdirectory and called `_index.md`) and add the following frontmatter configuration to the file (see exampleSite's `content/showcase/_index.en.md`). This causes its content to **not** be contained in the sitemap.
|
||||
|
||||
{{< multiconfig fm=true >}}
|
||||
title = "Showcase"
|
||||
|
|
@ -0,0 +1,6 @@
|
|||
+++
|
||||
description = "Add additional shortcut links to the sidebar"
|
||||
title = "Shorrrtcut Menu"
|
||||
weight = 5
|
||||
+++
|
||||
{{< piratify >}}
|
||||
33
exampleSite/content/configuration/sidebar/width/_index.en.md
Normal file
33
exampleSite/content/configuration/sidebar/width/_index.en.md
Normal file
|
|
@ -0,0 +1,33 @@
|
|||
+++
|
||||
description = "Changing the width of the sidebar"
|
||||
title = "Width"
|
||||
weight = 1
|
||||
+++
|
||||
|
||||
The theme reacts to browser resizes and adjusts the menu width accordingly.
|
||||
|
||||
If you dislike the default behavior, you can link to a CSS stylesheet or change it in your `layouts/partials/custom-header.html`.
|
||||
|
||||
## Change the Menu Width
|
||||
|
||||
The menu width adjusts automatically for different screen sizes for the following screen sizes:
|
||||
|
||||
| Name | Screen Width | Menu Width |
|
||||
| ---- | ------------- | ---------- |
|
||||
| S | < 48rem | 14.375rem |
|
||||
| M | 48rem - 60rem | 14.375rem |
|
||||
| L | >= 60rem | 18.75rem |
|
||||
|
||||
The values for the screen width breakpoints aren't configurable.
|
||||
|
||||
If you want to adjust the menu width you can define the following CSS variables. Note that `--MENU-WIDTH-S` applies to the menu flyout width in mobile mode for small screen sizes.
|
||||
|
||||
````html {title="layouts/partials/custom-header.html"}
|
||||
<style>
|
||||
:root {
|
||||
--MENU-WIDTH-S: 14.375rem;
|
||||
--MENU-WIDTH-M: 14.375rem;
|
||||
--MENU-WIDTH-L: 18.75rem;
|
||||
}
|
||||
</style>
|
||||
````
|
||||
|
|
@ -0,0 +1,6 @@
|
|||
+++
|
||||
description = "Changing the width of the sidebar"
|
||||
title = "Width"
|
||||
weight = 1
|
||||
+++
|
||||
{{< piratify >}}
|
||||
|
|
@ -0,0 +1,8 @@
|
|||
+++
|
||||
alwaysopen = false
|
||||
description = "Get yourself familiar with the general structure of your website"
|
||||
title = "Site Organization"
|
||||
weight = 1
|
||||
+++
|
||||
|
||||
{{% children containerstyle="div" style="h2" description=true %}}
|
||||
|
|
@ -0,0 +1,7 @@
|
|||
+++
|
||||
alwaysopen = false
|
||||
description = "Get yourself familiar with the general structure of your website"
|
||||
title = "Site Organization"
|
||||
weight = 1
|
||||
+++
|
||||
{{< piratify >}}
|
||||
|
|
@ -0,0 +1,58 @@
|
|||
+++
|
||||
description = "Options for specific deployment needs"
|
||||
title = "Deployment Scenarios"
|
||||
weight = 3
|
||||
+++
|
||||
|
||||
## Server Deployment
|
||||
|
||||
If you have no further requirements to your server deployment, you can skip the following page and choose of the broad range of available [options in a standard Hugo installation](https://gohugo.io/content-management/urls/).
|
||||
|
||||
If you have special requirements, the theme is capable of different scenarios, requiring the following mandatory settings in your `hugo.toml`. All settings not mentioned can be set to your liking.
|
||||
|
||||
### Public Web Server from Root
|
||||
|
||||
{{< multiconfig file=hugo >}}
|
||||
baseURL = "https://example.com/"
|
||||
{{< /multiconfig >}}
|
||||
|
||||
### Public Web Server from Subdirectory
|
||||
|
||||
{{< multiconfig file=hugo >}}
|
||||
baseURL = "https://example.com/mysite/"
|
||||
relativeURLs = false
|
||||
{{< /multiconfig >}}
|
||||
|
||||
### Private Web Server (LAN)
|
||||
|
||||
The same settings as with any of the public web server usage scenarios or
|
||||
|
||||
{{< multiconfig file=hugo >}}
|
||||
baseURL = "/"
|
||||
relativeURLs = true
|
||||
{{< /multiconfig >}}
|
||||
|
||||
### File System
|
||||
|
||||
{{< multiconfig file=hugo >}}
|
||||
baseURL = "/"
|
||||
relativeURLs = true
|
||||
{{< /multiconfig >}}
|
||||
|
||||
> [!WARNING]
|
||||
> Using a `baseURL` with a subdirectory and `relativeURLs=true` are mutually exclusive due to the fact, that [Hugo does not apply the `baseURL` correctly](https://github.com/gohugoio/hugo/issues/12130).
|
||||
>
|
||||
> If you need both, you have to generate your site twice but with different settings into separate directories.
|
||||
|
||||
{{% notice note %}}
|
||||
Sublemental pages (like `sitemap.xml`, `rss.xml`) and generated social media links inside of your pages will always be generated with absolute URLs and will not work if you set `relativeURLs=true`.
|
||||
{{% /notice %}}
|
||||
|
||||
## URL Management
|
||||
|
||||
If you are using `uglyURLs=false` (Hugo's default), the theme will append an additional `index.html` to all page links to make your site be servable from the file system. If you don't care about the file system and only serve your page via a web server you can generate the links without this:
|
||||
|
||||
{{< multiconfig file=hugo >}}
|
||||
[params]
|
||||
disableExplicitIndexURLs = true
|
||||
{{< /multiconfig >}}
|
||||
|
|
@ -0,0 +1,6 @@
|
|||
+++
|
||||
description = "Options for specific deployment needs"
|
||||
title = "Deployment Scenarios"
|
||||
weight = 3
|
||||
+++
|
||||
{{< piratify >}}
|
||||
|
|
@ -0,0 +1,92 @@
|
|||
+++
|
||||
description = "How to configure your site to be multilingual"
|
||||
title = "Multilingual"
|
||||
weight = 2
|
||||
+++
|
||||
|
||||
The Relearn theme is compatible with [Hugo's multilingual mode](https://gohugo.io/content-management/multilingual/).
|
||||
|
||||
The theme supports a wide set of languages, also supporting languages written right to left.
|
||||
|
||||
{{% expand "Supported languages" %}}
|
||||
- Arabic
|
||||
- Simplified Chinese
|
||||
- Traditional Chinese
|
||||
- Czech
|
||||
- Dutch
|
||||
- English
|
||||
- Finnish
|
||||
- French
|
||||
- German
|
||||
- Hindi
|
||||
- Hungarian
|
||||
- Indonesian
|
||||
- Italian
|
||||
- Japanese
|
||||
- Korean
|
||||
- Polish
|
||||
- Portuguese
|
||||
- Romanian
|
||||
- Russian
|
||||
- Spanish
|
||||
- Swahili
|
||||
- Turkish
|
||||
- Vietnamese
|
||||
{{% /expand %}}
|
||||
|
||||
## Basic Configuration
|
||||
|
||||
This example will show you, how to convert your site created in the [Getting Started](basics/quickstart) section to be multilingual using [translation by file name](https://gohugo.io/content-management/multilingual/#translation-by-file-name). You can also use [translation by content directory](https://gohugo.io/content-management/multilingual/#translation-by-content-directory), but this is out of the scope of this documentation.
|
||||
|
||||
Define your languages in your `hugo.toml` file. For example with English and Piratish English website.
|
||||
|
||||
{{< multiconfig file=hugo >}}
|
||||
defaultContentLanguage = "en"
|
||||
|
||||
[languages]
|
||||
[languages.en]
|
||||
title = "My Website"
|
||||
weight = 1
|
||||
languageName = "English"
|
||||
|
||||
[languages.pir]
|
||||
title = "Arrr, my Website"
|
||||
weight = 2
|
||||
languageName = "Pirrratish"
|
||||
{{< /multiconfig >}}
|
||||
|
||||
Then, for each new page, append the _id_ of the language to the file.
|
||||
|
||||
````plaintext
|
||||
├── content
|
||||
│ ├── basics
|
||||
│ │ ├── first-content
|
||||
| | | ├── _index.en.md
|
||||
| | | └── _index.pir.md
|
||||
│ │ ├── second-content
|
||||
| | | ├── _index.en.md
|
||||
| | | └── _index.pir.md
|
||||
│ │ ├── third-content.en.md
|
||||
│ │ └── third-content.pir.md
|
||||
│ ├── _index.en.md
|
||||
│ └── _index.pir.md
|
||||
├── themes
|
||||
│ └── hugo-theme-relearn
|
||||
│ └── ...
|
||||
└── hugo.toml
|
||||
````
|
||||
|
||||
## Configure Search
|
||||
|
||||
You may want to take a look into [search configuration](configuration/sidebar/search/). It has some additional options for multilingual websites.
|
||||
|
||||
## Disable Language Switching
|
||||
|
||||
Switching the language in the browser is a great feature, but for some reasons you may want to disable it.
|
||||
|
||||
Just set `params.disableLanguageSwitchingButton=true` in your `hugo.toml`
|
||||
|
||||
{{< multiconfig file=hugo >}}
|
||||
[params]
|
||||
disableLanguageSwitchingButton = true
|
||||
{{< /multiconfig >}}
|
||||
|
|
@ -0,0 +1,6 @@
|
|||
+++
|
||||
description = "How to configure your site to be multilingual"
|
||||
title = "Multilingual"
|
||||
weight = 2
|
||||
+++
|
||||
{{< piratify >}}
|
||||
|
|
@ -0,0 +1,42 @@
|
|||
+++
|
||||
description = "Your site's directory structure"
|
||||
title = "Basic Structure"
|
||||
weight = 1
|
||||
+++
|
||||
|
||||
## Structure
|
||||
|
||||
If you've followed the [Getting Started](basics/quickstart/) guide, you are resulting in a directory layout similar to this
|
||||
|
||||
````plaintext
|
||||
├── content
|
||||
│ ├── basics
|
||||
│ │ ├── first-content
|
||||
| | | └── _index.md
|
||||
│ │ ├── second-content
|
||||
| | | └── _index.md
|
||||
│ │ └── third-content.md
|
||||
│ └── _index.md
|
||||
├── themes
|
||||
│ └── hugo-theme-relearn
|
||||
│ └── ...
|
||||
└── hugo.toml
|
||||
````
|
||||
|
||||
Hugo creates a [union file system](https://gohugo.io/getting-started/directory-structure/#union-file-system), allowing you to mount two or more directories to the same location.
|
||||
|
||||
By default, it overlays your root directory on top of the directory of the Relearn theme. Files contained in your root directory will replace files in the Relearn theme's directory of the same location.
|
||||
|
||||
For example, the theme defines a file `themes/hugo-theme-relearn/layouts/partials/heading.html`, you can override it by defining your own file in `layouts/partials/heading.html`.
|
||||
|
||||
This makes it easy to customize the theme without having to edit files inside of the `themes` directory and so making it easier for you in the future to update the theme to a newer version.
|
||||
|
||||
> [!WARNING]
|
||||
> If you are editing files inside the `themes/hugo-theme-relearn` directory, you're doing it wrong.
|
||||
>
|
||||
> See the [above paragraphs](#structure).
|
||||
|
||||
> [!WARNING]
|
||||
> If you have cloned the theme repository and start editing files for your site in this clone, you're doing it wrong.
|
||||
>
|
||||
> Follow the [Getting Started](basics/quickstart/) guide.
|
||||
|
|
@ -0,0 +1,6 @@
|
|||
+++
|
||||
description = "Your site's directory structure"
|
||||
title = "Basic Structure"
|
||||
weight = 1
|
||||
+++
|
||||
{{< piratify >}}
|
||||
|
|
@ -69,17 +69,17 @@ editURL = ""
|
|||
# Menu
|
||||
# These options modify the menu appearance.
|
||||
|
||||
# Prefix for the title in main menu.
|
||||
# Prefix for the title in navigation menu.
|
||||
# Default: not set
|
||||
# The title of the page in the menu will be prefixed by this HTML content.
|
||||
menuPre = ""
|
||||
|
||||
# Suffix for the title in main menu.
|
||||
# Suffix for the title in navigation menu.
|
||||
# Default: not set
|
||||
# The title of the page in the menu will be suffixed by this HTML content.
|
||||
menuPost = ""
|
||||
|
||||
# The order of main menu submenus.
|
||||
# The order of navigation menu submenus.
|
||||
# Default: "weight"
|
||||
# Submenus can be ordered by "weight", "title", "linktitle", "modifieddate",
|
||||
# "expirydate", "publishdate", "date", "length" or "default" (adhering to
|
||||
|
|
@ -106,7 +106,7 @@ collapsibleMenu = true
|
|||
#++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
|
||||
# Hidden pages
|
||||
# These options configure how hidden pages are treated.
|
||||
# A page flagged as hidden, is only removed from the main menu if you are
|
||||
# A page flagged as hidden, is only removed from the navigation menu if you are
|
||||
# currently not on this page or the hidden page is not part of current page's
|
||||
# ancestors. For all other functionality in Hugo a hidden page behaves like any
|
||||
# other page if not otherwise configured.
|
||||
|
|
|
|||
|
|
@ -94,7 +94,7 @@ Default values for extension options can be set via params settings in your `hug
|
|||
|
||||
### Global Configuration File
|
||||
|
||||
You can configure the color style used for code blocks in your [color variants stylesheet](configuration/branding#syntax-highlighting) file.
|
||||
You can configure the color style used for code blocks in your [color variants stylesheet](configuration/appearance/branding#syntax-highlighting) file.
|
||||
|
||||
#### Recommended Settings
|
||||
|
||||
|
|
|
|||
|
|
@ -39,7 +39,7 @@ While the examples are using shortcodes with named parameter you are free to als
|
|||
{{% notice note %}}
|
||||
If you want to print out (or generate a PDF) from your OpenAPI documentation, don't initiate printing directly from the page because the elements are optimized for interactive usage in a browser.
|
||||
|
||||
Instead, open the [print preview](configuration/customization#activate-print-support) in your browser and initiate printing from that page. This page is optimized for reading and expands most of the available sections.
|
||||
Instead, open the [print preview](configuration/appearance/topbar/#print-support) in your browser and initiate printing from that page. This page is optimized for reading and expands most of the available sections.
|
||||
{{% /notice %}}
|
||||
|
||||
## Example
|
||||
|
|
|
|||
Loading…
Reference in a new issue