major: Docusaurus v3 upgrade (#223)

.gitignore

@@ -32,3 +32,5 @@ versioned_sidebars/*
 !versioned_sidebars/.keep
 
 static/generated/*.json
+versions-shipped.json
+versions.json

README.md

@@ -44,11 +44,9 @@ By running `npm run serve`, you will load locally the production build from the
 $ npm start
 ```
 
-This command starts a local development server and opens up a browser window.
-Most changes are reflected live without having to restart the server.
+This command starts a local development server and opens up a browser window. Most changes are reflected live without having to restart the server.
 
-Note that only the documentations listed in the `versions.json` file will be available.
-So, if you have a long version list, your local enviroment will be slowed down.
+Note that only the documentations listed in the `versions.json` file will be available. So, if you have a long version list, your local enviroment will be slowed down.
 
 ### Deployment
 

docusaurus.config.js

@@ -1,7 +1,7 @@
 // @ts-check
-
-const lightCodeTheme = require('prism-react-renderer/themes/github')
-const darkCodeTheme = require('prism-react-renderer/themes/dracula')
+const { themes } = require('prism-react-renderer')
+const lightCodeTheme = themes.github
+const darkCodeTheme = themes.dracula
 
 const u = require('./docusaurus.config.utils')
 
@@ -10,7 +10,7 @@ const versions = require('./versions.json')
 const BASE_URL = process.env.BASE_URL ?? '/'
 
 const isDev = process.env.NODE_ENV === 'development'
-const latestMajorVersion = versions.find((v) => v.startsWith('v'))?.split('.')[0] || 'v4'
+const latestMajorVersion = versions.find((v) => v.startsWith('v'))?.split('.')[0] || 'v5'
 
 u.checkGeneratedData()
 
@@ -200,7 +200,7 @@ const config = {
     }),
 
   plugins: [
-    '@orama/plugin-docusaurus',
+    '@orama/plugin-docusaurus-v3',
     [
       // This plugin does not work in dev mode
       '@docusaurus/plugin-client-redirects',

docusaurus.config.utils.js

@@ -72,6 +72,14 @@ function getVersionLabels(versionsJson) {
   }
 }
 
+/**
+ * Generate redirects for old versions of the documentation.
+ * @param {string} existingPath - The path to redirect.
+ * @param {string} major - The major version.
+ * @param {Array<string>} versions - The list of versions.
+ * @param {Array<string>} versionsShipped - The list of versions shipped.
+ * @param {Array<string>} ignore - The list of paths to ignore.
+ */
 function manageRedirects({ existingPath, major, versions, versionsShipped, ignore = [] }) {
   if (ignore.includes(existingPath)) {
     //  Do not create redirects for this path

package.json

@@ -25,32 +25,32 @@
     "lint:style:fix": "npm run lint:style -- --fix"
   },
   "dependencies": {
-    "@docusaurus/core": "^2.4.3",
-    "@docusaurus/plugin-client-redirects": "^2.4.3",
-    "@docusaurus/preset-classic": "^2.4.3",
-    "@mdx-js/react": "^1.6.22",
-    "@orama/plugin-docusaurus": "^2.0.16",
-    "clsx": "^1.2.1",
-    "prism-react-renderer": "^1.3.5",
-    "react": "^17.0.2",
-    "react-dom": "^17.0.2",
+    "@docusaurus/core": "^3.3.2",
+    "@docusaurus/plugin-client-redirects": "^3.6.3",
+    "@docusaurus/preset-classic": "^3.6.3",
+    "@mdx-js/react": "^3.1.0",
+    "@orama/plugin-docusaurus-v3": "^3.0.2",
+    "clsx": "^2.1.1",
+    "prism-react-renderer": "^2.4.0",
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1",
     "react-github-btn": "^1.4.0",
-    "react-markdown": "^8.0.7"
+    "react-markdown": "^9.0.1"
   },
   "devDependencies": {
-    "@docusaurus/eslint-plugin": "^2.4.3",
-    "@docusaurus/module-type-aliases": "^2.3.1",
-    "@fastify/pre-commit": "^2.1.0",
+    "@docusaurus/eslint-plugin": "^3.6.3",
+    "@docusaurus/module-type-aliases": "^3.3.2",
+    "@fastify/pre-commit": "^2.2.0",
     "babel-eslint": "^10.1.0",
-    "eslint": "^8.57.0",
+    "eslint": "^8.57.1",
     "eslint-config-prettier": "^9.1.0",
     "eslint-plugin-check-file": "^2.8.0",
-    "eslint-plugin-import": "^2.29.1",
+    "eslint-plugin-import": "^2.31.0",
     "eslint-plugin-mdx": "^3.1.5",
-    "eslint-plugin-react": "^7.34.1",
-    "eslint-plugin-react-hooks": "^4.6.0",
-    "eslint-plugin-regexp": "^2.5.0",
-    "prettier": "^3.2.5",
+    "eslint-plugin-react": "^7.37.2",
+    "eslint-plugin-react-hooks": "^4.6.2",
+    "eslint-plugin-regexp": "^2.7.0",
+    "prettier": "^3.4.1",
     "stylelint": "^14.16.1",
     "stylelint-config-prettier": "^9.0.5",
     "stylelint-config-standard": "^29.0.0"
@@ -68,7 +68,7 @@
     ]
   },
   "engines": {
-    "node": ">=16.14"
+    "node": ">=18.0"
   },
   "pre-commit": {
     "run": [

scripts/download-releases.sh

@@ -19,8 +19,14 @@ releaseFile="$baseDir/releases.tag"
 
 downloadRelease() {
   outputFile="$baseDir/downloads/$1.tar.gz"
-  gh release download "v$1" --repo $repo --archive=tar.gz -O $outputFile --skip-existing
-  echo "Downloaded $repo > $1"
+
+  # if the file already exists, skip
+  if [ -f $outputFile ]; then
+    echo "Skipped $repo > $1"
+  else
+    gh release download "v$1" --repo $repo --archive=tar.gz -O $outputFile --skip-existing
+    echo "Downloaded $repo > $1"
+  fi
 
   mkdir -p "$baseDir/releases/$1/"
   mkdir -p "$baseDir/downloads/$1/"

scripts/process-docusaurus-v3-upgrade.js

@@ -0,0 +1,59 @@
+'use strict'
+
+const { join } = require('node:path')
+const replace = require('replace')
+
+function processDocusaurusV3Upgrade(dir) {
+  // global updates
+  // adding spacing between <[ characters
+
+  replace({
+    regex: /<\[/g,
+    replacement: '< [',
+    paths: [dir],
+    includes: join(dir, `*`),
+    recursive: true,
+    silent: false,
+  })
+
+  // In case of errors, just check what is wrong with this playground:
+  // https://mdxjs.com/playground/
+  const edits = [
+    {
+      inFile: 'TypeScript.md',
+      from: 'fastify.preSerializationHookHandler<PreSerializationPayload',
+      to: 'fastify.preSerializationHookHandler< PreSerializationPayload',
+    },
+
+    {
+      inFile: 'TypeScript.md',
+      from: 'fastify.onSendHookHandler<OnSendPayload',
+      to: 'fastify.onSendHookHandler< OnSendPayload',
+    },
+
+    {
+      inFile: 'TypeScript.md',
+      from: '& { path: string; prefix',
+      to: '& \\{ path: string; prefix',
+    },
+
+    {
+      inFile: 'Server.md',
+      from: '</a> option is set.',
+      to: '</a> \noption is set.',
+    },
+  ]
+
+  for (const edit of edits) {
+    replace({
+      paths: [dir],
+      regex: edit.from,
+      replacement: edit.to,
+      includes: edit.inFile,
+      recursive: true,
+      silent: false,
+    })
+  }
+}
+
+module.exports = processDocusaurusV3Upgrade

scripts/process-releases.js

@@ -13,6 +13,7 @@ const replace = require('replace')
 const prependFile = require('prepend-file')
 
 const sidebarsTemplate = require('../sidebars-template.json')
+const processDocusaurusV3Upgrade = require('./process-docusaurus-v3-upgrade')
 const log = require('pino')({
   level: process.env.LOG_LEVEL || 'debug',
   transport: {
@@ -112,6 +113,9 @@ async function processReleases(opts) {
   const v2Docs = orderedVersions.find((v) => v.startsWith('v2.'))
   await fixCodeBlocks(join(versionedFolder, `version-${v2Docs}`))
 
+  processDocusaurusV3Upgrade(versionedFolder)
+  log.info('Updated docs to match Docusaurus v3 guidelines')
+
   log.info('Done')
 }
 

src/components/BenchmarkInfo/index.jsx

@@ -1,6 +1,6 @@
 import React from 'react'
 import styles from './styles.module.css'
-
+import Heading from '@theme/Heading'
 import Link from '@docusaurus/Link'
 
 function BenchmarkInfo({ name, test: testFile, repository, req, progressValue }) {
@@ -9,7 +9,7 @@ function BenchmarkInfo({ name, test: testFile, repository, req, progressValue })
       <div className={styles.level}>
         <div>
           <Link to={testFile}>
-            <h2>{name}</h2>
+            <Heading as={'h2'}>{name}</Heading>
           </Link>
         </div>
         <div>

src/components/HeroBanner/index.jsx

@@ -1,11 +1,13 @@
 import React from 'react'
-
+import Heading from '@theme/Heading'
 // TODO: will applies some styling
 
 function HeroBanner({ title }) {
   return (
     <header className="hero-banner">
-      <h1 className="hero-title">{title}</h1>
+      <Heading as={'h1'} className="hero-title">
+        {title}
+      </Heading>
     </header>
   )
 }

src/components/HomePageHeader/index.jsx

@@ -1,4 +1,5 @@
 import React from 'react'
+import Heading from '@theme/Heading'
 
 import useDocusaurusContext from '@docusaurus/useDocusaurusContext'
 import GitHubButton from 'react-github-btn'
@@ -13,7 +14,7 @@ function HomepageHeader() {
       <div className="container">
         <img alt={siteConfig.title} src={`img/logos/fastify-white.svg`} />
 
-        <h2>{siteConfig.tagline}</h2>
+        <Heading as={'h2'}>{siteConfig.tagline}</Heading>
 
         <div>
           <GitHubButton

src/components/Organisations/index.jsx

@@ -1,5 +1,6 @@
 import React from 'react'
 import useBaseUrl from '@docusaurus/useBaseUrl'
+import Link from '@docusaurus/Link'
 
 import organizationsData from '@site/static/generated/organisations.json'
 import styles from './styles.module.css'
@@ -22,9 +23,9 @@ export default function Organisations({ maxItems, onlySponsors }) {
 
 function OrganizationItem({ organization }) {
   return (
-    <a href={organization.link} target="_blank" rel="noreferrer" className={getOrganizationStyle(organization)}>
+    <Link href={organization.link} target="_blank" rel="noreferrer" className={getOrganizationStyle(organization)}>
       <img src={useBaseUrl(`/img/organisations/${organization.image}`)} alt={`${organization.name} is using Fastify`} />
-    </a>
+    </Link>
   )
 }
 

src/components/QuickStart/index.jsx

@@ -3,6 +3,7 @@ import Tabs from '@theme/Tabs'
 import TabItem from '@theme/TabItem'
 import CodeBlock from '@theme/CodeBlock'
 import Link from '@docusaurus/Link'
+import Heading from '@theme/Heading'
 
 export default function QuickStart() {
   const esm = `// Import the framework and instantiate it
@@ -165,7 +166,7 @@ start()`
 
   return (
     <>
-      <h1>Quick start</h1>
+      <Heading as={'h1'}>Quick start</Heading>
       <p>Get Fastify with NPM:</p>
 
       <CodeBlock language="bash">npm install fastify</CodeBlock>
@@ -187,7 +188,7 @@ start()`
       <p>and test it with:</p>
       <CodeBlock language="bash">curl http://localhost:3000</CodeBlock>
 
-      <h2>Using CLI</h2>
+      <Heading as={'h2'}>Using CLI</Heading>
       <p>
         Get the{' '}
         <Link to="https://github.com/fastify/fastify-cli">
@@ -202,7 +203,7 @@ start()`
         fastify generate myproject
       </CodeBlock>
 
-      <h2>Request/Response validation and hooks</h2>
+      <Heading as={'h2'}>Request/Response validation and hooks</Heading>
       <p>
         Fastify can do much more than this. For example, you can easily provide input and output validation using JSON
         Schema and perform specific operations before the handler is executed:
@@ -216,7 +217,7 @@ start()`
         </TabItem>
       </Tabs>
 
-      <h2>TypeScript Support</h2>
+      <Heading as={'h2'}>TypeScript Support</Heading>
       <p>
         Fastify is shipped with a typings file, but you may need to install <code>@types/node</code>, depending on the
         Node.js version you are using.

src/components/Team/index.jsx

@@ -1,4 +1,6 @@
 import React from 'react'
+import Link from '@docusaurus/Link'
+import Heading from '@theme/Heading'
 
 import teamData from '@site/static/generated/team.json'
 import styles from './styles.module.css'
@@ -54,7 +56,7 @@ function buildGroup(section, index) {
   return (
     <div key={index}>
       <div className="content">
-        <h2>{section.name}</h2>
+        <Heading as={'h2'}>{section.name}</Heading>
       </div>
       <div className="row">{section.people.map((member, index) => TeamMember({ member, index }))}</div>
     </div>
@@ -79,34 +81,34 @@ function TeamMember({ member, index }) {
             <p>{member.name}</p>
             <p>
               {member.links.github && (
-                <a
+                <Link
                   href={member.links.github}
                   target="_blank"
                   rel="noreferrer"
                   className={styles.linkGithub}
                   title={`Check out ${member.name}'s Github profile`}>
                   {svgicons.github}
-                </a>
+                </Link>
               )}
               {member.links.npm && (
-                <a
+                <Link
                   href={member.links.npm}
                   target="_blank"
                   rel="noreferrer"
                   className={styles.linkNpm}
                   title={`Check out ${member.name}'s NPM profile`}>
                   {svgicons.npm}
-                </a>
+                </Link>
               )}
               {member.links.twitter && (
-                <a
+                <Link
                   href={member.links.twitter}
                   target="_blank"
                   className={styles.linkTwitter}
                   rel="noreferrer"
                   title={`Check out ${member.name}'s Twitter profile`}>
                   {svgicons.twitter}
-                </a>
+                </Link>
               )}
             </p>
           </div>

src/pages/contribute.mdx

@@ -4,8 +4,7 @@ import GoodFirstIssue from '@site/src/components/GoodFirstIssue'
 
 <HeroBanner title="Join the Fastify community" />
 
-Fastify is a growing and friendly community, and would be lucky to have your contributions! 🙇‍♂️
-Contributions are always welcome, we only ask you to follow the [Contribution Guidelines](https://github.com/fastify/fastify/blob/master/CONTRIBUTING.md) and the [Code Of Conduct](https://github.com/fastify/fastify/blob/master/CODE_OF_CONDUCT.md).
+Fastify is a growing and friendly community, and would be lucky to have your contributions! 🙇‍♂️ Contributions are always welcome, we only ask you to follow the [Contribution Guidelines](https://github.com/fastify/fastify/blob/master/CONTRIBUTING.md) and the [Code Of Conduct](https://github.com/fastify/fastify/blob/master/CODE_OF_CONDUCT.md).
 
 If you don't know where to start, you can have a look at the list of **good first issues** below.