diff --git a/README.md b/README.md index a06bd327f9..38dec59f14 100644 --- a/README.md +++ b/README.md @@ -16,10 +16,10 @@ The Relearn theme is a fork of the great [Learn theme](https://github.com/matcor - Responsive design for mobile usage - Looks nice on paper (if it has to) - Usable offline, no external dependencies - - [Usable from your local file system via `file://` protocol](https://mcshelby.github.io/hugo-theme-relearn/basics/configuration#serving-your-page-from-the-filesystem) + - [Usable from your local file system via `file://` protocol](https://mcshelby.github.io/hugo-theme-relearn/basics/customization#serving-your-page-from-the-filesystem) - Support for the [VSCode Front Matter extension](https://github.com/estruyf/vscode-front-matter) for on-premise CMS capabilities - Support for Internet Explorer 11 - - [Support for Open Graph and Twitter Cards](https://mcshelby.github.io/hugo-theme-relearn/basics/configuration/#social-media-meta-tags) + - [Support for Open Graph and Twitter Cards](https://mcshelby.github.io/hugo-theme-relearn/basics/customization#social-media-meta-tags) - **Configurable theming and visuals** - [Configurable brand images](https://mcshelby.github.io/hugo-theme-relearn/basics/customization#change-the-logo) - [Automatic switch for light/dark variant dependend on your OS settings](https://mcshelby.github.io/hugo-theme-relearn/basics/customization#adjusting-to-os-settings) @@ -28,10 +28,10 @@ The Relearn theme is a fork of the great [Learn theme](https://github.com/matcor - [Stylesheet generator](https://mcshelby.github.io/hugo-theme-relearn/basics/generator) - [Configurable syntax highlighting](https://mcshelby.github.io/hugo-theme-relearn/shortcodes/highlight) - **Unique theme features** - - [Print whole chapters or even the complete site](https://mcshelby.github.io/hugo-theme-relearn/basics/configuration#activate-print-support) + - [Print whole chapters or even the complete site](https://mcshelby.github.io/hugo-theme-relearn/basics/customization#activate-print-support) - In page search - - [Site search](https://mcshelby.github.io/hugo-theme-relearn/basics/configuration#activate-search) - - [Dedicated search page](https://mcshelby.github.io/hugo-theme-relearn/basics/configuration#activate-dedicated-search-page) + - [Site search](https://mcshelby.github.io/hugo-theme-relearn/basics/customization#activate-search) + - [Dedicated search page](https://mcshelby.github.io/hugo-theme-relearn/basics/customization#activate-dedicated-search-page) - [Taxonomy support](https://mcshelby.github.io/hugo-theme-relearn/cont/taxonomy) - [Configurable topbar buttons](https://mcshelby.github.io/hugo-theme-relearn/basics/topbar) - [Unlimited nested menu items](https://mcshelby.github.io/hugo-theme-relearn/cont/pages) diff --git a/exampleSite/config/_default/params.toml b/exampleSite/config/_default/params.toml index edfadda378..93d1111d5f 100644 --- a/exampleSite/config/_default/params.toml +++ b/exampleSite/config/_default/params.toml @@ -75,7 +75,7 @@ themeVariant = [ # The color variants used for auto mode. # Default: [ "relearn-light", "relearn-dark" ], overwritten by the first -# two non-auto options from themeVariant if existant. +# two non-auto options of your `themeVariant` option if present. # The auto variant defines how your site adjusts to your selected OS settings # for light/dark mode. The first array element is the variant for light mode, # the second for dark mode. diff --git a/exampleSite/content/_index.en.md b/exampleSite/content/_index.en.md index f6d48898c9..183c5df7fa 100644 --- a/exampleSite/content/_index.en.md +++ b/exampleSite/content/_index.en.md @@ -19,10 +19,10 @@ The theme is a fork of the great [Learn theme](https://github.com/matcornic/hugo - Responsive design for mobile usage - Looks nice on paper (if it has to) - Usable offline, no external dependencies - - [Usable from your local file system via `file://` protocol](basics/configuration#serving-your-page-from-the-filesystem) + - [Usable from your local file system via `file://` protocol](basics/customization#serving-your-page-from-the-filesystem) - Support for the [VSCode Front Matter extension](https://github.com/estruyf/vscode-front-matter) for on-premise CMS capabilities - Support for Internet Explorer 11 - - [Support for Open Graph and Twitter Cards](basics/configuration/#social-media-meta-tags) + - [Support for Open Graph and Twitter Cards](basics/customization#social-media-meta-tags) - **Configurable theming and visuals** - [Configurable brand images](basics/customization#change-the-logo) - [Automatic switch for light/dark variant dependend on your OS settings](basics/customization#adjusting-to-os-settings) @@ -31,10 +31,10 @@ The theme is a fork of the great [Learn theme](https://github.com/matcornic/hugo - [Stylesheet generator](basics/generator/) - [Configurable syntax highlighting](shortcodes/highlight) - **Unique theme features** - - [Print whole chapters or even the complete site](basics/configuration#activate-print-support) + - [Print whole chapters or even the complete site](basics/customization#activate-print-support) - In page search - - [Site search](basics/configuration#activate-search) - - [Dedicated search page](basics/configuration#activate-dedicated-search-page) + - [Site search](basics/customization#activate-search) + - [Dedicated search page](basics/customization#activate-dedicated-search-page) - [Taxonomy support](cont/taxonomy) - [Configurable topbar buttons](basics/topbar) - [Unlimited nested menu items](cont/pages) diff --git a/exampleSite/content/basics/branding/_index.en.md b/exampleSite/content/basics/branding/_index.en.md new file mode 100644 index 0000000000..498fe8919a --- /dev/null +++ b/exampleSite/content/basics/branding/_index.en.md @@ -0,0 +1,130 @@ ++++ +categories = ["custom", "theming"] +title = "Branding" +weight = 24 ++++ + +The Relearn theme provides configuration options to change your 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 thru so called color variants. + +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 `config.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](basics/generator) may help you with this task. + +Once configured in your `config.toml`, you can select them with the variant selector at the bottom of the menu. + +## Change the Variant (Simple) {#theme-variant} + +### 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. + +````toml +[params] + themeVariant = "relearn-light" +```` + +{{% notice note %}} +Your theme variant file must reside in your site's `static/css` directory or in the theme's `static/css` directory and the file name must start with `theme-` and end wit `.css`. In the above example, the path of your theme file must be `static/css/theme-relearn-light.css`. + +If you want to make changes to a shipped color variant, create a copy in your site's `static/css` directory. Don't edit the file in the theme's directory! + +{{% /notice %}} + +### Multiple Variants + +You can also set multiple variants. In this case, the first variant is the default chosen on first view and a variant selector will be shown in the menu footer if the array contains more than one entry. + +````toml +[params] + themeVariant = [ "relearn-light", "relearn-dark" ] +```` + +{{% 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, logo and syntax highlightning 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 %}} + +## Adjust to OS Settings + +You can also cause the site to adjust to your OS settings for light/dark mode. Just set the `themeVariant` to `auto`. That's it. + +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. + +````toml +[params] + themeVariant = [ "auto", "red" ] +```` + +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. + +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. + +````toml +[params] + themeVariantAuto = [ "learn", "neon" ] +```` + +## 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 + +```` + +## 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_ folder, or you could paste a SVG definition! + +{{% notice note %}} +The size of the logo will adapt automatically. +{{% /notice %}} + +## Syntax highlightning + +If you want to switch the syntax highlighting theme together with your color variant, generate a syntax highlighting stylesheet and configure your installation [according to Hugo's documentation](https://gohugo.io/content-management/syntax-highlighting/). Then, `@import` the syntax highlightning stylesheet in your color variant stylesheet. + +For an example, take a look into `theme-relearn-light.css` and `config.toml` of the exampleSite. + +If you want to reconfigure just the syntax highlighting of an existing color variant, you need to copy the file to your site's directory and adjust it accordingly. + +## 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. + +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**. + +Again, in this case, the first variant is the default chosen on first view and a variant selector will be shown in the menu footer if the array contains more than one entry. + +````toml +[params] + themeVariant = [ "relearn-light", "relearn-dark" ] +```` + +you now write it that way: + +````toml +[params] + [[params.themeVariant]] + identifier = "relearn-light" + [[params.themeVariant]] + identifier = "relearn-dark" +```` + +The `identifier` option is mandatory and equivalent to the string in the first example. Further options can be configured, see the table below. + +### Parameter + +| Name | Default | Notes | +|-----------------------|-----------------|-------------| +| identifier | _<empty>_ | Must correspond to the name of a color variant either in your site's or the theme's directory in the form `static/css/theme-.css`. | +| name | see notes | The name to be displayed in the variant selector. If not set, the identifier is used in a human readable form. | diff --git a/exampleSite/content/basics/branding/_index.pir.md b/exampleSite/content/basics/branding/_index.pir.md new file mode 100644 index 0000000000..080f96ad0b --- /dev/null +++ b/exampleSite/content/basics/branding/_index.pir.md @@ -0,0 +1,6 @@ ++++ +categories = ["custom", "theming"] +title = "Brrrand'n" +weight = 24 ++++ +{{< piratify >}} \ No newline at end of file diff --git a/exampleSite/content/basics/configuration/_index.en.md b/exampleSite/content/basics/configuration/_index.en.md index 599a54526e..facee3a776 100644 --- a/exampleSite/content/basics/configuration/_index.en.md +++ b/exampleSite/content/basics/configuration/_index.en.md @@ -4,152 +4,11 @@ title = "Configuration" weight = 20 +++ -## Global site parameters +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 `config.toml`. The defaults are written in the comments of each option. -On top of [Hugo global configuration](https://gohugo.io/overview/configuration/), the Relearn theme lets you define the following parameters in your `config.toml` (here, values are default). - -Note that some of these parameters are explained in details in other sections of this documentation. +Note that some of these options are explained in detail in other sections of this documentation. ````toml {title="config.toml"} [params] {{% include "config/_default/params.toml" %}} ```` - -## Serving your page from a subfolder - -If your site is served from a subfolder, eg. `https://example.com/mysite/`, you have to set the following lines to your `config.toml` - -````toml -baseURL = "https://example.com/mysite/" -canonifyURLs = true -relativeURLs = true -```` - -Without `canonifyURLs=true` URLs in sublemental pages (like `sitemap.xml`, `rss.xml`) will be generated falsly while your HTML files will still work. See https://github.com/gohugoio/hugo/issues/5226. - -## Serving your page from the filesystem - -If you want your page served from the filesystem by using URLs starting with `file://` you'll need the following configuration in your `config.toml`: - -````toml -relativeURLs = true -```` - -The theme will append an additional `index.html` to all branch bundle links by default to make the page be servable from the file system. If you don't care about the file system and only serve your page via a webserver you can also generate the links without this change by adding this to your `config.toml` - -````toml -[params] - disableExplicitIndexURLs = true -```` - -{{% notice note %}} -If you want to use the search feature from the file system using an older installation of the theme make sure to change your outputformat for the homepage from the now deprecated `JSON` to `SEARCH` [as seen below](#activate-search). -{{% /notice %}} - -## Activate search - -If not already present, add the following lines in the same `config.toml` file. - -```toml -[outputs] - home = ["HTML", "RSS", "SEARCH"] -``` - -This will generate a search index file at the root of your public folder ready to be consumed by the Lunr search library. Note that the `SEARCH` outputformat was named `JSON` in previous releases but was implemented differently. Although `JSON` still works, it is now deprecated. - -### Activate dedicated search page - -You can add a dedicated search page for your page by adding the `SEARCHPAGE` outputformat to your home page by adding the following lines in your `config.toml` file. This will cause Hugo to generate a new file `http://example.com/mysite/search.html`. - -```toml -[outputs] - home = ["HTML", "RSS", "SEARCH", "SEARCHPAGE"] -``` - -You can access this page by either clicking on the magnifier glass or by typing some search term and pressing `ENTER` inside of the menu's search box . - -![Screenshot of the dedicated search page](search_page.png?&width=60pc) - -{{% notice note %}} -To have Hugo create the dedicated search page successfully, you must not generate the URL `http://example.com/mysite/search.html` from your own content. This can happen if you set `uglyURLs=true` in your `config.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 `config.toml` as seen below: - -```toml -[outputs] - home = ["HTML", "RSS", "PRINT", "SEARCH"] - section = ["HTML", "RSS", "PRINT"] - page = ["HTML", "RSS", "PRINT"] -``` - -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 `config.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 `config.toml` to your liking. -{{% /notice %}} - -## MathJax - -The MathJax configuration parameters can also be set on a specific page. In this case, the global parameter would be overwritten by the local one. See [Math](shortcodes/math) for additional documentation. - -### Example {#math-example} - -MathJax is globally disabled. By default it won't be loaded by any page. - -On page "Physics" you coded some JavaScript for a dynamic formulae. You can set the MathJax parameters locally to load mathJax on this page. - -You also can disable MathJax for specific pages while globally enabled. - -## Mermaid - -The Mermaid configuration parameters can also be set on a specific page. In this case, the global parameter would be overwritten by the local one. See [Mermaid](shortcodes/mermaid) for additional documentation. - -### Example {#mermaid-example} - -Mermaid is globally disabled. By default it won't be loaded by any page. - -On page "Architecture" you coded some JavaScript to dynamically generate a class diagram. You can set the Mermaid parameters locally to load mermaid on this page. - -You also can disable Mermaid for specific pages while globally enabled. - -## 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 two parameters for the defined languages: - -```toml -[languages] -[languages.en] -... -[languages.en.params] -landingPageName = " Home" -... -[languages.pir] -... -[languages.pir.params] -landingPageName = " Arrr! Homme" -... -``` - -If those params are not configured for a specific language, they will get their -default values: - -```toml -landingPageName = " Home" -``` - -The home button is going to look like this: - -![Default Home Button](home_button_defaults.png?width=18.75rem) - -## 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. diff --git a/exampleSite/content/basics/customization/_index.en.md b/exampleSite/content/basics/customization/_index.en.md index a14c26557d..fd4154f050 100644 --- a/exampleSite/content/basics/customization/_index.en.md +++ b/exampleSite/content/basics/customization/_index.en.md @@ -1,64 +1,122 @@ +++ -categories = ["custom", "theming"] title = "Customization" weight = 25 +++ -The Relearn theme has been built to be as configurable as possible by defining multiple [partials](https://gohugo.io/templates/partials/) +## Serving your page from a subfolder -In `themes/hugo-theme-relearn/layouts/partials/`, you will find all the partials defined for this theme. If you need to overwrite something, don't change the code directly. Instead [follow this page](https://gohugo.io/themes/customizing/). You'd create a new partial in the `layouts/partials` folder of your local project. This partial will have the priority. +If your site is served from a subfolder, eg. `https://example.com/mysite/`, you have to set the following lines to your `config.toml` -This theme defines the following partials : +````toml +baseURL = "https://example.com/mysite/" +canonifyURLs = true +relativeURLs = true +```` -- `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-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 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. +Without `canonifyURLs=true` URLs in sublemental pages (like `sitemap.xml`, `rss.xml`) will be generated falsly while your HTML files will still work. See https://github.com/gohugoio/hugo/issues/5226. -## Change the Logo +## Serving your page from the filesystem -Create a new file in `layouts/partials/` named `logo.html`. Then write any HTML you want. -You could use an `img` HTML tag and reference an image created under the _static_ folder, or you could paste a SVG definition! +If you want your page served from the filesystem by using URLs starting with `file://` you'll need the following configuration in your `config.toml`: + +````toml +relativeURLs = true +```` + +The theme will append an additional `index.html` to all page bundle links by default to make the page be servable from the file system. If you don't care about the file system and only serve your page via a webserver you can also generate the links without this change by adding this to your `config.toml` + +````toml +[params] + disableExplicitIndexURLs = true +```` {{% notice note %}} -The size of the logo will adapt automatically +If you want to use the search feature from the file system using an older installation of the theme make sure to change your outputformat for the homepage from the now deprecated `JSON` to `SEARCH` [as seen below](#activate-search). {{% /notice %}} -## Change the Favicon +## Activate search -If your favicon is a SVG, PNG or ICO, just drop off your image in your local `static/images/` folder and name it `favicon.svg`, `favicon.png` or `favicon.ico` respectively. +If not already present, add the following lines in your `config.toml` file. -Additionally, if you want your site to use light & dark theme favicons that follow the OS' (and in some cases, the browser's) color scheme, add the image files to your local `static/images/` folder and name them eg. `favicon-light.svg` and/or `favicon-dark.svg` respectively corresponding to your file format. In case one of the files is missing, the theme falls back to eg. `favicon.svg` for the missing file. All supplied favicons must be of the same file format. - -{{% notice warning %}} -IE and old browser versions do not support [media queries](https://caniuse.com/css-media-interaction), which are necessary for the light & dark theme favicon option. -If you have requirements to support IE and/or older browser versions, use one of the other options. -{{% /notice %}} - -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 in `layouts/partials/` named `favicon.html`. Then write something like this: - -```html - +```toml +[outputs] + home = ["HTML", "RSS", "SEARCH"] ``` +This will generate a search index file at the root of your public folder ready to be consumed by the Lunr search library. Note that the `SEARCH` outputformat was named `JSON` in previous releases but was implemented differently. Although `JSON` still works, it is now deprecated. + +### Activate dedicated search page + +You can add a dedicated search page for your page by adding the `SEARCHPAGE` outputformat to your home page by adding the following lines in your `config.toml` file. This will cause Hugo to generate a new file `http://example.com/mysite/search.html`. + +```toml +[outputs] + home = ["HTML", "RSS", "SEARCH", "SEARCHPAGE"] +``` + +You can access this page by either clicking on the magnifier glass or by typing some search term and pressing `ENTER` inside of the menu's search box . + +![Screenshot of the dedicated search page](search_page.png?&width=60pc) + +{{% notice note %}} +To have Hugo create the dedicated search page successfully, you must not generate the URL `http://example.com/mysite/search.html` from your own content. This can happen if you set `uglyURLs=true` in your `config.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 `config.toml` as seen below: + +```toml +[outputs] + home = ["HTML", "RSS", "PRINT", "SEARCH"] + section = ["HTML", "RSS", "PRINT"] + page = ["HTML", "RSS", "PRINT"] +``` + +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 `config.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 `config.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: + +```toml +[languages] +[languages.en] +... +[languages.en.params] +landingPageName = " Home" +... +[languages.pir] +... +[languages.pir.params] +landingPageName = " Arrr! Homme" +... +``` + +If this option is not configured for a specific language, they will get their default values: + +```toml +landingPageName = " Home" +``` + +The home button is going to look like this: + +![Default Home Button](home_button_defaults.png?width=18.75rem) + +## 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. @@ -80,81 +138,11 @@ If you want to adjust the menu width you can define the following CSS variables } ```` -## Change the Colors {#theme-variant} - -The Relearn theme lets you choose between some predefined color variants in light or dark mode, but feel free to add one yourself! - -You can preview the shipped variants by changing them in the variant selector at the bottom of the menu. - -### Single Variant - -Set the `themeVariant` value with the name of your theme file. That's it! - -```toml -[params] - themeVariant = "relearn-light" -``` - -In the above example your theme file has to be named `theme-relearn-light.css` - -### Multiple Variants - -You can also set multiple variants. In this case, the first variant is the default chosen on first view and a variant switch will be shown in the menu footer. - -```toml -[params] - # Change default color scheme with a variant one. - themeVariant = [ "relearn-light", "relearn-dark" ] -``` - -{{% notice tip %}} -If you want to switch the syntax highlighting theme together with your color variant, generate a syntax highlighting stylesheet and configure your installation [according to Hugo's documentation](https://gohugo.io/content-management/syntax-highlighting/), and `@import` this stylesheet in your color variant stylesheet. For an example, take a look into `theme-relearn-light.css` and `config.toml` of the exampleSite. -{{% /notice %}} - -### Adjust to OS Settings - -You can also cause the site to adjust to your OS settings for light/dark mode. Just set the `themeVariant` to `auto`. That's it. - -If you've set multiple variants, you can drop `auto` at any position, but usually it makes sense to set it in the first position and make it the default. - -```toml -[params] - themeVariant = [ "auto", "red" ] -``` - -If you don't configure anything else, the theme will use `relearn-light` for light mode and `relearn-dark` for dark mode. - -If you don't like that, you can set `themeVariantAuto`. The first element is the variant for light mode, the second for dark mode - -```toml -[params] - themeVariantAuto = [ "learn", "neon" ] -``` - -{{% notice note %}} -This is not supported for Internet Explorer 11, which still displays in the `relearn-light` variant. -{{% /notice %}} - - -### JavaScript - -Once a variant is fully loaded, either initially or by switching the 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` -}); -```` - -### Roll your Own - -If you are not happy with the shipped variants you can either copy and rename one of the shipped files from `themes/hugo-theme-relearn/static/css` to `static/css`, edit them afterwards to your liking in a text editor and configure the `themeVariant` parameter in your `config.toml` or just use the [interactive variant generator](basics/generator). - ## Own Shortcodes with JavaScript Dependencies -Certain shortcodes make use of additional JavaScript files. The theme only loads these dependencies if the shortcode is used. To do so correctly the theme adds management code in various files. To provide this behavior to the user and extending it for his own shortcodes this can be configured. +Certain shortcodes make use of additional JavaScript files. The theme only loads these dependencies if the shortcode is used. To do so correctly the theme adds management code in various files. -Say you want to add a shortcode `myshortcode` that also requires the `jquery` JavaScript library. +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 @@ -187,3 +175,42 @@ See the `math`, `mermaid` and `openapi` shortcodes for examples. ## Output Formats Certain parts of the theme can be changed for support of your own [output formats](https://gohugo.io/templates/output-formats/). Eg. if you define a new output format `PLAINTEXT` in your `config.toml`, you can add a file `layouts/partials/header.plaintext.html` to change the way, the page header should look like for that output format. + +## 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` folder 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-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 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. diff --git a/exampleSite/content/basics/customization/_index.pir.md b/exampleSite/content/basics/customization/_index.pir.md index 4ea0d12324..03cd9daa5b 100644 --- a/exampleSite/content/basics/customization/_index.pir.md +++ b/exampleSite/content/basics/customization/_index.pir.md @@ -1,5 +1,4 @@ +++ -categories = ["custom", "theming"] title = "Customizat'n" weight = 25 +++ diff --git a/exampleSite/content/basics/configuration/home_button_defaults.png b/exampleSite/content/basics/customization/home_button_defaults.png similarity index 100% rename from exampleSite/content/basics/configuration/home_button_defaults.png rename to exampleSite/content/basics/customization/home_button_defaults.png diff --git a/exampleSite/content/basics/configuration/search_page.png b/exampleSite/content/basics/customization/search_page.png similarity index 100% rename from exampleSite/content/basics/configuration/search_page.png rename to exampleSite/content/basics/customization/search_page.png diff --git a/exampleSite/content/basics/generator/_index.en.md b/exampleSite/content/basics/generator/_index.en.md index 9326cfe684..eebaec7cbc 100644 --- a/exampleSite/content/basics/generator/_index.en.md +++ b/exampleSite/content/basics/generator/_index.en.md @@ -8,7 +8,7 @@ weight = 26 This interactive tool may help you to generate your own color variant stylesheet. {{% expand "Show usage instructions" %}} -To get started, first select a color variant from the variant switch in the lower left sidebar that fits you best as a starting point. +To get started, first select a color variant from the variant selector in the lower left sidebar that fits you best as a starting point. The graph is interactive and reflect the current colors. You can click on any of the colored boxes to adjust the respective color. The graph **and the page** will update accordingly. @@ -16,7 +16,7 @@ The arrowed lines reflect how colors are inherited thru different parts of the t To better understand this select the `neon` variant and modify the different heading colors. There, colors for the heading `h2`, `h3` and `h4` are explicitly set. `h5` is not set and inherits its value from `h4`. `h6` is also not set and inherits its value from `h5`. -Once you've changed a color, the variant switch will show a "My custom variant" entry and your changes are stored in the browser. You can **browse to other pages** and even close the browser **without losing your changes**. +Once you've changed a color, the variant selector will show a "My custom variant" entry and your changes are stored in the browser. You can **browse to other pages** and even close the browser **without losing your changes**. Once you are satisfied, you can download the new variants file and copy it into your site's `static/css` directory. Afterwards you have to adjust the `themeVariant` parameter in your `config.toml` to your chosen file name. diff --git a/exampleSite/content/basics/migration/_index.en.md b/exampleSite/content/basics/migration/_index.en.md index 71af04c8e2..fd6634c8e5 100644 --- a/exampleSite/content/basics/migration/_index.en.md +++ b/exampleSite/content/basics/migration/_index.en.md @@ -46,7 +46,7 @@ This document shows you what's new in the latest release and flags it with one o author.name = "Hugo" ```` -- {{% badge style="note" title=" " %}}Change{{% /badge %}} Taxonomy [term pages](https://gohugo.io/content-management/taxonomies/#add-custom-metadata-to-a-taxonomy-or-term) now add the breadcrumb for each listed page. If this gets too crowded for you, you can turn the breadcrumbs off in your `config.toml` by adding `disableTermBreadcrumbs=true`. +- {{% badge style="note" title=" " %}}Change{{% /badge %}} Taxonomy [term pages](https://gohugo.io/content-management/taxonomies#add-custom-metadata-to-a-taxonomy-or-term) now add the breadcrumb for each listed page. If this gets too crowded for you, you can turn the breadcrumbs off in your `config.toml` by adding `disableTermBreadcrumbs=true`. - {{% badge style="info" icon="plus-circle" title=" " %}}New{{% /badge %}} Taxonomy and term pages are now allowed to contain content. This is added inbetween the title and the page list. @@ -54,7 +54,7 @@ This document shows you what's new in the latest release and flags it with one o - {{% 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](basics/customization#change-the-menu-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](basics/configuration#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](basics/customization#social-media-meta-tags). - {{% 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). @@ -113,7 +113,7 @@ This document shows you what's new in the latest release and flags it with one o ## 5.21.0 (2023-09-18) {#5210} -- {{% 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](basics/customization), 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](basics/customization#partials), you may want to review the styling (eg. margins/paddings) of your partial. - {{% 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](basics/topbar) for further details. @@ -158,7 +158,7 @@ This document shows you what's new in the latest release and flags it with one o - {{% 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](basics/customization/#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](basics/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 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). @@ -210,7 +210,7 @@ This document shows you what's new in the latest release and flags it with one o 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](basics/customization/#change-the-favicon) for light & dark mode. +- {{% badge style="info" icon="plus-circle" title=" " %}}New{{% /badge %}} The theme now optionally supports [separate favicons](basics/customization#change-the-favicon) for light & dark mode. --- @@ -300,7 +300,7 @@ This document shows you what's new in the latest release and flags it with one o 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](basics/customization/#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](basics/branding#adjust-to-os-settings). This is also the new default setting if you haven't configured `themeVariant` in your `config.toml`. @@ -402,7 +402,7 @@ This document shows you what's new in the latest release and flags it with one o - {{% 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 thru large number of results. - To activate this feature, you need to [configure it](basics/configuration#activate-dedicated-search-page) in your `config.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](basics/customization#activate-dedicated-search-page) in your `config.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. @@ -414,7 +414,7 @@ This document shows you what's new in the latest release and flags it with one o - {{% badge style="info" icon="plus-circle" title=" " %}}New{{% /badge %}} You are now able to turn off the generation of generator meta tags in your HTML head to hide the used versions of Hugo and this theme. - To [configure this](basics/configuration#global-site-parameters) in your `config.toml` make sure to set Hugo's `disableHugoGeneratorInject=true` **and** also `[params] disableGeneratorVersion=true`, otherwise Hugo will generate a meta tag into your home page automagically. + To [configure this](basics/configuration) in your `config.toml` make sure to set Hugo's `disableHugoGeneratorInject=true` **and** also `[params] disableGeneratorVersion=true`, otherwise Hugo will generate a meta tag into your home page automagically. - {{% badge style="info" icon="plus-circle" title=" " %}}New{{% /badge %}} Creation of your project gets a little bit faster with this release. @@ -438,7 +438,7 @@ This document shows you what's new in the latest release and flags it with one o ## 5.4.0 (2022-11-01) {#540} -- {{% badge style="note" title=" " %}}Change{{% /badge %}} [With the proper settings](basics/configuration#serving-your-page-from-the-filesystem) in your `config.toml` your page is now servable from the local file system using `file://` URLs. +- {{% badge style="note" title=" " %}}Change{{% /badge %}} [With the proper settings](basics/customization#serving-your-page-from-the-filesystem) in your `config.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 `config.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://`. @@ -458,7 +458,7 @@ This document shows you what's new in the latest release and flags it with one o - {{% badge style="info" icon="plus-circle" title=" " %}}New{{% /badge %}} [Image formatting](cont/markdown#add-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](basics/configuration#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](basics/customization#activate-print-support) to be configured. --- @@ -529,7 +529,7 @@ This document shows you what's new in the latest release and flags it with one o ## 4.1.0 (2022-06-12) {#410} -- {{% 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](cont/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](cont/i18n#search-with-mixed-language-support). --- @@ -561,7 +561,7 @@ This document shows you what's new in the latest release and flags it with one o - {{% badge style="info" icon="plus-circle" title=" " %}}New{{% /badge %}} If you prefer expandable/collapsible menu items, you can now set `collapsibleMenu=true` in your `config.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](basics/configuration#activate-print-support) in your `config.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](basics/customization#activate-print-support) in your `config.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. @@ -595,13 +595,13 @@ This document shows you what's new in the latest release and flags it with one o ## 3.0.0 (2022-02-22) {#300} -- {{% badge style="warning" title=" " %}}Breaking{{% /badge %}} We made changes to the menu footer. If you have your `menu-footer.html` [partial overridden](basics/customization), 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](basics/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. 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 `config.toml`. [If you still want to use the Learn color variant](basics/customization/#theme-variant), you have to explicitly set `themeVariant="learn"` in your `config.toml`. + This change will only affect your installation if you've not set the `themeVariant` parameter in your `config.toml`. [If you still want to use the Learn color variant](basics/branding#theme-variant), you have to explicitly set `themeVariant="learn"` in your `config.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. @@ -611,15 +611,15 @@ This document shows you what's new in the latest release and flags it with one o - {{% 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](basics/customization/#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](basics/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](basics/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 `config.toml`. In this case, the first variant is the default chosen on first view and a variant switch will be shown in the menu footer. See the [documentation](basics/customization/#multiple-variants) for configuration. +- {{% badge style="info" icon="plus-circle" title=" " %}}New{{% /badge %}} You can now configure multiple color variants in your `config.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](basics/branding#multiple-variants) for configuration. - Note, that the new variant switch will not work with Internet Explorer 11 as it does not support CSS variables. Therefore, the variant switcher will not be displayed with Internet Explorer 11. + 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. --- @@ -659,9 +659,9 @@ This document shows you what's new in the latest release and flags it with one o - {{% badge style="note" title=" " %}}Change{{% /badge %}} Although never officially documented, this release removes the font `Novacento`/`Novecento`. If you use it in an overwritten CSS please replace it with `Work Sans`. This change was necessary as Novacento did not provide all Latin special characters and lead to mixed styled character text eg. for Czech. -- {{% 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](basics/customization/#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](basics/customization#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 `config.toml`. For an example see [the example configuration](basics/configuration/#global-site-parameters). +- {{% 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 `config.toml`. For an example see [the example configuration](basics/configuration). --- @@ -673,7 +673,7 @@ This document shows you what's new in the latest release and flags it with one o ## 2.6.0 (2021-10-21) {#260} -- {{% badge style="info" icon="plus-circle" title=" " %}}New{{% /badge %}} Your site can now be served from a subfolder if you set `baseURL` and `canonifyURLs=true` in your `config.toml`. See the [documentation](basics/configuration/#a-word-on-running-your-site-in-a-subfolder) for a detailed example. +- {{% badge style="info" icon="plus-circle" title=" " %}}New{{% /badge %}} Your site can now be served from a subfolder if you set `baseURL` and `canonifyURLs=true` in your `config.toml`. See the [documentation](basics/customization#serving-your-page-from-a-subfolder) for a detailed example. --- @@ -689,7 +689,7 @@ This document shows you what's new in the latest release and flags it with one o - {{% badge style="info" icon="plus-circle" title=" " %}}New{{% /badge %}} Hidden pages are displayed by default in their according tags page. You can now turn off this behavior by setting `disableTagHiddenPages=true` in your `config.toml`. -- {{% badge style="info" icon="plus-circle" title=" " %}}New{{% /badge %}} You can define the expansion state of your menus for the whole site by setting the `alwaysopen` option in your `config.toml`. Please see further [documentation](cont/pages/#override-expand-state-rules-for-menu-entries) for possible values and default behavior. +- {{% badge style="info" icon="plus-circle" title=" " %}}New{{% /badge %}} You can define the expansion state of your menus for the whole site by setting the `alwaysopen` option in your `config.toml`. Please see further [documentation](cont/pages#override-expand-state-rules-for-menu-entries) for possible values and default behavior. - {{% badge style="info" icon="plus-circle" title=" " %}}New{{% /badge %}} New frontmatter `ordersectionsby` option to change immediate children sorting in menu and `children` shortcode. Possible values are `title` or `weight`. @@ -739,9 +739,9 @@ This document shows you what's new in the latest release and flags it with one o - {{% badge style="note" title=" " %}}Change{{% /badge %}} A page without a `title` will be treated as `hidden=true`. -- {{% 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](cont/pages/#override-expand-state-rules-for-menu-entries) for possible values and default behavior. +- {{% 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](cont/pages#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](basics/customization) 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](basics/customization#partials) for further reading. - {{% badge style="info" icon="plus-circle" title=" " %}}New{{% /badge %}} Shortcode [`children`](shortcodes/children) with new parameter `containerstyle`. diff --git a/exampleSite/content/basics/topbar/_index.en.md b/exampleSite/content/basics/topbar/_index.en.md index 9f255c0726..b1bd54e40a 100644 --- a/exampleSite/content/basics/topbar/_index.en.md +++ b/exampleSite/content/basics/topbar/_index.en.md @@ -31,8 +31,8 @@ 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](/basics/configuration/#global-site-parameters) -- {{% 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](/basics/configuration/#activate-print-support) was activated +- {{% 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](/basics/configuration) +- {{% 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](/basics/customization#activate-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 diff --git a/exampleSite/content/shortcodes/children/_index.en.md b/exampleSite/content/shortcodes/children/_index.en.md index f67e6bd283..358b92005a 100644 --- a/exampleSite/content/shortcodes/children/_index.en.md +++ b/exampleSite/content/shortcodes/children/_index.en.md @@ -41,7 +41,7 @@ While the examples are using shortcodes with named parameter you are free to als | **showhidden** | `false` | When `true`, child pages hidden from the menu will be displayed as well. | | **description** | `false` | When `true` shows a short text under each page in the list. When no description or summary exists for the page, the first 70 words of the content is taken - [read more info about summaries on gohugo.io](https://gohugo.io/content/summaries/). | | **depth** | `1` | The depth of descendants to display. For example, if the value is `2`, the shortcode will display two levels of child pages. To get all descendants, set this value to a high number eg. `999`. | -| **sort** | `auto` | The sort criteria of the displayed list.

- `auto` defaults to [`ordersectionsby` of the pages frontmatter](cont/pages/#frontmatter-configuration)
    or to [`ordersectionsby` of the site configuration](basics/configuration#global-site-parameters)
    or to `weight`
- `weight`
- `title`
- `linktitle`
- `modifieddate`
- `expirydate`
- `publishdate`
- `date`
- `length`
- `default` adhering to Hugo's default sort criteria| +| **sort** | `auto` | The sort criteria of the displayed list.

- `auto` defaults to [`ordersectionsby` of the pages frontmatter](cont/pages#frontmatter-configuration)
    or to [`ordersectionsby` of the site configuration](basics/configuration)
    or to `weight`
- `weight`
- `title`
- `linktitle`
- `modifieddate`
- `expirydate`
- `publishdate`
- `date`
- `length`
- `default` adhering to Hugo's default sort criteria| ## Examples diff --git a/exampleSite/content/shortcodes/openapi/_index.en.md b/exampleSite/content/shortcodes/openapi/_index.en.md index 74d93d5a5d..d34ce7ccc7 100644 --- a/exampleSite/content/shortcodes/openapi/_index.en.md +++ b/exampleSite/content/shortcodes/openapi/_index.en.md @@ -42,7 +42,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](basics/configuration/#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](basics/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. {{% /notice %}} ## Example diff --git a/exampleSite/layouts/partials/shortcodes/piratify.html b/exampleSite/layouts/partials/shortcodes/piratify.html index acb66b5c1d..b169338a1a 100644 --- a/exampleSite/layouts/partials/shortcodes/piratify.html +++ b/exampleSite/layouts/partials/shortcodes/piratify.html @@ -1,7 +1,7 @@ {{- $page := .page }} {{- if and (not $page) .context }} {{- $page = .context }} - {{- warnf "%q: DEPRECATED parameter 'context' for shortcode 'piratify' found, use 'page' instead; see https://mcshelby.github.io/hugo-theme-relearn/basics/migration/#5180" $page.File.Filename }} + {{- warnf "%q: DEPRECATED parameter 'context' for shortcode 'piratify' found, use 'page' instead; see https://mcshelby.github.io/hugo-theme-relearn/basics/migration#5180" $page.File.Filename }} {{- end }} {{- $content := .content }} {{- $pagefield := cond (ne $content nil) nil (.pagefield | default "Content") }} diff --git a/layouts/partials/archetypes/deprecated-chapter/article.html b/layouts/partials/archetypes/deprecated-chapter/article.html index 624d847881..f58dc10743 100644 --- a/layouts/partials/archetypes/deprecated-chapter/article.html +++ b/layouts/partials/archetypes/deprecated-chapter/article.html @@ -1,7 +1,7 @@ {{- $page := .page }} {{- $content := .content }} {{- with $page }} - {{- warnf "%q: DEPRECATED usage of old 'chapter' archetype found, remove 'chapter=true' and add 'archetype=\"chapter\"' to your frontmatter and remove the leading h3 and h1 headings; see https://mcshelby.github.io/hugo-theme-relearn/basics/migration/#500" $page.File.Filename }} + {{- warnf "%q: DEPRECATED usage of old 'chapter' archetype found, remove 'chapter=true' and add 'archetype=\"chapter\"' to your frontmatter and remove the leading h3 and h1 headings; see https://mcshelby.github.io/hugo-theme-relearn/basics/migration#500" $page.File.Filename }}
{{- partial "content-header.html" . }} diff --git a/layouts/partials/archetypes/deprecated-home/article.html b/layouts/partials/archetypes/deprecated-home/article.html index fec3821316..196fc5a9fa 100644 --- a/layouts/partials/archetypes/deprecated-home/article.html +++ b/layouts/partials/archetypes/deprecated-home/article.html @@ -1,7 +1,7 @@ {{- $page := .page }} {{- $content := .content }} {{- with $page }} - {{- warnf "%q: DEPRECATED usage of old 'home' archetype found, add 'archetype=\"home\"' to your frontmatter and remove the leading h1 heading; see https://mcshelby.github.io/hugo-theme-relearn/basics/migration/#500" $page.File.Filename }} + {{- warnf "%q: DEPRECATED usage of old 'home' archetype found, add 'archetype=\"home\"' to your frontmatter and remove the leading h1 heading; see https://mcshelby.github.io/hugo-theme-relearn/basics/migration#500" $page.File.Filename }}
{{- partial "content-header.html" . }} diff --git a/layouts/partials/authorname.hugo b/layouts/partials/authorname.hugo index e3f5a28915..028fae8978 100644 --- a/layouts/partials/authorname.hugo +++ b/layouts/partials/authorname.hugo @@ -5,7 +5,7 @@ {{- $authorName = . }} {{- end }} {{- else }} - {{- warnf "%q: DEPRECATED usage of 'params.author' config parameter found, replace it with `params.author.name` in your config.toml; see https://mcshelby.github.io/hugo-theme-relearn/basics/migration/#5230" .File.Filename }} + {{- warnf "%q: DEPRECATED usage of 'params.author' config parameter found, replace it with `params.author.name` in your config.toml; see https://mcshelby.github.io/hugo-theme-relearn/basics/migration#5230" .File.Filename }} {{- $authorName = .Site.Params.author }} {{- end }} {{- else }} diff --git a/layouts/partials/menu.html b/layouts/partials/menu.html index f16c72ad4c..06cb8097cf 100644 --- a/layouts/partials/menu.html +++ b/layouts/partials/menu.html @@ -20,7 +20,7 @@