docs: migration and configuration #888

README.md

@@ -28,9 +28,7 @@ The Relearn theme is a fork of the great [Learn theme](https://github.com/matcor
   - [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/customization#activate-print-support)
-  - In page search
-  - [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)
+  - [In-page search, search popup and dedicated search page](https://mcshelby.github.io/hugo-theme-relearn/basics/customization#configure-search)
   - [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)

exampleSite/content/basics/customization/_index.en.md

@@ -55,32 +55,29 @@ If you are using `uglyURLs=false` (Hugo's default), the theme will append an add
 {{< /multiconfig >}}
 {{% /notice %}}
 
-## Activate search
+## Configure Search
 
-If not already present, add the following lines in your `hugo.toml` file.
+The theme comes with three levels of search, all provided through the search form in the menu:
 
-{{< multiconfig file=hugo >}}
-[outputs]
-  home = ["html", "rss"]
-{{< /multiconfig >}}
+- in-page search: a found search term will be marked in the currently displayed page
+- search popup: if a search index is generated, a popup will open during typing in the search form, if the term is found in other pages of your site
+- dedicated search page: access the dedicated search page by either clicking on the magnifier glass or by typing some search term in the search form and pressing `ENTER`
 
-This will generate a search index file at the root of your public folder ready to be consumed by the Lunr search library.
+Each level depends on the previous level to be enabled, eg. the dedicated search page is only available, if you have search popup and in-page search enabled.
 
-### Activate dedicated search page
+By default all three levels are enabled. You can disable each level by the following settings in your `hugo.toml`:
 
-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`.
+- in-page search: `disableSearch=true`
+- search popup: `disableSearchIndex=true`
+- dedicated search page: `disableSearchPage=true`
 
-{{< multiconfig file=hugo >}}
-[outputs]
-  home = ["html", "rss"]
-{{< /multiconfig >}}
+By default the following files will be created for each level, relative to each languages home page but can be overwritten:
 
-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)
+- search popup: `search_index.js`, configured by `searchIndexURL`
+- dedicated search page: either `/search.html` or `search/index.html` depending on your settings for `uglyURLs`, configured by `searchPageURL`
 
 {{% 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 `hugo.toml` and defining a Markdown file `content/search.md`.
+You only need to reconfigure the file / page URLs if you have own content at those URLs in your project. Eg. this can happen if you set `uglyURLs=true` in your `hugo.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 %}}

exampleSite/content/basics/migration/_index.en.md

@@ -18,6 +18,31 @@ This document shows you what's new in the latest release and flags it with one o
 
 ---
 
+## 7.0.0 (XXXX-XX-XX) {#700}
+
+- {{% badge style="warning" title=" " %}}Breaking{{% /badge %}} This release changes the way, the search index and the dedicated search page are generated and require reconfiguration by you to not break your build.
+
+  You need to remove the `search` and `searchpage` output format from `outputs.home` in your `hugo.toml`, resulting in something similar to
+
+    {{< multiconfig file=hugo >}}
+    [outputs]
+      home = ["html", "rss", "print"]
+    {{< /multiconfig >}}
+
+  After that, your build will succeed but causes new defaults to be applied. With no further settings, in-page search, search popup and dedicated search page are active by default.
+
+  You can disable search completely, causing no search field in the menu by adding `disableSearch=true` to your `hugo.toml`.
+
+  You can limit your site to only providing in-page search by disabling generation of the search index and search page using `disableSearchIndex=true` in your `hugo.toml`.
+
+  You can limit your site to only providing in-page search and the search popup by disabling generation of the search page using `disableSearchPage=true` in your `hugo.toml`.
+
+  In addition you are now able to overwrite the default file and page names of the search index and the search page by changing `searchIndexURL` and `searchPageURL` respectivly in your `hugo.toml`.
+
+  See the [updated documentation](basics/customization#configure-search) for reference.
+
+---
+
 ## 6.4.0 (2024-10-11) {#640}
 
 - {{% badge style="note" title=" " %}}Change{{% /badge %}} If you now display a single code block in a `notice` box, its [margin and border will be removed](shortcodes/notice#code-with-collapsed-colored-borders) so only the colored notice border is visible.
@@ -105,7 +130,7 @@ This document shows you what's new in the latest release and flags it with one o
 
 - {{% badge style="warning" title=" " %}}Breaking{{% /badge %}} Search support for the `json` outputformat [deprecated in 5.4.0](#540) was removed.
 
-  Change it to `search` for the homepage in your `hugo.toml`. See the docs for [detailed configuration](basics/customization#activate-search).
+  Change it to `search` for the homepage in your `hugo.toml`. See the docs for [detailed configuration](basics/customization#configure-search).
 
 - {{% badge style="warning" title=" " %}}Breaking{{% /badge %}} The frontmatter option `menuTitle` [deprecated in 5.24.0](#5240) was removed in favor for Hugo’s own `linkTitle`.
 
@@ -590,7 +615,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 through large number of results.
 
-  To activate this feature, you need to [configure it](basics/customization#activate-dedicated-search-page) in your `hugo.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#configure-search) in your `hugo.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.