added versioning to syllabus and added Release 1.0.1 to the versioned docs (#92)

Previews will include a version called `next` which is the current
working head.
Production Builds will only contain versioned version.


Adds Docusaurus docs versioning for the syllabus so that preview builds
include the current “next” docs while production builds publish only
released versions, and introduces the first released docs snapshot
(1.0.1).

**Changes:**
- Added `1.0.1` as the first versioned docs release (versions list,
versioned sidebars, and versioned docs content).
- Introduced preview vs production build modes via `DOCS_BUILD_MODE`,
plus corresponding npm scripts and CI workflow updates.
- Adjusted the remark code-block line-length check to skip
`versioned_docs` snapshots and added a docs version dropdown in the
navbar.

---------

Signed-off-by: René <snooz@posteo.de>
Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>

Author: Snooz82

.github/workflows/pr-preview-surge.yml

@@ -64,7 +64,7 @@ jobs:
         run: npm ci
 
       - name: Build
-        run: npm run build
+        run: npm run build:preview
 
       - name: Upload build artifact
         uses: actions/upload-artifact@v4

.github/workflows/release-pages.yml

@@ -18,6 +18,24 @@ jobs:
           ref: ${{ github.event.release.tag_name }}
           fetch-depth: 0
 
+      - name: Verify matching versioned docs exist
+        shell: bash
+        run: |
+          RELEASE_TAG="${{ github.event.release.tag_name }}"
+          # Strip a leading 'v' from the tag (e.g. v1.0.1 → 1.0.1)
+          VERSION="${RELEASE_TAG#v}"
+          DOCS_DIR="website/versioned_docs/version-${VERSION}"
+
+          if [[ ! -d "${DOCS_DIR}" ]]; then
+            echo "::error::Missing docs snapshot for release tag '${RELEASE_TAG}'."
+            echo "Expected directory: ${DOCS_DIR}"
+            echo "Available directories in website/versioned_docs:"
+            ls -1 website/versioned_docs || true
+            exit 1
+          fi
+
+          echo "Found matching docs directory: ${DOCS_DIR}"
+
       - name: Use Node.js
         uses: actions/setup-node@v4
         with:
@@ -31,7 +49,7 @@ jobs:
 
       - name: Build website
         working-directory: ./website
-        run: npm run build
+        run: npm run build:production
 
       - name: Deploy to gh-pages
         uses: peaceiris/actions-gh-pages@v3

website/README.md

@@ -30,6 +30,20 @@ $ npm run build
 
 This command generates static content into the `build` directory and can be served using any static contents hosting service.
 
+Build modes:
+
+```
+$ npm run build:preview
+```
+
+Builds docs with both released versions and `next` content.
+
+```
+$ npm run build:production
+```
+
+Builds docs with released versions only (hides `next`).
+
 ### Deployment
 
 Using SSH:

website/docusaurus.config.ts

@@ -1,15 +1,21 @@
-// @ts-check
-// Note: type annotations allow type checking and IDEs autocompletion
-
-const lightCodeTheme = require('prism-react-renderer').themes.vsLight;
-const darkCodeTheme = require('prism-react-renderer').themes.dracula;
+import { themes as prismThemes } from 'prism-react-renderer';
 import remarkDirective from "remark-directive";
 import remarkTermDirective from "./src/remark/remark-term-directive.js";
 import codeMaxLineLength from './src/remark/remark-code-max-line-length.js';
+import type { Config } from '@docusaurus/types';
+import type * as Preset from '@docusaurus/preset-classic';
+
+const rawDocsBuildMode = process.env.DOCS_BUILD_MODE ?? 'preview';
 
+if (!['preview', 'production'].includes(rawDocsBuildMode)) {
+  throw new Error(
+    `Invalid DOCS_BUILD_MODE: "${rawDocsBuildMode}". Expected "preview" or "production".`,
+  );
+}
 
-/** @type {import('@docusaurus/types').Config} */
-const config = {
+const includeCurrentVersion = rawDocsBuildMode === 'preview';
+
+const config: Config = {
   title: 'Syllabus of Robot Framework® Certified Professional',
   tagline: 'The foundation for the "Robot Framework® Certified Professional" (RFCP®) exam and training',
   url: 'https://robotframework.org',
@@ -25,105 +31,111 @@ const config = {
   future: {
     v4: true, // Improve compatibility with the upcoming Docusaurus v4
   },
-  organizationName: 'robotframework', // Usually your GitHub org/user name.
-  projectName: 'robotframework-RFCP-syllabus', // Usually your repo name.
+  organizationName: 'robotframework',
+  projectName: 'robotframework-RFCP-syllabus',
   trailingSlash: false,
   presets: [
     [
       'classic',
-      /** @type {import('@docusaurus/preset-classic').Options} */
       ({
         docs: {
+          includeCurrentVersion,
           admonitions: {
             keywords: ['lo', 'K1', 'K2', 'K3', 'note', 'tip', 'info', 'warning', 'danger'],
             extendDefaults: true,
           },
-          routeBasePath: '/docs',
-          sidebarPath: require.resolve('./sidebars.js'),
-          // Please change this to your repo.
-          // editUrl: 'https://github.com/robotframework/robotframework-RFCP-syllabus/edit/docusaurus/website',
+          sidebarPath: './sidebars.ts',
           remarkPlugins: [remarkDirective, remarkTermDirective, [codeMaxLineLength, { max: 100 }]],
         },
         blog: false,
         theme: {
-          customCss: require.resolve('./src/css/custom.css'),
+          customCss: './src/css/custom.css',
         },
-      }),
+      } satisfies Preset.Options),
     ],
   ],
-  themeConfig:
-    /** @type {import('@docusaurus/preset-classic').ThemeConfig} */
-    ({
-      colorMode: {
-        defaultMode: 'dark',
-        disableSwitch: false,
-        respectPrefersColorScheme: false,
+  themeConfig: ({
+    colorMode: {
+      defaultMode: 'dark',
+      disableSwitch: false,
+      respectPrefersColorScheme: true,
+    },
+    navbar: {
+      title: 'RFCP-Syllabus',
+      logo: {
+        alt: 'Robot Framework Logo',
+        src: 'img/robot-framework.svg',
+        srcDark: 'img/robot-framework-dark.svg',
       },
-      navbar: {
-        title: 'RFCP-Syllabus',
-        logo: {
-          alt: 'Robot Framework Logo',
-          src: 'img/robot-framework.svg',
-          srcDark: 'img/robot-framework-dark.svg',
+      items: [
+        {
+          type: 'doc',
+          docId: 'overview',
+          label: 'Introduction',
+          position: 'left',
         },
-        items: [
-          {
-            label: 'Introduction',
-            to: '/docs/overview',
-            position: 'left',
-          },
-          {
-            label: 'Chapter 1',
-            to: '/docs/chapter-01/overview',
-            position: 'left',
-          },
-          {
-            label: 'Chapter 2',
-            to: '/docs/chapter-02/overview',
-            position: 'left',
-          },
-          {
-            label: 'Chapter 3',
-            to: '/docs/chapter-03/overview',
-            position: 'left',
-          },
-          {
-            label: 'Chapter 4',
-            to: '/docs/chapter-04/overview',
-            position: 'left',
-          },
-          {
-            label: 'Chapter 5',
-            to: '/docs/chapter-05/overview',
-            position: 'left',
-          },
-          {
-            label: 'Example Exam',
-            to: '/docs/example-exam',
-            position: 'left',
-          },
-          {
-            label: 'LOs',
-            to: '/docs/learning_objectives',
-            position: 'left',
-          },
-        ],
-      },
-      footer: {
-        style: 'dark',
-        links: [
-        ],
-        copyright: `Copyright © ${new Date().getFullYear()} Robot Framework® Foundation - Syllabus of Robot Framework® Certified Professional`,
-      },
-      prism: {
-        theme: lightCodeTheme,
-        darkTheme: darkCodeTheme,
-        additionalLanguages: ['robotframework', 'python'],
-      },
-    }),
+        {
+          type: 'doc',
+          docId: 'chapter-01/overview',
+          label: 'Chapter 1',
+          position: 'left',
+        },
+        {
+          type: 'doc',
+          docId: 'chapter-02/overview',
+          label: 'Chapter 2',
+          position: 'left',
+        },
+        {
+          type: 'doc',
+          docId: 'chapter-03/overview',
+          label: 'Chapter 3',
+          position: 'left',
+        },
+        {
+          type: 'doc',
+          docId: 'chapter-04/overview',
+          label: 'Chapter 4',
+          position: 'left',
+        },
+        {
+          type: 'doc',
+          docId: 'chapter-05/overview',
+          label: 'Chapter 5',
+          position: 'left',
+        },
+        {
+          type: 'doc',
+          docId: 'example-exam/Example-exam',
+          label: 'Example Exam',
+          position: 'left',
+        },
+        {
+          type: 'doc',
+          docId: 'learning_objectives',
+          label: 'LOs',
+          position: 'left',
+        },
+        {
+          type: 'docsVersionDropdown',
+          position: 'right',
+          dropdownActiveClassDisabled: true,
+        },
+      ],
+    },
+    footer: {
+      style: 'dark',
+      copyright: `Copyright © ${new Date().getFullYear()} Robot Framework® Foundation - Syllabus of Robot Framework® Certified Professional`,
+    },
+    prism: {
+      theme: prismThemes.vsLight,
+      darkTheme: prismThemes.dracula,
+      additionalLanguages: ['robotframework', 'python'],
+    },
+  } satisfies Preset.ThemeConfig),
   plugins: [
-    require.resolve('docusaurus-lunr-search')
+    'docusaurus-lunr-search',
   ],
 };
 
-module.exports = config;
+export default config;