docs: revise versioning #1050

docs/content/configuration/sitemanagement/versioning/_index.en.md

@@ -12,90 +12,109 @@ A version switcher will be displayed at the top of the sidebar if versioning is
 
 If you want to have more control, where the version switcher is positioned or you want to configure a different icon, see the [chapter on sidebar configuration](configuration/sidebar/menus#defining-sidebar-menus).
 
-## Example: Versioning an Existing Site
+## Example: Versioning an Existing Nonversioned Site
 
-Assume, you are writing a documentation for an app. At some point you are a releasing a new major version. This new version requires enhanced documentation while the older documentation must still be available for users of the older app version.
+Assume, you have written a documentation for an app. At some point you are a releasing a new major version. This new version requires enhanced documentation while the older documentation must still be available for users of the older app version.
 
-This is your intial `hugo.toml` file:
+Your site's source files reside in the directory `/home/me/mysite` on your local disc. The current URL of your site (the value set in `baseURL` in your `hugo.toml`) is `https://example.com/`. When done, the URL of the latest version of your site should not change. The archived version of your site should be available at the URL `https://example.com/v1.0/`.
 
-{{< multiconfig file=hugo >}}
+This is your intial config file before versioning:
+
+{{< multiconfig file=/home/me/mysite/hugo >}}
 baseURL = 'https://example.com/'
 {{< /multiconfig >}}
 
 To setup versioning, you have to do the following steps:
 
-1. Prepare your old site for versioning.
-    - add an array of all available `versions` to your `hugo.toml`
-    - add information, which of these versions is the latest by setting the `isLatest` option on **one** item in the `versions` array
-    - add information, which of these versions your site actually is, by setting the `version` option
-    - change your `baseURL` to the version specific URL
-      {{< multiconfig file=hugo >}}
+1. Prepare `/home/me/mysite/hugo.toml` of the current version for versioning.
+    - add an array of all available `versions`
+    - add information, which of these versions is the latest by setting the `isLatest` option on **one** item (here onto `v2.0`) in the `versions` array
+    - add information, which of these versions your site actually is, by setting the `version` option (here to `v2.0`)
+
+    After the modifications the config file looks like:
+
+      {{< multiconfig file=/home/me/mysite/hugo >}}
+      baseURL = 'https://example.com/'
+      params = { version = 'v2.0', versions = [
+        { identifier = 'v2.0', title = 'Latest', baseURL = 'https://example.com/', isLatest = true },
+        { identifier = 'v1.0', title = 'v1.0', baseURL = 'https://example.com/v1.0/' }
+      ]}
+      {{< /multiconfig >}}
+2. Generate the current site with the changed configuration and deploy the resulting directory to `baseURL` (here to `https://example.com/`)
+    - this step has not changed to your previous deploy, so everything should be familiar until here
+3. Copy the source files from `/home/me/mysite` into a new directory `/home/me/mysite-1.0` for the archived version
+4. Prepare `/home/me/mysite-1.0/hugo.toml` of the archived version for release.
+    - change the information, which of the versions your site actually is, by setting the `version` option (here to `v1.0`)
+    - change the top level `baseURL` to the URL of version 1.0 (here to `https://example.com/v1.0/`)
+
+    After the modifications the config file looks like:
+
+      {{< multiconfig file=/home/me/mysite-1.0/hugo >}}
       baseURL = 'https://example.com/v1.0/'
       params = { version = 'v1.0', versions = [
         { identifier = 'v2.0', title = 'Latest', baseURL = 'https://example.com/', isLatest = true },
         { identifier = 'v1.0', title = 'v1.0', baseURL = 'https://example.com/v1.0/' }
       ]}
       {{< /multiconfig >}}
-2. Generate your old site into the `baseURL` (in our case `https://example.com/v1.0/`)
-3. Copy you Hugo project into a new directory
-4. Make changes to the documentation for the new version
-5. Prepare your new site for release.
-    - leave the previously set array of available `versions` as is
-    - change the information, which of the versions your site actually is, by setting the `version` option
-    - change your `baseURL` back to the original URL
-      {{< multiconfig file=hugo >}}
-      baseURL = 'https://example.com/'
-      params = { version = 'v2.0', versions = [
-        { identifier = 'v2.0', title = 'Latest', baseURL = 'https://example.com/', isLatest = true },
-        { identifier = 'v1.0', title = 'v1.0', baseURL = 'https://example.com/v1.0/' }
-      ]}
-      {{< /multiconfig >}}
-6. Generate your new site to the chosen location (in our case `https://example.com/`)
+5. Generate the archived site with the changed configuration and deploy the resulting directory to `baseURL` (here to `https://example.com/v1.0/`)
+6. Now you're ready to edit the content of your current version and proceed with your usual workflow.
 
-A few things to note here:
+**A few things to note here:**
 
 - `version` must be an `identifier` of one of the entries in the `versions` array
-- you are not limited with the `baseURL`, these can be absolute or relative to your server root
-- you can generate your old versions into the directory of the new version
+- you are not limited with the `baseURL`; these can be absolute or relative to your server root, can also reside in sub-subdirectories or be subdomains
+- you can generate your archived versions into a sub-directory of the current version (as with this example)
+- if you generate your archived versions into a sub-directory take care in your workflow not to delete old archived versions during release of the current version
+- the example does not take version control systems into account (like git or subversion) as such a workflow is highly subjective
+- both sites are completely independent autonomous Hugo sites; if you want to test this setup locally, you will need two running Hugo servers
+- if you want to test this locally, you will need to adept the top level `baseURL` parameter as well as the `baseURL` parameter in the `versions` array to your local setup; best is to have [preconfigured environment configs](https://gohugo.io/configuration/introduction/#configuration-directory) available
 
-## Example: Add New Versions to a Versioned Site
+## Example: Add a New Version to a Versioned Site
 
 At some point, your version 2 of the app may be deprecated, too, as you've released a new version 3.
 
-You only need to create two versions of your site, the former current one and the new current one.
+The structure from the previous example still applys. Your current version of your site's source files reside in the directory `/home/me/mysite` on your local disc, the archived version in `/home/me/mysite-0.1`. The current URL of your site (the value set in `baseURL` in your `hugo.toml`) is `https://example.com/`. When done, the URL of the latest version of your site should not change. The archived version of your site should be available at the URL `https://example.com/v2.0/`.
 
-1. Prepare your old site.
-    - add the new version to the array of available `versions` in your `hugo.toml`
-    - revise information, which of these versions is the latest by setting the `isLatest` option on **one** item in the `versions` array
-    - change your `baseURL` to the version specific URL
-      {{< multiconfig file=hugo >}}
-      baseURL = 'https://example.com/v2.0/'
-      params = { version = 'v2.0', versions = [
-        { identifier = 'v3.0', title = 'Latest', baseURL = 'https://example.com/', isLatest = true },
-        { identifier = 'v2.0', title = 'v2.0', baseURL = 'https://example.com/v2.0/' },
-        { identifier = 'v1.0', title = 'v1.0', baseURL = 'https://example.com/v1.0/' }
-      ]}
-      {{< /multiconfig >}}
-2. Generate your old site into the `baseURL` (in our case `https://example.com/v2.0/`)
-3. Copy you Hugo project into a new directory
-4. Make changes to the documentation for the new version
-5. Prepare your new site for release.
-    - leave the previously set array of available `versions` as is
-    - change the information, which of the versions your site actually is, by setting the `version` option
-    - change your `baseURL` back to the original URL
-      {{< multiconfig file=hugo >}}
+You only need to generate the current and the new archived version of your site (`v3.0` and `v2.0`), the former archived version (`v1.0`) doesn't need to be generated again..
+
+1. Prepare `/home/me/mysite/hugo.toml` of the current version for the new archived version.
+    - add the new archived version to the array of available `versions`
+    - change information, which of these versions is the latest by setting the `isLatest` option on **one** item (here onto `v3.0`) in the `versions` array
+    - add information, which of these versions your site actually is, by setting the `version` option (here to `v3.0`)
+
+    After the modifications the config file looks like:
+
+      {{< multiconfig file=/home/me/mysite/hugo >}}
       baseURL = 'https://example.com/'
       params = { version = 'v3.0', versions = [
         { identifier = 'v3.0', title = 'Latest', baseURL = 'https://example.com/', isLatest = true },
-        { identifier = 'v2.0', title = 'v2.0', baseURL = 'https://example.com/v2.0/' },
+        { identifier = 'v2.0', title = 'v2.0', baseURL = 'https://example.com/v.2.0/' },
         { identifier = 'v1.0', title = 'v1.0', baseURL = 'https://example.com/v1.0/' }
       ]}
       {{< /multiconfig >}}
-6. Generate your new site to the chosen location (in our case `https://example.com/`)
+2. Generate the current site with the changed configuration and deploy the resulting directory to `baseURL` (here to `https://example.com/`)
+3. Copy the source files from `/home/me/mysite` into a new directory `/home/me/mysite-2.0` for the archived version
+4. Prepare `/home/me/mysite-2.0/hugo.toml` of the archived version for release.
+    - change the information, which of the versions your site actually is, by setting the `version` option (here to `v2.0`)
+    - change the top level`baseURL` to the URL of version 2.0 (here to `https://example.com/v2.0/`)
 
-A few things to note here:
+    After the modifications the config file looks like:
 
-- you **don't need to recreate version 1** of your site as long as the `baseURL` for the entry marked with `isLatest=true` hasn't changed. The old versions will access the version index of the latest site to display all available versions in the version switcher
+      {{< multiconfig file=/home/me/mysite-2.0/hugo >}}
+      baseURL = 'https://example.com/v2.0/'
+      params = { version = 'v2.0', versions = [
+        { identifier = 'v3.0', title = 'Latest', baseURL = 'https://example.com/', isLatest = true },
+        { identifier = 'v2.0', title = 'v2.0', baseURL = 'https://example.com/v.2.0/' },
+        { identifier = 'v1.0', title = 'v1.0', baseURL = 'https://example.com/v1.0/' }
+      ]}
+      {{< /multiconfig >}}
+5. Generate the archived site with the changed configuration and deploy the resulting directory to `baseURL` (here to `https://example.com/v2.0/`)
+6. Now you're ready to edit the content of your current version and proceed with your usual workflow.
+
+**A few things to note here:**
+
+- you **don't need to regenerate version 1** of your site as long as the version marked with `isLatest=true` hasn't changed its `baseURL` parameter. The old archived versions will access the version index of the latest site using JavaScript to display all currently available versions in the version switcher
+- with each new version, you will need another Hugo server instance to run a complete local test
 
 ## Hiding the Deprecation Warning
 

layouts/partials/version.txt

@@ -1 +1 @@
-7.5.0+5ba09afb6c62227e5e432359be04159973e3774b
+7.5.0+75d9bc2b2ef443f15cd428a046ca249dcde58131