chore: docusaurus upgrade (#350)

* chore: upgrade docusaurus to 3.6.0

* ci: use action from docusaurus docs

https://docusaurus.io/docs/deployment#triggering-deployment-with-github-actions

* ci: configure cache correctly

* ci: set working directory

* ci: remove cd step

* docs: fix broken link

.github/workflows/publish-docs.yml

@@ -9,20 +9,43 @@ on:
       - ".github/workflows/publish-docs.yml"
 
 jobs:
-  gh-release:
+  build:
+    name: Build Docusaurus
     runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: docusaurus
     steps:
       - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
       - uses: actions/setup-node@v4
         with:
-          node-version: "20"
+          node-version: 20
+          cache: npm
+          cache-dependency-path: docusaurus/package-lock.json
+
+      - name: Install dependencies
+        run: npm ci
       - name: Build
-        run: |
-          cd docusaurus
-          npm ci
-          npm run build
-      - name: Deploy
-        uses: peaceiris/actions-gh-pages@v3
-        with:
-          github_token: ${{ secrets.GITHUB_TOKEN }}
-          publish_dir: ./docusaurus/build
+        run: npm run build
+
+  deploy:
+    name: Deploy to GitHub Pages
+    needs: build
+
+    # Grant GITHUB_TOKEN the permissions required to make a Pages deployment
+    permissions:
+      pages: write # to deploy to Pages
+      id-token: write # to verify the deployment originates from an appropriate source
+
+    # Deploy to the github-pages environment
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+
+    runs-on: ubuntu-latest
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

.github/workflows/test-publish-docs.yaml

@@ -0,0 +1,30 @@
+name: Test deployment
+
+on:
+  pull_request:
+    branches:
+      - main
+    # Review gh actions docs if you want to further define triggers, paths, etc
+    # https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#on
+
+jobs:
+  test-deploy:
+    name: Test deployment
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: docusaurus
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: npm
+          cache-dependency-path: docusaurus/package-lock.json
+
+      - name: Install dependencies
+        run: npm ci
+      - name: Test build website
+        run: npm run build

.vscode/settings.json

@@ -0,0 +1,13 @@
+{
+  "[javascript]": {
+    "editor.defaultFormatter": "esbenp.prettier-vscode"
+  },
+  "[javascriptreact]": {
+    "editor.defaultFormatter": "esbenp.prettier-vscode"
+  },
+  "[mdx]": {
+    "editor.formatOnSave": false
+  },
+  "editor.defaultFormatter": "esbenp.prettier-vscode",
+  "editor.formatOnSave": true
+}

docusaurus/docusaurus.config.js → docusaurus/docusaurus.config.ts

@@ -1,4 +1,10 @@
-module.exports = {
+import type { Config } from '@docusaurus/types';
+import type * as Preset from '@docusaurus/preset-classic';
+
+const config: Config = {
+  future: {
+    experimental_faster: true,
+  },
   title: 'Create Intility App',
   tagline: 'Easy to use templates for Intility developers',
   url: 'https://create.intility.app/',
@@ -102,13 +108,13 @@ module.exports = {
       ],
       copyright: `Copyright © ${new Date().getFullYear()} Intility AS. Built with Docusaurus.`,
     },
-  },
+  } satisfies Preset.ThemeConfig,
   presets: [
     [
       '@docusaurus/preset-classic',
       {
         docs: {
-          sidebarPath: require.resolve('./sidebarsReact.js'),
+          sidebarPath: undefined,
           id: 'react',
           path: 'react',
           routeBasePath: 'react',
@@ -119,7 +125,7 @@ module.exports = {
         theme: {
           customCss: require.resolve('./src/css/custom.css'),
         },
-      },
+      } satisfies Preset.Options,
     ],
   ],
   plugins: [
@@ -130,7 +136,7 @@ module.exports = {
         id: 'dotnet',
         path: 'dotnet',
         routeBasePath: 'dotnet',
-        sidebarPath: require.resolve('./sidebarsDotnet.js'),
+        sidebarPath: undefined,
         editUrl: 'https://github.com/Intility/templates/tree/main/docusaurus',
         sidebarCollapsible: false,
 
@@ -166,11 +172,13 @@ module.exports = {
         id: 'fastapi',
         path: 'fastapi',
         routeBasePath: 'fastapi',
-        sidebarPath: require.resolve('./sidebarsFastapi.js'),
+        sidebarPath: undefined,
         editUrl: 'https://github.com/Intility/templates/tree/main/docusaurus',
         sidebarCollapsible: false,
         // ... other options
       },
     ],
   ],
 };
+
+export default config;

docusaurus/dotnet/topics/configuration.mdx

@@ -73,7 +73,7 @@ Logging is provided by the external package `Intility.Logging.AspNetCore` in con
 continuous development of logging support centrally, as the infrastructure changes over time, alleviating you of this burden.
 
 :::note
-For more information about logging configurations visit the [Logging](./Logging) section.
+For more information about logging configurations visit the [Logging](./logging) section.
 :::
 
 ```json