chore: improve dev dx

docs/index.md

@@ -0,0 +1,14 @@
+# Developer Mode
+
+This page is for Development **only**.
+
+To see this page, set your local environment variable `NODE_ENV` to `development`.
+
+```
+NODE_ENV=development npm run start
+```
+
+## How it works
+
+- If you have multiple versions of the same major release in the `versions.json` file, only one minor release for each major release will be shown in the dropdown
+- If you have an empty `versions.json` file, you will see the `/docs` folder (and this page)

docusaurus.config.js

@@ -1,12 +1,17 @@
 // @ts-check
-// Note: type annotations allow type checking and IDEs autocompletion
 
 const lightCodeTheme = require('prism-react-renderer/themes/github')
 const darkCodeTheme = require('prism-react-renderer/themes/dracula')
 
+const u = require('./docusaurus.config.utils')
+
 const versions = require('./versions.json')
 
-const BASE_URL = process.env.BASE_URL || '/'
+const BASE_URL = process.env.BASE_URL ?? '/'
+
+const isDev = process.env.NODE_ENV === 'development'
+
+u.checkGeneratedData()
 
 /** @type {import('@docusaurus/types').Config} */
 const config = {
@@ -19,8 +24,8 @@ const config = {
   favicon: 'img/favicon.ico',
 
   // GitHub pages deployment config.
-  organizationName: 'fastify', // Usually your GitHub org/user name.
-  projectName: 'website-next', // Usually your repo name.
+  organizationName: 'fastify',
+  projectName: 'website-next',
 
   i18n: {
     defaultLocale: 'en',
@@ -33,6 +38,8 @@ const config = {
       'classic',
       /** @type {import('@docusaurus/preset-classic').Options} */
       ({
+        debug: true, // force debug plugin usage
+
         // https://docusaurus.io/docs/api/plugins/@docusaurus/plugin-content-docs#configuration
         docs: {
           editUrl: (editPage) => {
@@ -43,16 +50,9 @@ const config = {
           sidebarPath: 'sidebar.js',
           showLastUpdateTime: true,
           breadcrumbs: true,
-          includeCurrentVersion: false,
-          versions: {
-            [versions[0]]: {
-              path: 'latest',
-              label: `latest (${versions[1]})`,
-            },
-            [versions[1]]: {
-              banner: 'none',
-            },
-          },
+          includeCurrentVersion: isDev,
+          versions: u.getVersionLabels(versions),
+          onlyIncludeVersions: u.getVersionsIncluded({ versions, fastBuild: isDev }),
           sidebarItemsGenerator: require('./sidebar.js'),
         },
 

docusaurus.config.utils.js

@@ -0,0 +1,72 @@
+'use strict'
+
+const fs = require('fs')
+const path = require('path')
+
+module.exports = {
+  checkGeneratedData,
+  getVersionLabels,
+  getVersionsIncluded,
+}
+
+/**
+ * Throws an error if any of the generated files is missing.
+ */
+function checkGeneratedData() {
+  const generatedFiles = [
+    'static/generated/acknowledgements.json',
+    'static/generated/benchmarks.json',
+    'static/generated/organisations.json',
+    'static/generated/plugins.json',
+    'static/generated/team.json',
+  ]
+
+  generatedFiles.forEach((file) => {
+    const filePath = path.resolve(__dirname, file)
+    if (!fs.existsSync(filePath)) {
+      throw new Error(`Missing generated file: ${file}. Run the "npm run build:website" once.`)
+    }
+  })
+}
+
+/**
+ * Removes all the minor versions from the versions array, leaving only the major ones.
+ */
+function getVersionsIncluded({ fastBuild, versions }) {
+  if (fastBuild && versions.length > 1) {
+    const groupBy = versions.reduce(
+      (group, v) => {
+        const major = v.split('.')[0]
+        if (!group[major]) {
+          group[major] = v
+          group.out.push(v)
+        }
+        return group
+      },
+      { out: [] },
+    )
+
+    return groupBy?.out
+  }
+
+  return undefined
+}
+
+/**
+ * Rename the latest numeric version to `latest` to let Docusaurus handles routing.
+ */
+function getVersionLabels(versionsJson) {
+  if (versionsJson.length < 2) {
+    return {}
+  }
+
+  return {
+    [versionsJson[0]]: {
+      path: 'latest',
+      label: `latest (${versionsJson[1]})`,
+    },
+    [versionsJson[1]]: {
+      banner: 'none',
+    },
+  }
+}