From 7e83840a20d8d81da21c0de64bcd7f0d45553178 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?S=C3=B6ren=20Weber?= Date: Sat, 24 Feb 2024 16:52:53 +0100 Subject: [PATCH] docs: more clarification for serving use cases --- README.md | 2 +- exampleSite/content/_index.en.md | 2 +- exampleSite/content/basics/CHANGELOG.md | 2 +- .../content/basics/customization/_index.en.md | 55 +++++++++++++------ .../content/basics/migration/_index.en.md | 2 +- 5 files changed, 41 insertions(+), 22 deletions(-) diff --git a/README.md b/README.md index b83c96185b..366c024ead 100644 --- a/README.md +++ b/README.md @@ -16,7 +16,7 @@ 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/customization#serving-your-page-from-the-filesystem) + - [Usable from your local file system via `file://` protocol](https://mcshelby.github.io/hugo-theme-relearn/basics/customization#file-system) - 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/customization#social-media-meta-tags) diff --git a/exampleSite/content/_index.en.md b/exampleSite/content/_index.en.md index b7d50ab09d..3f7c939b12 100644 --- a/exampleSite/content/_index.en.md +++ b/exampleSite/content/_index.en.md @@ -19,7 +19,7 @@ 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/customization#serving-your-page-from-the-filesystem) + - [Usable from your local file system via `file://` protocol](basics/customization#file-system) - 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/customization#social-media-meta-tags) diff --git a/exampleSite/content/basics/CHANGELOG.md b/exampleSite/content/basics/CHANGELOG.md index 414575cccb..1c72a7a4ff 100644 --- a/exampleSite/content/basics/CHANGELOG.md +++ b/exampleSite/content/basics/CHANGELOG.md @@ -486,7 +486,7 @@ ### Fixes - [**bug**] i18n: write code ltr even for rtl languages [#492](https://github.com/McShelby/hugo-theme-relearn/issues/492) -- [**bug**] anchor: fix link in FF when served from filesystem [#482](https://github.com/McShelby/hugo-theme-relearn/issues/482) +- [**bug**] anchor: fix link in FF when served from file system [#482](https://github.com/McShelby/hugo-theme-relearn/issues/482) - [**bug**] shortcodes: don't break build and render for invalid parameters [#480](https://github.com/McShelby/hugo-theme-relearn/issues/480) - [**bug**] nav: restore scroll position on browser back [#476](https://github.com/McShelby/hugo-theme-relearn/issues/476) - [**bug**] variant: avoid style leak for auto style [#473](https://github.com/McShelby/hugo-theme-relearn/issues/473) diff --git a/exampleSite/content/basics/customization/_index.en.md b/exampleSite/content/basics/customization/_index.en.md index 94cefb8dd6..d809fcc176 100644 --- a/exampleSite/content/basics/customization/_index.en.md +++ b/exampleSite/content/basics/customization/_index.en.md @@ -3,41 +3,56 @@ title = "Customization" weight = 25 +++ -## Serving your page from a subfolder +## Usage scenarios -If your site is served from a subfolder, eg. `https://example.com/mysite/`, you have to set the following lines to your `hugo.toml` +The theme is usable in different scenarios, requiring the following mandatory settings in your `hugo.toml`. All settings not mentioned can be set to your liking. + +### Public Webserver from Root + +````toml +baseURL = "https://example.com/" +```` + +### Public Webserver from Subdirectory ````toml baseURL = "https://example.com/mysite/" +relativeURLs = false ```` -## Serving your page from the filesystem +### Private Webserver (LAN) -If you want your page served from the filesystem by using URLs starting with `file://` you'll need the following configuration in your `hugo.toml`: +The same settings as with any of the public webserver usage scenarios or ````toml +baseURL = "/" 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 `hugo.toml` +### File System + +````toml +baseURL = "/" +relativeURLs = true +```` + +{{% notice warning %}} +Using a `baseURL` with a subdirectory and `relativeURLs=true` are mutally exclusive due to the fact, that [Hugo does not apply the `baseURL` correctly](https://github.com/gohugoio/hugo/issues/12130). + +If you need both, you have to generate your site twice but with different settings into separate directories. +{{% /notice %}} + +{{% notice note %}} +Sublemental pages (like `sitemap.xml`, `rss.xml`) and generated social media links inside of your pages will always be generated with absolute URLs and will not work if you set `relativeURLs=true`. +{{% /notice %}} + +{{% notice info %}} +If you are using `uglyURLs=false` (Hugo's default), the theme will append an additional `index.html` to all page links to make your site be servable from the file system. If you don't care about the file system and only serve your page via a webserver you can generate the links without this: ````toml [params] disableExplicitIndexURLs = true ```` - -{{% notice note %}} -Sublemental pages (like `sitemap.xml`, `rss.xml`) will always be generated with fully quallyfied URLs and will not work if your site is served from the filesystem. -{{% /notice %}} - -{{% notice note %}} -If you want to use the search feature from the file system, migrating from 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 %}} - -{{% notice warning %}} -[Serving your page from a subfolder](#serving-your-page-from-a-subfolder) and [Serving your page from the filesystem](#serving-your-page-from-the-filesystem) are mutally exclusive due to the fact, that [Hugo does not apply the `baseURL` correctly](https://github.com/gohugoio/hugo/issues/12130). - -If you need both, you have to generate your site twice but with different settings into separate directories. {{% /notice %}} ## Activate search @@ -51,6 +66,10 @@ If not already present, add the following lines in your `hugo.toml` file. 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. +{{% notice note %}} +If you want to use the search feature from the file system, migrating from 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 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 `hugo.toml` file. This will cause Hugo to generate a new file `http://example.com/mysite/search.html`. diff --git a/exampleSite/content/basics/migration/_index.en.md b/exampleSite/content/basics/migration/_index.en.md index 6eda743ccf..3cfb1263bb 100644 --- a/exampleSite/content/basics/migration/_index.en.md +++ b/exampleSite/content/basics/migration/_index.en.md @@ -468,7 +468,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/customization#serving-your-page-from-the-filesystem) in your `hugo.toml` your page is now servable from the local file system using `file://` URLs. +- {{% badge style="note" title=" " %}}Change{{% /badge %}} [With the proper settings](basics/customization#file-system) in your `hugo.toml` your page is now servable from the local file system using `file://` URLs. Please note that the searchbox will only work for this if you reconfigure your outputformat for the homepage in your `hugo.toml` from `json` to `search`. The now deprecated `json` outputformat still works as before, so there is no need to reconfigure your installation if it is only served from `http://` or `https://`.