initial commit
This commit is contained in:
@@ -0,0 +1,9 @@
|
||||
+++
|
||||
alwaysopen = false
|
||||
categories = ["reference"]
|
||||
description = "Get yourself familiar with the general structure of your website"
|
||||
title = "Site Management"
|
||||
weight = 1
|
||||
+++
|
||||
|
||||
{{% children containerstyle="div" style="h2" description=true %}}
|
||||
@@ -0,0 +1,8 @@
|
||||
+++
|
||||
alwaysopen = false
|
||||
categories = ["reference"]
|
||||
description = "Get yourself familiar with the general structure of your website"
|
||||
title = "Site Management"
|
||||
weight = 1
|
||||
+++
|
||||
{{< piratify >}}
|
||||
@@ -0,0 +1,61 @@
|
||||
+++
|
||||
categories = ["howto"]
|
||||
description = "Options for specific deployment needs"
|
||||
title = "Deployment Scenarios"
|
||||
weight = 4
|
||||
+++
|
||||
|
||||
## Offline Usage
|
||||
|
||||
The theme is usable offline. No internet connection is required to load your page. This is achieved by storing all dependencies within the theme.
|
||||
|
||||
No calls to 3rd party servers, no calling home, no tracking. Privacy friendly.
|
||||
|
||||
## Server Deployment
|
||||
|
||||
If your server deployment has no special requirements, you can skip this section and use the [standard Hugo options](https://gohugo.io/content-management/urls/).
|
||||
|
||||
For special requirements, the theme is capable of different scenarios, requiring the following mandatory settings in your `hugo.toml`. All settings not mentioned in the examples below can be set to your liking.
|
||||
|
||||
### Public Web Server from Root
|
||||
|
||||
{{< multiconfig file=hugo >}}
|
||||
baseURL = 'https://example.com/'
|
||||
{{< /multiconfig >}}
|
||||
|
||||
### Public Web Server from Subdirectory
|
||||
|
||||
{{< multiconfig file=hugo >}}
|
||||
baseURL = 'https://example.com/mysite/'
|
||||
relativeURLs = false
|
||||
{{< /multiconfig >}}
|
||||
|
||||
If you are still using Hugo's `relref` shortcode (which you shouldn't), you will need [further configuration](configuration/content/linking#patching-the-relref-shortcode).
|
||||
|
||||
> [!WARNING]
|
||||
> Don't use a `baseURL` with a subdirectory and `relativeURLs=true` together. [Hugo doesn't apply the `baseURL` correctly](https://github.com/gohugoio/hugo/issues/12130) in this case. If you need both, generate your site twice with different settings into separate directories.
|
||||
|
||||
### Private Web Server (LAN)
|
||||
|
||||
The same settings as with any of the public web server scenarios or
|
||||
|
||||
{{< multiconfig file=hugo >}}
|
||||
baseURL = '/'
|
||||
relativeURLs = true
|
||||
{{< /multiconfig >}}
|
||||
|
||||
### File System
|
||||
|
||||
Your generated site can be used headless without a HTTP server.
|
||||
|
||||
This can be achieved by using the `file://` protocol in your browser's address bar or by double click on a generated `*.html` file in your file navigation tool.
|
||||
|
||||
Use the following settings
|
||||
|
||||
{{< multiconfig file=hugo >}}
|
||||
baseURL = '/'
|
||||
relativeURLs = true
|
||||
{{< /multiconfig >}}
|
||||
|
||||
> [!note]
|
||||
> Pages like `sitemap.xml` and `rss.xml`, and social media links will always use absolute URLs. They won't work with `relativeURLs=true`.
|
||||
@@ -0,0 +1,7 @@
|
||||
+++
|
||||
categories = ["howto"]
|
||||
description = "Options for specific deployment needs"
|
||||
title = "Deployment Scenarios"
|
||||
weight = 4
|
||||
+++
|
||||
{{< piratify >}}
|
||||
@@ -0,0 +1,43 @@
|
||||
+++
|
||||
categories = ["howto"]
|
||||
description = "What site-wide meta information can be set"
|
||||
frontmatter = ["description"]
|
||||
options = ["author.email", "author.name"]
|
||||
title = "Meta Information"
|
||||
weight = 3
|
||||
+++
|
||||
|
||||
## Site Author Information
|
||||
|
||||
{{% 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]
|
||||
[params.author]
|
||||
name = 'Santa Claus'
|
||||
email = 'santa@example.com'
|
||||
{{< /multiconfig >}}
|
||||
|
||||
## Site Title
|
||||
|
||||
The `title` will be used in meta information of your HTML.
|
||||
|
||||
{{< multiconfig file=hugo >}}
|
||||
title = 'Hugo Relearn Theme'
|
||||
{{< /multiconfig >}}
|
||||
|
||||
## Site Description
|
||||
|
||||
{{% 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
|
||||
|
||||
When your page is shared on social media, you can set a site-wide image to display with the link
|
||||
|
||||
{{< multiconfig file=hugo >}}
|
||||
images = [ 'images/hero.png' ]
|
||||
{{< /multiconfig >}}
|
||||
|
||||
## More Social Media Options
|
||||
|
||||
The theme adheres to Hugo's official documentation for [Open Graph](https://gohugo.io/templates/embedded/#configure-open-graph) and [Twitter Cards](https://gohugo.io/templates/embedded/#configure-x-twitter-cards) configuration.
|
||||
@@ -0,0 +1,9 @@
|
||||
+++
|
||||
categories = ["howto"]
|
||||
description = "What site-wide meta information can be set"
|
||||
frontmatter = ["description"]
|
||||
options = ["author.email", "author.name"]
|
||||
title = "Meta Information"
|
||||
weight = 3
|
||||
+++
|
||||
{{< piratify >}}
|
||||
@@ -0,0 +1,155 @@
|
||||
+++
|
||||
categories = ["howto"]
|
||||
description = "How to set up a multilingual site"
|
||||
options = ["disableLanguageSwitchingButton"]
|
||||
title = "Multilingual"
|
||||
weight = 2
|
||||
+++
|
||||
|
||||
The Relearn theme works with [Hugo's multilingual mode](https://gohugo.io/content-management/multilingual/).
|
||||
|
||||
It supports many languages, including right-to-left languages.
|
||||
|
||||
{{% expand "Supported languages" %}}
|
||||
- Arabic
|
||||
- Simplified Chinese
|
||||
- Traditional Chinese
|
||||
- Czech
|
||||
- Dutch
|
||||
- English
|
||||
- Finnish
|
||||
- French
|
||||
- German
|
||||
- Hindi
|
||||
- Hungarian
|
||||
- Indonesian
|
||||
- Italian
|
||||
- Japanese
|
||||
- Korean
|
||||
- Persian
|
||||
- Polish
|
||||
- Portuguese
|
||||
- Romanian
|
||||
- Russian
|
||||
- Spanish
|
||||
- Swahili
|
||||
- Turkish
|
||||
- Vietnamese
|
||||
{{% /expand %}}
|
||||
|
||||
## Translation by File Name
|
||||
|
||||
Here's how to make your site multilingual using [translations by file name](https://gohugo.io/content-management/multilingual/#translation-by-file-name):
|
||||
|
||||
1. Set up languages in your `hugo.toml` file:
|
||||
|
||||
{{< multiconfig file=hugo >}}
|
||||
defaultContentLanguage = 'en'
|
||||
|
||||
[languages]
|
||||
[languages.en]
|
||||
weight = 1
|
||||
languageName = 'English'
|
||||
languageCode = 'en'
|
||||
title = 'My Website'
|
||||
|
||||
[languages.pir]
|
||||
weight = 2
|
||||
languageName = 'Pirrratish'
|
||||
languageCode = 'art-x-pir'
|
||||
languageDirection = 'rtl'
|
||||
title = 'Arrr, my Website'
|
||||
{{< /multiconfig >}}
|
||||
|
||||
2. Duplicate your content files and add language codes to their file names:
|
||||
|
||||
````plaintext
|
||||
├── content
|
||||
│ ├── log
|
||||
│ │ ├── first-day
|
||||
| | | ├── _index.en.md
|
||||
| | | └── _index.pir.md
|
||||
│ │ ├── second-day
|
||||
| | | ├── index.en.md
|
||||
| | | └── index.pir.md
|
||||
│ │ ├── third-day.en.md
|
||||
│ │ ├── third-day.pir.md
|
||||
│ │ ├── _index.en.md
|
||||
│ │ └── _index.pir.md
|
||||
│ ├── _index.en.md
|
||||
│ └── _index.pir.md
|
||||
├── themes
|
||||
│ └── hugo-theme-relearn
|
||||
│ └── ...
|
||||
└── hugo.toml
|
||||
````
|
||||
|
||||
## Translation by Content Directory
|
||||
|
||||
The theme also support [translations by content directory](https://gohugo.io/content-management/multilingual/#translation-by-content-directory) which can be configured in a similar way.
|
||||
|
||||
1. Set up languages in your `hugo.toml` file:
|
||||
|
||||
{{< multiconfig file=hugo >}}
|
||||
defaultContentLanguage = 'en'
|
||||
|
||||
[languages]
|
||||
[languages.en]
|
||||
weight = 1
|
||||
languageName = 'English'
|
||||
languageCode = 'en'
|
||||
contentDir = 'content/en'
|
||||
title = 'My Website'
|
||||
|
||||
[languages.pir]
|
||||
weight = 2
|
||||
languageName = 'Pirrratish'
|
||||
languageCode = 'art-x-pir'
|
||||
languageDirection = 'rtl'
|
||||
contentDir = 'content/pir'
|
||||
title = 'Arrr, my Website'
|
||||
{{< /multiconfig >}}
|
||||
|
||||
2. Duplicate your content files into separate directories named by their language code:
|
||||
|
||||
````plaintext
|
||||
├── content
|
||||
│ ├── en
|
||||
| │ ├── log
|
||||
| │ │ ├── first-day
|
||||
| | | | └── _index.md
|
||||
| │ │ ├── second-day
|
||||
| | | | └── index.md
|
||||
| │ │ ├── third-day.md
|
||||
| │ │ └── _index.md
|
||||
| │ └── _index.md
|
||||
│ ├── pir
|
||||
| │ ├── log
|
||||
| │ │ ├── first-day
|
||||
| | | | └── _index.md
|
||||
| │ │ ├── second-day
|
||||
| | | | └── index.md
|
||||
| │ │ ├── third-day.md
|
||||
| │ │ └── _index.md
|
||||
| │ └── _index.md
|
||||
| ├── themes
|
||||
| │ └── hugo-theme-relearn
|
||||
| │ └── ...
|
||||
| └── hugo.toml
|
||||
````
|
||||
|
||||
|
||||
## Search Settings
|
||||
|
||||
Check the [search configuration](configuration/sidebar/search#mixed-language-support) for multilingual options.
|
||||
|
||||
## Turn Off Language Switching
|
||||
|
||||
{{% badge style="cyan" icon="gears" title=" " %}}Option{{% /badge %}} By default the theme shows a language switcher in the lower part of the menu.
|
||||
|
||||
To disable the language switcher set `disableLanguageSwitchingButton=true`
|
||||
|
||||
{{< multiconfig file=hugo >}}
|
||||
[params]
|
||||
disableLanguageSwitchingButton = true
|
||||
{{< /multiconfig >}}
|
||||
@@ -0,0 +1,8 @@
|
||||
+++
|
||||
categories = ["howto"]
|
||||
description = "How to set up a multilingual site"
|
||||
options = ["disableLanguageSwitchingButton"]
|
||||
title = "Multilingual"
|
||||
weight = 2
|
||||
+++
|
||||
{{< piratify >}}
|
||||
@@ -0,0 +1,86 @@
|
||||
+++
|
||||
categories = ["howto"]
|
||||
description = "What formats can a page be displayed in"
|
||||
outputs = ["html", "rss", "print", "markdown", "source"]
|
||||
title = "Available Output Formats"
|
||||
weight = 5
|
||||
+++
|
||||
|
||||
The Relearn theme by default comes with templates for HTML and RSS for each page.
|
||||
|
||||
In addition you can configure the below formats.
|
||||
|
||||
If this is not enough, learn how to [create your own output formats](configuration/customization/outputformats).
|
||||
|
||||
## Print Support
|
||||
|
||||
Enable print support to print entire chapters or the whole site. Add the `print` output format to your home, section, and page in `hugo.toml`:
|
||||
|
||||
{{< multiconfig file=hugo >}}
|
||||
[outputs]
|
||||
home = ['html', 'rss', 'print']
|
||||
section = ['html', 'rss', 'print']
|
||||
page = ['html', 'rss', 'print']
|
||||
{{< /multiconfig >}}
|
||||
|
||||
By default this adds a printer icon in the topbar but [can be deactived](authoring/frontmatter/topbar/#print-button). Clicking it switches to print preview, showing the page and its [visible subpages](configuration/content/hidden) in a printer-friendly format. Use your browser's print function to print or save as PDF.
|
||||
|
||||
The URL won't be [configured ugly](https://gohugo.io/templates/output-formats/#configure-output-formats) for [Hugo's URL handling](https://gohugo.io/content-management/urls/#ugly-urls), even with `uglyURLs=true` in `hugo.toml`. This is because each mime type can only have one suffix.
|
||||
|
||||
If you don't like the URLs, you can reconfigure `outputFormats.print` in your `hugo.toml` to something other than the default of:
|
||||
|
||||
{{< multiconfig file=hugo >}}
|
||||
[outputFormats]
|
||||
[outputFormats.print]
|
||||
name= 'print'
|
||||
baseName = 'index.print'
|
||||
isHTML = true
|
||||
mediaType = 'text/html'
|
||||
permalinkable = false
|
||||
noUgly = true
|
||||
{{< /multiconfig >}}
|
||||
|
||||
## Markdown Support
|
||||
|
||||
Enable support to show the Markdown source of a page. Add the `markdown` output format to your home, section, and page in `hugo.toml`:
|
||||
|
||||
{{< multiconfig file=hugo >}}
|
||||
[outputs]
|
||||
home = ['html', 'rss', 'markdown']
|
||||
section = ['html', 'rss', 'markdown']
|
||||
page = ['html', 'rss', 'markdown']
|
||||
{{< /multiconfig >}}
|
||||
|
||||
By default this adds a Markdown icon in the topbar but [can be deactived](authoring/frontmatter/topbar/#markdown-button). Clicking it switches to the Markdown source including the title of the page.
|
||||
|
||||
The `markdown` output format configuration is [provided by Hugo](https://gohugo.io/templates/output-formats/#output-format-definitions).
|
||||
|
||||
## Source Support
|
||||
|
||||
Enable support to show the source code of a page if it was generated from a file. Add the `source` output format to your home, section, and page in `hugo.toml`:
|
||||
|
||||
{{< multiconfig file=hugo >}}
|
||||
[outputs]
|
||||
home = ['html', 'rss', 'source']
|
||||
section = ['html', 'rss', 'source']
|
||||
page = ['html', 'rss', 'source']
|
||||
{{< /multiconfig >}}
|
||||
|
||||
By default this adds a Source icon in the topbar but [can be deactived](authoring/frontmatter/topbar/#source-button). Clicking it switches to the source code of the page.
|
||||
|
||||
The Source output format differs from the Markdown format, as it prints the source code _as is_ including the front matter.
|
||||
|
||||
The URL won't be [configured ugly](https://gohugo.io/templates/output-formats/#configure-output-formats) for [Hugo's URL handling](https://gohugo.io/content-management/urls/#ugly-urls), even with `uglyURLs=true` in `hugo.toml`. This is because each mime type can only have one suffix.
|
||||
|
||||
If you don't like the URLs, you can reconfigure `outputFormats.source` in your `hugo.toml` to something other than the default of:
|
||||
|
||||
{{< multiconfig file=hugo >}}
|
||||
[outputFormats]
|
||||
[outputFormats.source]
|
||||
name= 'source'
|
||||
baseName = 'index.source'
|
||||
isHTML = false
|
||||
mediaType = 'text/markdown'
|
||||
permalinkable = false
|
||||
noUgly = true
|
||||
{{< /multiconfig >}}
|
||||
@@ -0,0 +1,8 @@
|
||||
+++
|
||||
categories = ["howto"]
|
||||
description = "What formats can a page be displayed in"
|
||||
outputs = ["html", "rss", "print", "markdown", "source"]
|
||||
title = "Available Output Formats"
|
||||
weight = 5
|
||||
+++
|
||||
{{< piratify >}}
|
||||
@@ -0,0 +1,57 @@
|
||||
+++
|
||||
categories = ["howto"]
|
||||
description = "How to make your generated HTML output stable"
|
||||
options = ["disableAssetsBusting", "disableGeneratorVersion", "disableRandomIds", "minify"]
|
||||
title = "Stable Output"
|
||||
weight = 6
|
||||
+++
|
||||
|
||||
## Disabling the Generator Meta
|
||||
|
||||
{{% badge style="cyan" icon="gears" title=" " %}}Option{{% /badge %}} The theme adds a meta tag with its version number to each page.
|
||||
|
||||
This isn't a security risk and helps us support you better.
|
||||
|
||||
To turn this off, set `disableGeneratorVersion=true`.
|
||||
|
||||
{{< multiconfig file=hugo >}}
|
||||
[params]
|
||||
disableGeneratorVersion = true
|
||||
{{< /multiconfig >}}
|
||||
|
||||
If you also want to turn off [Hugo's version meta tag](https://gohugo.io/getting-started/configuration/#disablehugogeneratorinject), use `disableHugoGeneratorInject=true`.
|
||||
|
||||
## Disabling IDs for Referenced Assets
|
||||
|
||||
{{% badge style="cyan" icon="gears" title=" " %}}Option{{% /badge %}} The theme creates a unique ID for each build and adds it to each referenced asset's URL to make browsers not keep outdated cached assets.
|
||||
|
||||
This is good for production sites but can be problematic during development. It makes comparing outputs difficult as each build has new IDs.
|
||||
|
||||
To disable this, set `disableAssetsBusting=true`.
|
||||
|
||||
{{< multiconfig file=hugo >}}
|
||||
[params]
|
||||
disableAssetsBusting = true
|
||||
{{< /multiconfig >}}
|
||||
|
||||
## Disabling IDs for Interactive HTML Elements
|
||||
|
||||
{{% badge style="cyan" icon="gears" title=" " %}}Option{{% /badge %}} Features like expanders, callouts, and tabs use unique IDs to work. These IDs change with each build.
|
||||
|
||||
This is necessary for the theme to work properly, but it can make comparing outputs between builds difficult.
|
||||
|
||||
To turn this off, set `disableRandomIds=true`. Note, that this will result in a non-functional site!.
|
||||
|
||||
{{< multiconfig file=hugo >}}
|
||||
[params]
|
||||
disableRandomIds = true
|
||||
{{< /multiconfig >}}
|
||||
|
||||
## Disabling Assets Minification
|
||||
|
||||
{{% badge style="cyan" icon="gears" title=" " %}}Option{{% /badge %}} If `minify=true`, further theme assets will be minified during build. If no value is set, the theme will avoid minification if you have started with `hugo server` and otherwise will minify.
|
||||
|
||||
{{< multiconfig file=hugo >}}
|
||||
[params]
|
||||
minify = false
|
||||
{{< /multiconfig >}}
|
||||
@@ -0,0 +1,8 @@
|
||||
+++
|
||||
categories = ["howto"]
|
||||
description = "How to make your generated HTML output stable"
|
||||
options = ["disableAssetsBusting", "disableGeneratorVersion", "disableRandomIds", "minify"]
|
||||
title = "Stable Output"
|
||||
weight = 6
|
||||
+++
|
||||
{{< piratify >}}
|
||||
@@ -0,0 +1,39 @@
|
||||
+++
|
||||
categories = ["explanation"]
|
||||
description = "Your site's directory structure"
|
||||
title = "Directory Structure"
|
||||
weight = 1
|
||||
+++
|
||||
|
||||
If you've followed the [Getting Started](introduction/quickstart) guide, your directory layout will look similar to this:
|
||||
|
||||
````plaintext
|
||||
├── content
|
||||
│ ├── log
|
||||
│ │ ├── first-day
|
||||
| | | └── _index.md
|
||||
│ │ ├── second-day
|
||||
| | | └── index.md
|
||||
│ │ ├── third-day.md
|
||||
│ │ └── _index.md
|
||||
│ └── _index.md
|
||||
├── themes
|
||||
│ └── hugo-theme-relearn
|
||||
│ └── ...
|
||||
└── hugo.toml
|
||||
````
|
||||
|
||||
Hugo uses a [union file system](https://gohugo.io/getting-started/directory-structure/#union-file-system), which lets you combine multiple directories.
|
||||
|
||||
By default, it puts your root directory on top of the Relearn theme directory. Files in your root directory will replace theme files in the same location.
|
||||
|
||||
For example, if you create a file at `layouts/partials/heading.html`, it will override the theme's `themes/hugo-theme-relearn/layouts/partials/heading.html`.
|
||||
|
||||
[See this list](configuration/customization/partials), to learn which files are allowed to be overridden by you.
|
||||
|
||||
This makes it easy to customize the theme without changing files in the `themes` directory, making future theme updates simpler.
|
||||
|
||||
> [!WARNING]
|
||||
> Don't edit files inside the `themes/hugo-theme-relearn` directory. That's not the recommended way to customize! Refer to the explanation above.
|
||||
>
|
||||
> Don't clone the theme repository and edit files there for your site. That's not the recommended way to customize! Instead, follow the [Getting Started](introduction/quickstart) guide.
|
||||
@@ -0,0 +1,7 @@
|
||||
+++
|
||||
categories = ["explanation"]
|
||||
description = "Your site's directory structure"
|
||||
title = "Directory Structure"
|
||||
weight = 1
|
||||
+++
|
||||
{{< piratify >}}
|
||||
Reference in New Issue
Block a user