feat: build versioned documentation site form CI pipeline

.github/workflows/ci.yml

@@ -251,7 +251,7 @@ jobs:
           tags: ${{ steps.meta.outputs.tags }}
           labels: ${{ steps.meta.outputs.labels }}
 
-  docs:
+  typedocs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v3
@@ -259,7 +259,7 @@ jobs:
         with:
           node-version: '16.x'
       - run: npm ci --ignore-scripts
-      - run: npm run docs
+      - run: npm run typedocs
       - name: Save docs
         uses: actions/upload-artifact@v3
         with:
@@ -267,9 +267,28 @@ jobs:
           path: docs
           retention-days: 1
 
+  mkdocs:
+    runs-on: ubuntu-latest
+    if: startsWith(github.ref, 'refs/tags/v')
+    needs:
+      - typedocs
+    steps:
+      - uses: actions/checkout@v2
+      - id: get_version
+        uses: battila7/get-version-action@v2
+      - uses: actions/setup-python@v2
+        with:
+          python-version: 3.x
+      - run: pip install mkdocs-material 
+      - run: pip install mike
+      - run: git config user.name ci-bot
+      - run: git config user.email ci-bot@example.com
+      - run: git fetch origin gh-pages --depth=1
+      - run: cd documentation && mike deploy --push --update-aliases ${{steps.get_version.outputs.major}}.${{steps.get_version.outputs.minor}} latest
+
   publish-docs:
     needs:
-      - docs
+      - mkdocs
       - lint
       - test-unit
       - test-integration
@@ -282,7 +301,10 @@ jobs:
         with:
           name: docs
           path: docs
+      - id: get_version
+        uses: battila7/get-version-action@v2
       - uses: peaceiris/actions-gh-pages@v3
         with:
           github_token: ${{ secrets.GITHUB_TOKEN }}
-          publish_dir: .
+          publish_dir: ./docs
+          destination_dir:  ${{steps.get_version.outputs.major}}.${{steps.get_version.outputs.minor}}/docs

documentation/markdown/README.md

@@ -1,4 +1,9 @@
-# Documentation
+---
+hide:
+  - navigation
+---
+
+# Welcome
 
 Welcome to the Community Solid Server!
 Here we will cover many aspects of the server,

documentation/markdown/architecture.md

@@ -69,5 +69,5 @@ The `ErrorHandler` will convert the error to an HTTP response to be returned.
 Below are sections that go deeper into the specific steps.
 Not all steps are covered yet and will be added in the future.
 
-[How authentication and authorization work](authorization.md)
-[What the `ResourceStore` looks like](resource-store.md)
+* [How authentication and authorization work](authorization.md)
+* [What the `ResourceStore` looks like](resource-store.md)

documentation/mkdocs.yml

@@ -0,0 +1,89 @@
+docs_dir: markdown
+
+theme:
+  name: 'material'
+  custom_dir: overrides
+  icon:
+    repo: fontawesome/brands/github
+  palette:
+    - media: "(prefers-color-scheme: light)"
+      scheme: default
+      toggle:
+        icon: material/weather-night 
+        name: Switch to dark mode
+      primary: deep purple
+      accent: deep orange
+
+    # Palette toggle for dark mode
+    - media: "(prefers-color-scheme: dark)"
+      scheme: slate
+      toggle:
+        icon: material/weather-sunny
+        name: Switch to light mode
+      primary: deep purple
+      accent: deep orange
+  features:
+    - navigation.instant
+    - navigation.tabs
+    - navigation.top
+    - navigation.indexes
+
+site_name: 'Community Solid Server'
+site_url: https://communitysolidserver.github.io/CommunitySolidServer
+
+repo_url: https://github.com/CommunitySolidServer/CommunitySolidServer
+repo_name: CommunitySolidServer
+edit_uri: ""
+
+plugins:
+  - search
+
+markdown_extensions:
+  - admonition
+  - def_list
+  - footnotes
+  - meta
+  - tables
+  - toc:
+      permalink: true
+  - pymdownx.betterem:
+      smart_enable: all
+  - pymdownx.caret
+  - pymdownx.tilde
+  - pymdownx.details
+  - pymdownx.highlight
+  - pymdownx.superfences 
+  - pymdownx.smartsymbols
+
+
+extra:
+  version: 
+    provider: mike
+  social:
+    - icon: fontawesome/brands/github
+      link: https://github.com/CommunitySolidServer/CommunitySolidServer
+    - icon: fontawesome/brands/docker
+      link: https://hub.docker.com/r/solidproject/community-server
+    - icon: fontawesome/brands/npm
+      link: https://www.npmjs.com/package/@solid/community-server
+    - icon: fontawesome/brands/gitter
+      link: https://gitter.im/CommunitySolidServer/community
+
+nav:
+  - Welcome: 
+    - README.md
+  - Usage:    
+    - 'Example request': example-requests.md
+    - 'Identity provider': identity-provider.md
+    - 'Client credentials': client-credentials.md
+    - 'Seeding Pods': seeding-pods.md
+  - Architecture:
+    - Architecture: architecture.md
+    - Dependency injection: dependency-injection.md
+  - Contributing: 
+    - Pull requests: making-changes.md
+    - Releases: release.md
+  - API: ./docs/" target="_blank
+
+# To write documentation locally, execute the next line and browse to http://localhost:8000 
+# docker run --rm -it -p 8000:8000 -v ${PWD}/documentation:/docs squidfunk/mkdocs-material

documentation/overrides/main.html

@@ -0,0 +1,8 @@
+{% extends "base.html" %}
+
+{% block outdated %}
+  You're not viewing the latest version.
+  <a href="{{ '../' ~ base_url }}"> 
+    <strong>Click here to go to latest.</strong>
+  </a>
+{% endblock %}

documentation/typedoc.css

@@ -0,0 +1,4 @@
+.tsd-page-toolbar,
+.tsd-page-title {
+    background-color: #7E56C2;
+}

package.json

@@ -50,7 +50,7 @@
     "docker:setup": "./test/docker/docker-setup.sh",
     "docker:start": "./test/docker/docker-start.sh",
     "docker:stop": "./test/docker/docker-stop.sh",
-    "docs": "typedoc",
+    "typedocs": "typedoc --customCss ./documentation/typedoc.css",
     "jest": "jest --coverageReporters text-summary --",
     "lint": "eslint . --cache --ignore-path .gitignore --max-warnings 0",
     "prepare": "npm run build",