diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 00000000..c29e0e68 --- /dev/null +++ b/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) diff --git a/docs/intro.md b/docs/intro.md deleted file mode 100644 index 8a2e69d9..00000000 --- a/docs/intro.md +++ /dev/null @@ -1,47 +0,0 @@ ---- -sidebar_position: 1 ---- - -# Tutorial Intro - -Let's discover **Docusaurus in less than 5 minutes**. - -## Getting Started - -Get started by **creating a new site**. - -Or **try Docusaurus immediately** with **[docusaurus.new](https://docusaurus.new)**. - -### What you'll need - -- [Node.js](https://nodejs.org/en/download/) version 16.14 or above: - - When installing Node.js, you are recommended to check all checkboxes related to dependencies. - -## Generate a new site - -Generate a new Docusaurus site using the **classic template**. - -The classic template will automatically be added to your project after you run the command: - -```bash -npm init docusaurus@latest my-website classic -``` - -You can type this command into Command Prompt, Powershell, Terminal, or any other integrated terminal of your code editor. - -The command also installs all necessary dependencies you need to run Docusaurus. - -## Start your site - -Run the development server: - -```bash -cd my-website -npm run start -``` - -The `cd` command changes the directory you're working with. In order to work with your newly created Docusaurus site, you'll need to navigate the terminal there. - -The `npm run start` command builds your website locally and serves it through a development server, ready for you to view at http://localhost:3000/. - -Open `docs/intro.md` (this page) and edit some lines: the site **reloads automatically** and displays your changes. diff --git a/docusaurus.config.js b/docusaurus.config.js index 6da0b8a3..9940db91 100644 --- a/docusaurus.config.js +++ b/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'), }, diff --git a/docusaurus.config.utils.js b/docusaurus.config.utils.js new file mode 100644 index 00000000..12615747 --- /dev/null +++ b/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', + }, + } +}