docs: use mike and gh actions for versioned k3d.io (#731)

* docs: use mike for versioned k3d.io
* switch to ghactions for docs

.drone.yml

@@ -73,6 +73,7 @@ steps:
         - tag
       ref:
         include:
+          # include only pre-release tags
           - "refs/tags/*rc*"
           - "refs/tags/*beta*"
           - "refs/tags/*alpha*"
@@ -97,11 +98,14 @@ steps:
         - tag
       ref:
         exclude:
+          # exclude pre-release tags
           - "refs/tags/*rc*"
           - "refs/tags/*beta*"
           - "refs/tags/*alpha*"
           - "refs/tags/*test*"
           - "refs/tags/*dev*"
+          # exclude docs specific tags
+          - "refs/tags/*docs*" 
 
 services:
   # Starting the docker service to be used by dind
@@ -116,51 +120,6 @@ volumes:
   - name: dockersock
     temp: {}
 
----
-#########################
-##### Documentation #####
-#########################
-
-kind: pipeline
-type: docker
-name: docs
-
-platform:
-  os: linux
-  arch: amd64
-
-steps:
-
-  - name: build
-    image: python:3.9
-    commands:
-      - python3 -m pip install -r docs/requirements.txt
-      - mkdocs build --verbose --clean --strict
-    when:
-      branch:
-        - main
-      event:
-        - push
-
-  - name: publish
-    image: plugins/gh-pages
-    settings:
-      password:
-        from_secret: github_token
-      username: rancherio-gh-m
-      pages_directory: site/
-      target_branch: gh-pages
-    when:
-      branch:
-        - main
-      event:
-        - push
-
-trigger:
-  event:
-    - push
-  branch:
-    - main
 
 ---
 ###########################
@@ -258,6 +217,10 @@ trigger:
   event:
     - tag # see note at the start of the "Docker Images" section: creates SemVer tagged images using the `auto_tag` option of the docker plugin
     - push # `auto_tag` option only creates the `latest` tag if target branch is default branch (i.e. `main`)
+  ref:
+    exclude:
+      # exclude docs specific tags
+      - "refs/tags/*docs*" 
 
 depends_on:
   - main
@@ -310,6 +273,10 @@ trigger:
   event:
     - tag # see note at the start of the "Docker Images" section: creates SemVer tagged images using the `auto_tag` option of the docker plugin
     - push # `auto_tag` option only creates the `latest` tag if target branch is default branch (i.e. `main`)
+  ref:
+    exclude:
+      # exclude docs specific tags
+      - "refs/tags/*docs*" 
 
 depends_on:
   - main
@@ -399,6 +366,10 @@ trigger:
   event:
     - tag # see note at the start of the "Docker Images" section: creates SemVer tagged images using the `auto_tag` option of the docker plugin
     - push # `auto_tag` option only creates the `latest` tag if target branch is default branch (i.e. `main`)
+  ref:
+    exclude:
+      # exclude docs specific tags
+      - "refs/tags/*docs*" 
 
 depends_on:
   - main
@@ -465,6 +436,10 @@ trigger:
   event:
     - tag # see note at the start of the "Docker Images" section: creates SemVer tagged images using the `auto_tag` option of the manifest plugin
     - push # `auto_tag` option only creates the `latest` tag if target branch is default branch (i.e. `main`)
+  ref:
+    exclude:
+      # exclude docs specific tags
+      - "refs/tags/*docs*" 
 
 depends_on:
   - main

.github/workflows/docs.yml

@@ -0,0 +1,46 @@
+name: k3d.io
+
+on:
+  push:
+    branches:
+      - main
+    tags:
+      # only run on tags for real releases and special docs releases
+      - 'v[0-9]+.[0-9]+.[0-9]+'
+      - 'v[0-9]+.[0-9]+.[0-9]+-docs.[0-9]+'
+    # tags-ignore:
+    #   - "*rc*"
+    #   - "*beta*"
+    #   - "*alpha*"
+    #   - "*test*"
+    #   - "*dev*"
+
+jobs:
+  build:
+    runs-on: ubuntu-20.04
+    container:
+      image: python:3.9
+    steps:
+      - name: Checkout Project
+        uses: actions/checkout@v2
+        with:
+          fetch-depth: 0
+      - name: Install Requirements
+        run: pip install -r docs/requirements.txt
+      - name: Build with MkDocs (validation)
+        run: |
+          mkdocs build --verbose --clean --strict
+          rm -r site/
+      - name: Configure Git
+        if: startsWith(github.ref, 'refs/tags/')
+        id: git
+        run: |
+          git config --global user.name ghaction-k3d.io
+          git config --global user.email ghaction@k3d.io
+          echo ::set-output name=tag::${GITHUB_REF#refs/tags/}
+      - name: Build & Deploy with Mike (versioned)
+        if: startsWith(github.ref, 'refs/tags/')
+        run: |
+          mike deploy --update-aliases --push --rebase ${{ steps.git.outputs.tag }} stable
+      
+

docs/requirements.txt

@@ -1,7 +1,8 @@
-mkdocs
-mkdocs-material
-pymdown-extensions
-mkdocs-git-revision-date-localized-plugin
-mkdocs-awesome-pages-plugin
-mdx_truly_sane_lists
-mkdocs-include-markdown-plugin # https://github.com/mondeja/mkdocs-include-markdown-plugin
+mkdocs==1.2.2
+mkdocs-material==7.2.6
+pymdown-extensions==8.2
+mkdocs-git-revision-date-localized-plugin==0.9.3
+mkdocs-awesome-pages-plugin==2.5.0
+mdx_truly_sane_lists==1.2 # https://github.com/radude/mdx_truly_sane_lists
+mkdocs-include-markdown-plugin==3.2.2 # https://github.com/mondeja/mkdocs-include-markdown-plugin
+mike==1.1.0 # versioned docs: https://github.com/jimporter/mike

mkdocs.yml

@@ -25,7 +25,10 @@ theme:
   name: material
   language: en
   features:
-    - tabs
+    - navigation.top # show back to top button
+    - search.suggest # search suggestions: https://squidfunk.github.io/mkdocs-material/setup/setting-up-site-search/#search-suggestions
+    - search.highlight # highlight search term on target page: https://squidfunk.github.io/mkdocs-material/setup/setting-up-site-search/#search-suggestions
+
   palette:
     - media: "(prefers-color-scheme: light)"
       scheme: default
@@ -71,6 +74,16 @@ plugins:
       type: date
   - awesome-pages # https://squidfunk.github.io/mkdocs-material/plugins/awesome-pages/
   - include-markdown # https://github.com/mondeja/mkdocs-include-markdown-plugin
+  - mike: # Versioned Docs: https://github.com/jimporter/mike
+      version_selector: true   # set to false to leave out the version selector
+      css_dir: static/css             # the directory to put the version selector's CSS
+      javascript_dir: static/js       # the directory to put the version selector's JS
+      canonical_version: null  # the version for <link rel="canonical">; `null` uses the version specified via `mike deploy`
+
+# Extra mkdocs-material settings
+extra:
+  version:
+    provider: mike
 
 # Other Settings
-strict: true # halt processing when a warning is raised
+strict: true # halt processing when a warning is raised