docs: migration instructions #685 #891

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

@@ -57,11 +57,11 @@ If you are using `uglyURLs=false` (Hugo's default), the theme will append an add
 
 ## Configure Search
 
-The theme comes with three levels of search, all provided through the search form in the menu:
+The theme comes with three levels of search, all provided through the search form in the menu
 
-- 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`
+- in-page search: a search term will be marked if found in the currently displayed page
+- search popup: a popup will open during typing if the term is found in other pages of your site
+- dedicated search page: you can access a dedicated search page by either clicking on the magnifier glass or by typing and pressing <kbd>ENTER</kbd>
 
 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.
 
@@ -71,7 +71,7 @@ By default all three levels are enabled. You can disable each level by the follo
 - search popup: `disableSearchIndex=true`
 - dedicated search page: `disableSearchPage=true`
 
-By default the following files will be created for each level, relative to each languages home page but can be overwritten:
+By default the following files will be created, relative to each languages home page but can be overwritten:
 
 - search popup: `searchindex.js`, configured by `searchIndexURL`
 - dedicated search page: either `/search.html` or `search/index.html` depending on your settings for `uglyURLs`, configured by `searchPageURL`

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

@@ -20,26 +20,43 @@ This document shows you what's new in the latest release and flags it with one o
 
 ## 7.0.0 (XXXX-XX-XX) {#700}
 
+> [!secondary]
+> The release you didn't know you want!
+
 - {{% badge color="fuchsia" icon="fa-fw fab fa-hackerrank" title=" " %}}0.126.0{{% /badge %}} This release requires a newer Hugo version.
 
-- {{% 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.
+- {{% badge style="warning" title=" " %}}Breaking{{% /badge %}} This release comes with significant changes in file naming of partials and how the theme works internally. This was done because the theme
 
-  You need to remove the `search` and `searchpage` output format from `outputs.home` in your `hugo.toml`, resulting in something similar to
+  - 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 in half. 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 the more pages you've introduced. For even bigger sites, the theme now has configurable performance optimizations (at the price of feature limitations).
+
+  If you haven't done customizations to any partials, you can update right away.
+
+  If you have customized your templates, in best cases you will get build warnings or even errors. In worst cases, your build succeeds but the site will not work as intended by you.
+
+  Specifically, you will most likely 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`
+  - redefined prev/next topbar buttons
+
+  There is a separate section in the documentation covering these cases.
+
+- {{% badge style="warning" title=" " %}}Breaking{{% /badge %}} This release changes the way, the search index and the dedicated search page are generated. This requires reconfiguration by you to still work as you intended.
+
+  You need to remove the now obsolete `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.
+  After that, your build will succeed but will most likely cause new defaults to be applied. With no further settings, in-page search, search popup and dedicated search page are all 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`.
+  In addition you are now able to overwrite the default file name of the search index and the default page name of the dedicated search page by changing `searchIndexURL` and `searchPageURL` respectively in your `hugo.toml`.
 
   See the [updated documentation](basics/customization#configure-search) for reference.