diff --git a/README.md b/README.md index 0ad62d3143..abec67680f 100644 --- a/README.md +++ b/README.md @@ -31,7 +31,7 @@ The Relearn theme is an enhanced fork of the popular [Learn theme](https://githu - [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/customization/topbar) - - [Nested navigation menu](https://mcshelby.github.io/hugo-theme-relearn/content/organization) + - [Nested navigation menu](https://mcshelby.github.io/hugo-theme-relearn/content/structure) - [Configurable menu shortcuts](https://mcshelby.github.io/hugo-theme-relearn/configuration/sidebar/shortcutmenu) - [Support for hidden pages](https://mcshelby.github.io/hugo-theme-relearn/configuration/content/hidden) - [Comprehensive taxonomy support](https://mcshelby.github.io/hugo-theme-relearn/configuration/customization/taxonomy) diff --git a/exampleSite/content/configuration/appearance/_index.en.md b/exampleSite/content/configuration/appearance/_index.en.md index c21ec0326d..9ea1d7c948 100644 --- a/exampleSite/content/configuration/appearance/_index.en.md +++ b/exampleSite/content/configuration/appearance/_index.en.md @@ -1,6 +1,6 @@ +++ alwaysopen = false -description = "Change colors, logos and the general appearance of your site" +description = "Change colors, logos and the overall appearance of your site" title = "Appearance" weight = 2 +++ diff --git a/exampleSite/content/configuration/appearance/_index.pir.md b/exampleSite/content/configuration/appearance/_index.pir.md index 97de83a9f9..393724b5bc 100644 --- a/exampleSite/content/configuration/appearance/_index.pir.md +++ b/exampleSite/content/configuration/appearance/_index.pir.md @@ -1,6 +1,6 @@ +++ alwaysopen = false -description = "Change colors, logos and the general appearance of your site" +description = "Change colors, logos and the overall appearance of your site" title = "Appearance" weight = 2 +++ diff --git a/exampleSite/content/configuration/appearance/branding/_index.en.md b/exampleSite/content/configuration/appearance/branding/_index.en.md index 0a37edecb3..cb2b3601f5 100644 --- a/exampleSite/content/configuration/appearance/branding/_index.en.md +++ b/exampleSite/content/configuration/appearance/branding/_index.en.md @@ -96,7 +96,7 @@ The `identifier` option is mandatory and equivalent to the string in the first e | name | see notes | The name to be displayed in the variant selector. If not set, the identifier is used in a human readable form. | | auto | _<empty>_ | If set, the variant is treated as an [auto mode variant](#adjust-to-os-settings). It has the same behavior as the `themeVariantAuto` option. The first entry in the array is the color variant for light mode, the second for dark mode. Defining auto mode variants with the advanced options has the benefit that you can now have multiple auto mode variants instead of just one with the simple options. | -#### Example Configuration of This Site +#### Example Configuration {{< multiconfig file=hugo >}} [params] diff --git a/exampleSite/content/configuration/customization/designs/index.en.md b/exampleSite/content/configuration/customization/designs/index.en.md index 6c27da7561..1bff67e1bc 100644 --- a/exampleSite/content/configuration/customization/designs/index.en.md +++ b/exampleSite/content/configuration/customization/designs/index.en.md @@ -1,30 +1,41 @@ +++ -description = "Using and extending page designs" +description = "Extending page designs" title = "Page Designs" weight = 5 +++ -The Relearn theme offers several page designs: `home`, `chapter`, and `default`. These are available as [archetypes](content/layouts) for site authors. +A page is displayed by exactly one page design. The Relearn theme offers the page designs `home`, `chapter`, and `default`. -To use a design, set [Hugo's reserved `type` option](https://gohugo.io/content-management/front-matter/#type) in your page's front matter. +A page design usually consists of -This leverages Hugo's [content view feature](https://gohugo.io/templates/types/#content-view). Don't use the `type` option in your modifications for other functionality! +- [an archetype file](https://gohugo.io/content-management/archetypes/): a template for creating new Markdown files with this design +- [content view files](https://gohugo.io/templates/types/#content-view): represented by [Hugo's reserved `type` front matter](https://gohugo.io/content-management/front-matter/#type) and backed by matching partials +- CSS styles -All designs use the theme's framework from `themes/hugo-theme-learn/layouts/_default/baseof.html`, containing of the same topbar and sidebar but can change how content appears in the center of the page. +If no `type` is set in your front matter, the page is treated as if `type='default'` was set. -### Creating Your Own Page Designs +> [!warning] +> Don't use the `type` option in your modifications for other functionality! + +All shipped designs use the theme's framework from `themes/hugo-theme-learn/layouts/_default/baseof.html`, containing of the same topbar and sidebar but can change how content appears in the center of the page. + +## Using a Page Design + +Regardless of shipped or custom page design, you are [using them](content/designs) in the same way. + +## Creating a Page Designs To make a custom page design: 1. Choose a name (for example, `mydesign`) -2. Create a file at `layouts/mydesign/views/article.html` -3. Add this content +2. Create a content view file at `layouts/mydesign/views/article.html` ````html {title="layouts/mydesign/views/article.html"}
{{ partial "content-header.html" . }}
+
AWESOME
{{ partial "heading-pre.html" . }}{{ partial "heading.html" . }}{{ partial "heading-post.html" . }} {{ partial "article-content.html" . }}
```` -In this file, you can customize the page design as needed. Typically, you'll want to: + In this file, you can customize the page design as needed. Typically, you'll want to: -- Set a `class` at the `article` element for custom CSS styles -- Use `{{ partial "article-content.html" . }}` to show your page content + - Set a `class` at the `article` element for custom CSS styles + - Use `{{ partial "article-content.html" . }}` to show your page content + +3. Create an archetype file at `archetypes/mydesign.md` (optional) + + ````html {title="archetypes/mydesign.md"} + +++ + title = "{{ replace .Name "-" " " | title }}" + type = "mydesign" + +++ + + This is my new design. + ```` + +4. Add CSS in file `layouts/partials/custom-header.html` (optional) + + ````html {title="layouts/partials/custom-header.html"} + + ```` + +### Partials + +The above example uses `layouts/mydesign/views/article.html` but you have some others + +- `layouts/mydesign/baseof.html`: Completely redefine the whole HTML structure, none of the other listed partials will be used +- `layouts/mydesign/views/menu.html`: Defines the sidebar menu layout +- `layouts/mydesign/views/body.html`: Determines what to contain in the content area (for example a single page, a list of pages, a tree of sub pages) +- `layouts/mydesign/views/article.html`: Controls how one page's content and title are displayed diff --git a/exampleSite/content/configuration/customization/imageeffects.en.md b/exampleSite/content/configuration/customization/imageeffects.en.md index 670602fbc0..14547def89 100644 --- a/exampleSite/content/configuration/customization/imageeffects.en.md +++ b/exampleSite/content/configuration/customization/imageeffects.en.md @@ -7,10 +7,12 @@ weight = 3 This page shows you, how to configure custom [image effects](content/markdown#image-effects) on top of existing ones. -For a detailed usage example, see [this page](content/imageeffects). +This setting can also be overridden by your front matter. For a detailed usage example, see [this page](content/imageeffects). If you don't configure anything in your `hugo.toml`, the image effects default to +## Default Values + {{< multiconfig >}} [imageEffects] border = false @@ -19,36 +21,19 @@ If you don't configure anything in your `hugo.toml`, the image effects default t shadow = false {{< /multiconfig >}} -{{% badge style="cyan" icon="gears" title=" " %}}Option{{% /badge %}} You can change these settings in your `hugo.toml` +## Configuration -{{< multiconfig file=hugo >}} -[params] - [params.imageEffects] - border = true - lazy = false -{{< /multiconfig >}} - -This would result in - -{{< multiconfig >}} -[imageEffects] - border = true - lazy = false - lightbox = true - shadow = false -{{< /multiconfig >}} - -## Adding Custom Effects - -You can add new effects with boolean values +{{% badge style="cyan" icon="gears" title=" " %}}Option{{% /badge %}} You can change these settings in your `hugo.toml` and add arbitrary custom effects as boolean values (like `bg-white` in the below snippet). {{< multiconfig file=hugo >}} [params] [params.imageEffects] bg-white = true + border = true + lazy = false {{< /multiconfig >}} -Result: +This would result in {{< multiconfig >}} [imageEffects] @@ -59,28 +44,30 @@ Result: shadow = false {{< /multiconfig >}} -## Styling Custom Effects - -If the effective image effect value is - -- `true`: add a class with the effect's name -- `false`: add a class with the effect's name and a "no" prefix - ### Example +With this configuration in effect, the following URL + ````markdown {title="Markdown"} ![Minion](https://octodex.github.com/images/minion.png) ```` -### Result +would result in ````html {title="HTML"} Minion ```` -Styles for default image effets are contained in the theme. Add custom styles for your extension image effects to `layouts/partials/content-header.html`. +## Styling Effects -In the above example you could add styles for both cases: +If the resulting effect value is + +- `true`: add a class with the effect's name +- `false`: add a class with the effect's name and a "no" prefix + +Styles for default effects are contained in the theme. Add styles for your custom effects to `layouts/partials/content-header.html`. + +For the above example you could add styles for both boolean cases: ````html {title="layouts/partials/content-header.html"}