Docs: versions of the documentation by mike

.github/workflows/docs.yml

@@ -7,10 +7,13 @@ on:
       - 'docs/**'
       - 'mkdocs.yml'
       - '.github/workflows/docs.yml'
+    # the paths are not checked for the tags
+    tags: ['v*']
   workflow_dispatch:
 
 permissions:
-  contents: read
+  # the versions of the documentation are stored in the gh-pages branch by mike
+  contents: write
   pages: write
   id-token: write
 
@@ -23,13 +26,37 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
       - uses: actions/setup-python@v5
         with:
           python-version: '3.12'
           cache: pip
           cache-dependency-path: docs/requirements.txt
       - run: pip install -r docs/requirements.txt
-      - run: mkdocs build --strict --site-dir site
+      - run: mkdocs build --strict --site-dir site-check
+
+      - name: Deploy the version
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+          git fetch origin gh-pages --depth=1 || true
+          if [[ "$GITHUB_REF" == refs/tags/v* ]]; then
+            # v1.4.2 is the version 1.4, the latest release
+            version="${GITHUB_REF_NAME#v}"
+            mike deploy --push --update-aliases "${version%.*}" latest
+          elif mike list | grep -v '^dev' | grep -q .; then
+            mike deploy --push dev
+          else
+            # latest is dev until the first release with the versions of the documentation
+            mike deploy --push --update-aliases dev latest
+          fi
+          mike set-default --push latest
+
+      - name: Checkout the site
+        run: |
+          git fetch origin gh-pages --depth=1
+          git worktree add site origin/gh-pages
       - uses: actions/upload-pages-artifact@v3
         with:
           path: site

Readme.md

@@ -5,7 +5,7 @@
 # tinyconf
 tinyconf - a simple and universal library for parsing configs.
 
-Documentation: [insei.github.io/tinyconf](https://insei.github.io/tinyconf/) — get started, [why tinyconf](https://insei.github.io/tinyconf/why-tinyconf/), [use cases](https://insei.github.io/tinyconf/use-cases/), features and drivers.
+Documentation: [insei.github.io/tinyconf](https://insei.github.io/tinyconf/) — get started, [why tinyconf](https://insei.github.io/tinyconf/latest/why-tinyconf/), [use cases](https://insei.github.io/tinyconf/latest/use-cases/), features and drivers.
 
 # Installation
 Install via go get. Note that Go 1.19 or newer is required.
@@ -303,4 +303,4 @@ If the driver implements the optional `tinyconf.Loader` or `tinyconf.ContextLoad
 so the driver can read its source once and not for every field.
 If the driver implements the optional `tinyconf.Watcher` interface, it can report changes of its source for reloading.
 
-More examples: the service in the [`example`](example) directory, runnable examples on [pkg.go.dev](https://pkg.go.dev/github.com/insei/tinyconf#pkg-examples), recipes in the [documentation](https://insei.github.io/tinyconf/use-cases/).
+More examples: the service in the [`example`](example) directory, runnable examples on [pkg.go.dev](https://pkg.go.dev/github.com/insei/tinyconf#pkg-examples), recipes in the [documentation](https://insei.github.io/tinyconf/latest/use-cases/).

docs/requirements.txt

@@ -1,2 +1,3 @@
 mkdocs-material>=9.5,<10
 pymdown-extensions>=10.7,<11
+mike>=2.1,<3

mkdocs.yml

@@ -61,6 +61,8 @@ markdown_extensions:
       emoji_generator: !!python/name:material.extensions.emoji.to_svg
 
 extra:
+  version:
+    provider: mike
   social:
     - icon: fontawesome/brands/github
       link: https://github.com/Insei/tinyconf