mirror of
https://github.com/McShelby/hugo-theme-relearn.git
synced 2024-10-27 02:33:18 +00:00
docs: honing #567
This commit is contained in:
Sören Weber
parent
19c3e8ee49
commit
4d2b55e64b
11 changed files with 60 additions and 42 deletions
36
README.md
36
README.md
|
|
@ -13,34 +13,34 @@ The Relearn theme is an enhanced fork of the popular [Learn theme](https://githu
|
|||
## Key Features
|
||||
|
||||
- **Versatile Usage**
|
||||
- Responsive design for mobile devices
|
||||
- Looks nice on paper (if it has to)
|
||||
- [Responsive design for mobile devices](https://mcshelby.github.io/hugo-theme-relearn/configuration/sidebar/width)
|
||||
- [Looks nice on paper - if it has to](https://mcshelby.github.io/hugo-theme-relearn/configuration/sitemanagement/outputformats)
|
||||
- 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/sitemanagement/deployment/)
|
||||
- [Usable from your local file system without a web server via `file://` protocol](https://mcshelby.github.io/hugo-theme-relearn/configuration/sitemanagement/deployment)
|
||||
- Integration with the [VSCode Front Matter CMS 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/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/appearance/branding#multiple-variants)
|
||||
- Pre-defined color variants
|
||||
- [User-selectable 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)
|
||||
- [Customizable syntax highlighting](https://mcshelby.github.io/hugo-theme-relearn/configuration/appearance/branding/#change-syntax-highlighting)
|
||||
|
||||
- **Advanced Functionality**
|
||||
- [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/)
|
||||
- [Unlimited nested menu structure](https://mcshelby.github.io/hugo-theme-relearn/content/organization)
|
||||
- [Configurable menu shortcuts](https://mcshelby.github.io/hugo-theme-relearn/configuration/sidebar/shortcutmenu/)
|
||||
- Support for hidden pages
|
||||
- [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)
|
||||
- [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)
|
||||
- [Social media integration](https://mcshelby.github.io/hugo-theme-relearn/content/image/)
|
||||
- [Social media integration](https://mcshelby.github.io/hugo-theme-relearn/configuration/sitemanagement/meta#social-media-images)
|
||||
|
||||
- **Multilingual Support**
|
||||
- [Full right-to-left (RTL) language support](https://mcshelby.github.io/hugo-theme-relearn/configuration/sitemanagement/multilingual/)
|
||||
- [Full right-to-left (RTL) language support](https://mcshelby.github.io/hugo-theme-relearn/configuration/sitemanagement/multilingual)
|
||||
- [Extensive list of supported languages](https://mcshelby.github.io/hugo-theme-relearn/configuration/sitemanagement/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/#mixed-language-support)
|
||||
- [Multilingual content search capabilities](https://mcshelby.github.io/hugo-theme-relearn/configuration/sidebar/search#mixed-language-support)
|
||||
|
||||
- **Enhanced Markdown Features**
|
||||
- [GitHub Flavored Markdown (GFM) support](https://mcshelby.github.io/hugo-theme-relearn/content/markdown)
|
||||
|
|
@ -49,15 +49,15 @@ The Relearn theme is an enhanced fork of the popular [Learn theme](https://githu
|
|||
|
||||
- **Rich Shortcode Library**
|
||||
- [Customizable marker badges](https://mcshelby.github.io/hugo-theme-relearn/shortcodes/badge)
|
||||
- [Flexible button creation](https://mcshelby.github.io/hugo-theme-relearn/shortcodes/button)
|
||||
- [Flexible buttons](https://mcshelby.github.io/hugo-theme-relearn/shortcodes/button)
|
||||
- [Child page listing](https://mcshelby.github.io/hugo-theme-relearn/shortcodes/children)
|
||||
- [Expandable content areas](https://mcshelby.github.io/hugo-theme-relearn/shortcodes/expand)
|
||||
- [Font Awesome icon integration](https://mcshelby.github.io/hugo-theme-relearn/shortcodes/icon)
|
||||
- [File inclusion capabilities](https://mcshelby.github.io/hugo-theme-relearn/shortcodes/include)
|
||||
- [MathJax support for mathematical and chemical formulae](https://mcshelby.github.io/hugo-theme-relearn/shortcodes/math)
|
||||
- [Math support for mathematical and chemical formulae](https://mcshelby.github.io/hugo-theme-relearn/shortcodes/math)
|
||||
- [Mermaid diagram integration](https://mcshelby.github.io/hugo-theme-relearn/shortcodes/mermaid)
|
||||
- [Styled notice boxes](https://mcshelby.github.io/hugo-theme-relearn/shortcodes/notice)
|
||||
- [OpenAPI specification rendering with Swagger UI](https://mcshelby.github.io/hugo-theme-relearn/shortcodes/openapi)
|
||||
- [OpenAPI specification rendering](https://mcshelby.github.io/hugo-theme-relearn/shortcodes/openapi)
|
||||
- [Page bundle resource display](https://mcshelby.github.io/hugo-theme-relearn/shortcodes/resources)
|
||||
- [Site configuration parameter display](https://mcshelby.github.io/hugo-theme-relearn/shortcodes/siteparam)
|
||||
- [Tab-based content organization](https://mcshelby.github.io/hugo-theme-relearn/shortcodes/tab) and [multi-tab panels](https://mcshelby.github.io/hugo-theme-relearn/shortcodes/tabs)
|
||||
|
|
|
|||
|
|
@ -7,7 +7,7 @@ weight = 4
|
|||
|
||||
## Opening Links
|
||||
|
||||
By default, external links open in a new tab. To change this, use the `externalLinkTarget` setting with a proper [link target](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a#target).
|
||||
{{% badge style="cyan" icon="gears" title=" " %}}Option{{% /badge %}} By default, external links open in a new tab. To change this, use the `externalLinkTarget` setting with a proper [link target](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a#target).
|
||||
|
||||
For example, this will open links in the same tab
|
||||
|
||||
|
|
@ -34,7 +34,7 @@ This option also comes for the [include](shortcodes/include#enabling-link-warnin
|
|||
|
||||
## Patching the `relref` Shortcode
|
||||
|
||||
While the usage of `relref` is obsolete and discouraged by Hugo for a while, existing installations may still use it.
|
||||
{{% badge style="cyan" icon="gears" title=" " %}}Option{{% /badge %}} While the usage of `relref` is obsolete and discouraged by Hugo for a while, existing installations may still use it.
|
||||
|
||||
In configurations using a baseURL **with** a subdirectory **and** having `relativeURLs=false` (the default) Hugo’s standard `relref` implementation was failing.
|
||||
|
||||
|
|
|
|||
|
|
@ -5,12 +5,26 @@ title = "Titles & Breadcrumbs"
|
|||
weight = 2
|
||||
+++
|
||||
|
||||
## Breadcrumbs
|
||||
|
||||
{{% badge style="cyan" icon="gears" title=" " %}}Option{{% /badge %}} Set `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.
|
||||
|
||||
{{% badge style="cyan" icon="gears" title=" " %}}Option{{% /badge %}} Further, you can override the breadcrumb separator by using `breadcrumbSeparator='/'`. This separator will also be used in the breadcrumbs of the search results and taxonomy pages.
|
||||
{{% badge style="cyan" icon="gears" title=" " %}}Option{{% /badge %}} You can override the default breadcrumb separator by using `breadcrumbSeparator='/'`. This separator will also be used in the breadcrumbs of the search results and taxonomy pages.
|
||||
|
||||
{{% badge style="cyan" icon="gears" title=" " %}}Option{{% /badge %}} By default the term pages of a taxonomy will display the breadcrumb for each page. Set `disableTermBreadcrumbs=true` to remove the breadcrumb if the term pages look to cluttered.
|
||||
|
||||
{{< multiconfig file=hugo >}}
|
||||
[params]
|
||||
disableRootBreadcrumb = true
|
||||
breadcrumbSeparator = '/'
|
||||
disableTermBreadcrumbs = true
|
||||
{{< /multiconfig >}}
|
||||
|
||||
## Titles
|
||||
|
||||
{{% badge style="cyan" icon="gears" title=" " %}}Option{{% /badge %}} You can override the default title separator by using `titleSeparator='|'`.
|
||||
|
||||
{{< multiconfig file=hugo >}}
|
||||
[params]
|
||||
titleSeparator = '|'
|
||||
{{< /multiconfig >}}
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
+++
|
||||
alwaysopen = false
|
||||
description = "Customize files for advanced customization"
|
||||
description = "Customize files for advanced usage"
|
||||
title = "Customization"
|
||||
weight = 5
|
||||
+++
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
+++
|
||||
alwaysopen = false
|
||||
description = "Customize files for advanced customization"
|
||||
description = "Customize files for advanced usage"
|
||||
title = "Customization"
|
||||
weight = 5
|
||||
+++
|
||||
|
|
|
|||
|
|
@ -1,5 +1,5 @@
|
|||
+++
|
||||
description = "Configuration options for the Relearn theme"
|
||||
description = "All configuration options for the Relearn theme"
|
||||
tags = ["reference"]
|
||||
title = "Options Reference"
|
||||
weight = 6
|
||||
|
|
|
|||
|
|
@ -1,5 +1,5 @@
|
|||
+++
|
||||
description = "Configuration options for the Relearn theme"
|
||||
description = "All configuration options for the Relearn theme"
|
||||
tags = ["reference"]
|
||||
title = "Options Reference"
|
||||
weight = 6
|
||||
|
|
|
|||
|
|
@ -1,12 +1,14 @@
|
|||
+++
|
||||
description = "What site-wide meta nformation can be set"
|
||||
frontmatter = ["description"]
|
||||
options = ["author.email", "author.name"]
|
||||
title = "Meta Information"
|
||||
weight = 3
|
||||
+++
|
||||
|
||||
## Site Author Information
|
||||
|
||||
The theme uses author details in various parts of your site, like RSS feeds and meta tags.
|
||||
{{% badge style="cyan" icon="gears" title=" " %}}Option{{% /badge %}} The theme uses author details in various parts of your site, like RSS feeds and meta tags.
|
||||
|
||||
{{< multiconfig file=hugo >}}
|
||||
[params]
|
||||
|
|
@ -17,7 +19,7 @@ The theme uses author details in various parts of your site, like RSS feeds and
|
|||
|
||||
## Site Description
|
||||
|
||||
The theme shows a site description in various places, such as RSS feeds and meta tags. For this, it uses the `description` field from your home page's front matter.
|
||||
{{% badge style="green" icon="fa-fw fab fa-markdown" title=" " %}}Front Matter{{% /badge %}} The theme shows a site description in various places, such as RSS feeds and meta tags. For this, it uses the `description` field from your home page's front matter.
|
||||
|
||||
## Social Media Images
|
||||
|
||||
|
|
|
|||
|
|
@ -19,7 +19,7 @@ weight = -0
|
|||
- suffered from poor build performance for sites with 1000 or more pages
|
||||
- reinvented the wheel instead of using available Hugo mechanisms
|
||||
|
||||
_What do I gain_, you may ask. A significant performance boost during build! Usually, the build time has been cut at least in half for bigger sites. It is now possible to build even larger sites with 5000 or more pages. This was previously almost impossible due to rapidly increasing build time with the more pages you've introduced. For even bigger sites, the theme now has configurable performance optimizations (at the price of feature limitations).
|
||||
_What do I gain_, you may ask. A significant performance boost during build! Usually, the build time has been cut at least in half for bigger sites. It is now possible to build even larger sites with 5000 or more pages. This was previously almost impossible due to rapidly increasing build time with the more pages you've introduced. For even bigger sites, the theme now has [configurable performance optimizations](configuration/sidebar/navigationmenu#expander-for-nested-sections) - at the price of feature limitations.
|
||||
|
||||
If you haven't done customizations to any partials, you can update right away.
|
||||
|
||||
|
|
@ -27,12 +27,10 @@ weight = -0
|
|||
|
||||
Specifically, you will have to adapt your site if you have
|
||||
|
||||
- overwritten the `header.html`, `menu.html` or `footer.html` partials
|
||||
- self-defined output formats that display HTML
|
||||
- defined archetype partials in `layouts/partials/archetypes`
|
||||
- overwritten prev/next topbar buttons
|
||||
|
||||
There is a separate section in the documentation covering these cases.
|
||||
- [overwritten the `header.html`, `menu.html` or `footer.html` partials](configuration/customization/partials)
|
||||
- [self-defined output formats](configuration/customization/outputformats) that display HTML
|
||||
- defined archetype partials in `layouts/partials/archetypes` - now becoming [page designs](configuration/customization/designs)
|
||||
- [overwritten prev/next topbar buttons](configuration/customization/topbar) - needs sync with the implementation changes
|
||||
|
||||
- {{% badge style="warning" title=" " %}}Breaking{{% /badge %}} This release changes the way the search index and the dedicated search page are generated. This may require reconfiguration by you to still work as you have intended.
|
||||
|
||||
|
|
@ -79,11 +77,12 @@ weight = -0
|
|||
|
||||
The docs now clearly differentiate between [configuration of your site](configuration), all things [writing page content](content) and the [shortcodes docs](shortcodes) that cover both topics, configuration and usage.
|
||||
|
||||
To give you a better overview of what's possible with the theme, we introduced reference pages for all theme [configuration options](configuration/options) and [front matter](content/frontmatter) and mark each occurrence of such on all pages with badges {{% badge style="cyan" icon="gears" title=" " %}}Option{{% /badge %}} and {{% badge style="green" icon="fa-fw fab fa-markdown" title=" " %}}Front Matter{{% /badge %}}.
|
||||
To give you a better overview of what's possible with the theme, we introduced reference pages for all theme [configuration options](configuration/options) and [front matter](content/frontmatter) and mark each occurrence of such on all pages with the badges {{% badge style="cyan" icon="gears" title=" " %}}Option{{% /badge %}} and {{% badge style="green" icon="fa-fw fab fa-markdown" title=" " %}}Front Matter{{% /badge %}}.
|
||||
|
||||
Also, a lot of previously undocumented features are now included, namely
|
||||
|
||||
- the [hidden pages](configuration/content/hidden) feature
|
||||
- options of the [navigation menu](configuration/sidebar/navigationmenu)
|
||||
- configuring the [headings](configuration/content/headings) of your content
|
||||
- configuring [breadcrumb, titles](configuration/content/titles) and [headings](configuration/content/headings) of your content
|
||||
- [options for using links](configuration/content/linking)
|
||||
- adding [custom output formats](configuration/customization/outputformats)
|
||||
|
|
|
|||
|
|
@ -1 +1 @@
|
|||
6.4.0+fec603cbbd468c7be6ec978f9fc421b240a6e881
|
||||
6.4.0+d5d7a94e8f291cdd80d26ebda063f6a89fa50547
|
||||
13
theme.toml
13
theme.toml
|
|
@ -5,22 +5,25 @@ description = "A theme for Hugo designed for documentation"
|
|||
homepage = "https://github.com/McShelby/hugo-theme-relearn"
|
||||
demosite = "https://mcshelby.github.io/hugo-theme-relearn"
|
||||
tags = ["dark", "dark mode", "docs", "light", "multilingual", "responsive"]
|
||||
features = ["badges", "breadcrumbs", "boxes", "buttons",
|
||||
"categories", "chemical formulae", "customizable", "color variants",
|
||||
features = [
|
||||
"alerts",
|
||||
"badges", "breadcrumbs", "boxes", "buttons",
|
||||
"callouts", "categories", "chemical formulae", "customizable", "color variants",
|
||||
"dark", "dark mode", "docs", "documentation",
|
||||
"expand",
|
||||
"favicon", "file inclusion", "file system support", "font awesome", "front matter cms",
|
||||
"gfm",
|
||||
"gfm", "github flavored markdown",
|
||||
"hidden pages",
|
||||
"i18n", "icons", "image resizing", "include",
|
||||
"light", "lightbox", "logo",
|
||||
"math", "mathjax", "menu", "mermaid", "multilingual", "mobile",
|
||||
"nested sections", "notice",
|
||||
"nested menus", "nested sections", "notice",
|
||||
"oas", "offline usable", "openapi", "open graph",
|
||||
"print", "printable",
|
||||
"responsive", "rss", "rtl",
|
||||
"schema", "search", "search page", "sidebar", "sitemap", "subtheme", "swagger", "swaggerui", "syntax highlighting",
|
||||
"table of contents", "tab", "tabs", "tags", "taxonomy", "themeable", "themes", "toc", "topbar buttons", "twitter cards"]
|
||||
"table of contents", "tab", "tabs", "tags", "taxonomy", "themeable", "themes", "toc", "topbar buttons", "twitter cards"
|
||||
]
|
||||
|
||||
[module]
|
||||
[module.hugoVersion]
|
||||
|
|
|
|||
Loading…
Reference in a new issue