diff --git a/docs/configure/search.md b/docs/configure/search.md index 66ff4a8..3cc2604 100644 --- a/docs/configure/search.md +++ b/docs/configure/search.md @@ -18,7 +18,7 @@ the conditions as long as the docs are open source. This page contains instructions for configuring Algolia for both [open-source](#docs-and-source-code-are-open-source) and [closed-source](#source-code-is-not-open-source) projects. -## Docs and source code are open source +## For an open source codebase Follow these steps to configure Algolia in your project: @@ -50,7 +50,7 @@ Follow these steps to configure Algolia in your project: Edit the `docs` index in the file to match your repository's index in Algolia. This workflow runs in the background and populates the index that Algolia uses to search. -## Source code is not open source +## For a close source code base If your project doesn't satisfy the [Algolia checklist](https://docsearch.algolia.com/docs/who-can-apply/), then you can't use Algolia for free. diff --git a/docs/configure/versioning/index.md b/docs/configure/versioning/index.md index 05a3752..c890100 100644 --- a/docs/configure/versioning/index.md +++ b/docs/configure/versioning/index.md @@ -3,28 +3,154 @@ description: Support and manage multiple documentation versions. sidebar_position: 1 --- -# Configure versioning +# Configure and use versioning Docusaurus can manage multiple versions of your documentation. See the [Docusaurus versioning documentation](https://docusaurus.io/docs/next/versioning) for detailed context and instructions on managing versions. -## Create a docs version +The following instructions are for documentation that uses n versions that can be accessed like so: + +| Path | Version | URL | +|:----------------------------------- |:------------- |:-------------------| +|versioned_docs/version-22.x/hello.md | 22.x | /22.x/hello | +|versioned_docs/version-23.x/hello.md | 23.x (latest) | /hello | +|docs/hello.md | development | /development/hello | + +:::info +Please note that unlike Read the Docs (RTD) that versions by tags on the code base, in Docusaurus, +every version in history is kept in the `versioned_docs` folder, so the onus is on you to remove +older versions when required +::: + +Docusaurus nomenclature is slightly different to what we use. In docusaurus, any version +(i.e. a subfolder in `versioned_docs`) is deeemed stable; and the next version is therefore called +`next` (the next stable version). In Consensys we follow the same for the `versioned_docs` but use the +term `development` instead, and this can be configured in docusaurus.config.js like so, where +the `current` version is given a `label` and `path` attribute. + +```js +... + routeBasePath: "/", + path: "./docs", + includeCurrentVersion: true, + lastVersion: "23.x", + versions: { + //defaults to the ./docs folder + // using 'development' instead of 'next' as path + current: { + label: "development", + path: "development", + }, + //the last stable release in the versioned_docs/version-stable + "23.x": { + label: "stable (23.x)", + }, + "22.x": { + label: "22.x", + }, + }, +... +``` + +## Release a new docs version + +### 1. Create a new version of the documentation: + +In the following steps, we'll release the `23.x` version of the documentation (from `22.x`) as an example. + + -Release version 1.0 of your docs using the following command: +# Syntax ```bash -npm run docusaurus docs:version 1.0 +npm run docusaurus docs:version ``` -The `docs` folder is copied into `versioned_docs/version-1.0` and `versions.json` is created. +# Example + +```bash +npm run docusaurus docs:version 23.x +``` + + + +This command: + +- Copies the full `docs/` directory into a new `version-` directory in the `versioned_docs` directory. +- Creates a new `versioned_sidebars/version--sidebars.json` file. +- Appends the new version number to the `versions.json` file. Your docs now have two versions: -- `1.0` at `http://localhost:3000/docs/` for the version 1.0 docs -- `current` at `http://localhost:3000/docs/next/` for the upcoming, unreleased docs. +- `23.x` at `http://localhost:3000/` for the version 23.x docs +- `current` at `http://localhost:3000/next/` for the upcoming, unreleased docs. + +### 2. Update the `docusaurus.config.js` file to re-label these paths + +In `docusaurus.config.js`, under `presets` > `classic` > `docs`: + +- Update the `lastVersion` to the new version number. +- Under `versions`, update the current version to the new version. + +For example, when releasing version `23.x` (from `23.x`), update the following section in the `docusaurus.config.js` +file by updating the version number: + +```js +presets: [ + [ + "classic", + { + docs: { + sidebarPath: require.resolve("./sidebars.js"), + // Set a base path separate from default /docs + editUrl: "https://github.com/ConsenSys/doc.teku/tree/master/", + routeBasePath: "/", + path: "./docs", + includeCurrentVersion: true, + // highlight-next-line + lastVersion: "23.3.x", + versions: { + //defaults to the ./docs folder + // using 'development' instead of 'next' as path + current: { + label: "development", + path: "development", + }, + //the last stable release in the versioned_docs/version-23.x + // highlight-start + "23.x": { + label: "stable (23.x)", + }, + // highlight-end + }, +... +], + +``` + +### 3. Update the `versions.json` file + +:::info +Please remember to remove any old versions that you are not required +::: + +```json +[ + "23.x" +] +``` + +### 4. Delete the previous doc versions (if needed) + +If you have deleted a version in step 3, also delete the artifacts for that version. For example, if deleting version `22.x` that would mean deleting the following: + +1. In the `versioned_docs` directory, delete the `version-22.x` folder +2. In the `versioned_sidebars` directory, delete the `version-22.x-sidebars.json` file. + +Create your pull request. You can perform a final check using the preview link generated for your PR. -## Add a version dropdown +### 5. Add a version dropdown (Do this once only when versioning is introduced) To navigate seamlessly across versions, add a version dropdown by modifying `docusaurus.config.js` as follows: @@ -57,5 +183,5 @@ The docs version dropdown appears in your navbar: You can edit versioned docs in their respective folder: -- `versioned_docs/version-1.0/hello.md` updates `http://localhost:3000/docs/hello`. +- `versioned_docs/version-23.x/hello.md` updates `http://localhost:3000/docs/hello`. - `docs/hello.md` updates `http://localhost:3000/docs/next/hello`. diff --git a/docs/contribute/doc-release-process.md b/docs/contribute/doc-release-process.md deleted file mode 100644 index d34a061..0000000 --- a/docs/contribute/doc-release-process.md +++ /dev/null @@ -1,119 +0,0 @@ ---- -description: Release process for documentation that uses a versioning system. -sidebar_position: 8 ---- - -# Documentation release process - -The following instructions are for documentation that uses the Docusaurus versioning system. - -:::info -Currently, only the Teku documentation utilizes versioning, supporting just two versions: `stable` and `development`. -This means previous releases must be removed as part of the release process. -::: - -A new stable version of the documentation is released when a new version of the software is released. -In the following example we'll release the `23.6.3` version of the documentation (from `23.6.2`). - -## Steps - -You'll need to create a documentation pull request with the following changes: - -### 1. Create a new version of the documentation: - -Create a new documentation version by running the following command: - - - -# Syntax - -```bash -npm run docusaurus docs:version -``` - -# Example - -```bash -npm run docusaurus docs:version 23.6.3 -``` - - - -This command: - -- Copies the full `docs/` directory into a new `version-` directory in the `versioned_docs` directory. -- Creates a new `versioned_sidebars/version--sidebars.json` file -- Appends the new version number to the `versions.json` file. - -### 2. Update the `docusaurus.config.js` file - -In `docusaurus.config.js`, under `presets` > `classic` > `docs`: - -- Update the `lastVersion` to the new version number. -- Under `versions`, update the current stable version to the new version - -For example, when releasing version `23.6.3` (from `23.6.2`), update the following section in the `docusaurus.config.js` -file by updating the version number: - -```javascript -presets: [ - [ - "classic", - { - docs: { - sidebarPath: require.resolve("./sidebars.js"), - // Set a base path separate from default /docs - editUrl: "https://github.com/ConsenSys/doc.teku/tree/master/", - routeBasePath: "/", - path: "./docs", - includeCurrentVersion: true, - // highlight-next-line - lastVersion: "23.6.3", - versions: { - //defaults to the ./docs folder - // using 'development' instead of 'next' as path - current: { - label: "development", - path: "development", - }, - //the last stable release in the versioned_docs/version-stable - // highlight-start - "23.6.3": { - label: "stable (23.6.3)", - }, - // highlight-end - }, -... -], - -``` - -### 3. Update the `versions.json` file - -Delete the previous version from the `versions.json` file: - -Before: - -```json -[ - "23.6.3", - "23.6.2" -] -``` - -After: - -```json -[ - "23.6.3" -] -``` - -### 4. Delete the previous doc versions - -Lastly, we'll cleanup the documentation directory by deleting the previous stable docs. For this example it means: - -1. In the `versioned_docs` directory, delete the `version-23.6.2` folder -2. In the `versioned_sidebars` directory, delete the `version-23.6.2-sidebars.json` file. - -Create your pull request. You can perform a final check using the Preview link that gets created for your PR. \ No newline at end of file diff --git a/docusaurus.config.js b/docusaurus.config.js index 197cb56..846e882 100644 --- a/docusaurus.config.js +++ b/docusaurus.config.js @@ -93,7 +93,24 @@ const config = { // Set a base path separate from default /docs editUrl: "https://github.com/ConsenSys/docs-template/tree/main/", routeBasePath: "/", - path: "docs", + path: "./docs", + includeCurrentVersion: true, + // lastVersion: "23.x", + // versions: { + // //defaults to the ./docs folder + // // using 'development' instead of 'next' as path + // current: { + // label: "development", + // path: "development", + // }, + // //the last stable release in the versioned_docs/version-stable + // "23.x": { + // label: "stable (23.x)", + // }, + // "22.x": { + // label: "22.x", + // }, + // }, // @ts-ignore // eslint-disable-next-line global-require remarkPlugins: [require("remark-docusaurus-tabs")], @@ -108,7 +125,6 @@ const config = { ], showLastUpdateAuthor: true, showLastUpdateTime: true, - includeCurrentVersion: true, }, theme: { customCss: require.resolve("./src/css/custom.css"), @@ -275,21 +291,6 @@ const config = { language: "nodejs", logoClass: "nodejs", }, - // { - // highlight: "ruby", - // language: "ruby", - // logoClass: "ruby", - // }, - // { - // highlight: "csharp", - // language: "csharp", - // logoClass: "csharp", - // }, - // { - // highlight: "php", - // language: "php", - // logoClass: "php", - // }, ], }), plugins: [ @@ -306,8 +307,33 @@ const config = { containerId: "GTM-", }, ], - ], // remove if not using docusaurus-plugin-openapi-docs - themes: [], // remove if not using docusaurus-plugin-openapi-docs + // This is how redirects are done + // [ + // "@docusaurus/plugin-client-redirects", + // { + // redirects: [ + // { + // from: "/HowTo/Get-Started/Installation-Options/Install-Binaries", + // to: "/get-started/install/install-binaries", + // }, + // ], + // // its quite odd here in that its back to front - replace(to, from) + // createRedirects(existingPath) { + // if (existingPath.includes("/development")) { + // return [ + // existingPath.replace("/development", "/en/latest"), + // existingPath.replace("/development", "/latest"), + // ]; + // } + // if (existingPath.includes("/")) { + // return [existingPath.replace("/", "/stable")]; + // } + // return undefined; // Return a falsy value: no redirect created + // }, + // }, + // ], + ], + themes: [], }; module.exports = config; diff --git a/package-lock.json b/package-lock.json index fc2c60b..e273c38 100644 --- a/package-lock.json +++ b/package-lock.json @@ -9,6 +9,7 @@ "version": "1.19.0", "dependencies": { "@docusaurus/core": "^2.4.1", + "@docusaurus/plugin-client-redirects": "^2.4.1", "@docusaurus/plugin-google-gtag": "^2.4.1", "@docusaurus/plugin-google-tag-manager": "^2.4.1", "@docusaurus/preset-classic": "^2.4.1", @@ -3057,6 +3058,42 @@ "react-dom": "*" } }, + "node_modules/@docusaurus/plugin-client-redirects": { + "version": "2.4.1", + "resolved": "https://registry.npmjs.org/@docusaurus/plugin-client-redirects/-/plugin-client-redirects-2.4.1.tgz", + "integrity": "sha512-tp0j16gaLIJ4p+IR0P6KDOFsTOGGMY54MNPnmM61Vaqqt5omLqsuKUO8UlCGU1oW/4EIQOhXYy99XYY5MjE+7A==", + "dependencies": { + "@docusaurus/core": "2.4.1", + "@docusaurus/logger": "2.4.1", + "@docusaurus/utils": "2.4.1", + "@docusaurus/utils-common": "2.4.1", + "@docusaurus/utils-validation": "2.4.1", + "eta": "^2.0.0", + "fs-extra": "^10.1.0", + "lodash": "^4.17.21", + "tslib": "^2.4.0" + }, + "engines": { + "node": ">=16.14" + }, + "peerDependencies": { + "react": "^16.8.4 || ^17.0.0", + "react-dom": "^16.8.4 || ^17.0.0" + } + }, + "node_modules/@docusaurus/plugin-client-redirects/node_modules/fs-extra": { + "version": "10.1.0", + "resolved": "https://registry.npmjs.org/fs-extra/-/fs-extra-10.1.0.tgz", + "integrity": "sha512-oRXApq54ETRj4eMiFzGnHWGy+zo5raudjuxN0b8H7s/RU2oW0Wvsx9O0ACRN/kRq9E8Vu/ReskGB5o3ji+FzHQ==", + "dependencies": { + "graceful-fs": "^4.2.0", + "jsonfile": "^6.0.1", + "universalify": "^2.0.0" + }, + "engines": { + "node": ">=12" + } + }, "node_modules/@docusaurus/plugin-content-blog": { "version": "2.4.1", "resolved": "https://registry.npmjs.org/@docusaurus/plugin-content-blog/-/plugin-content-blog-2.4.1.tgz", @@ -15412,6 +15449,8 @@ }, "node_modules/npm/node_modules/cross-spawn/node_modules/which": { "version": "2.0.2", + "resolved": "https://registry.npmjs.org/which/-/which-2.0.2.tgz", + "integrity": "sha512-BLI3Tl1TW3Pvl70l3yq3Y64i+awpwXqsGBYWkkqMtnbXgrMD+yj7rhW0kuEDxzJaYXGjEW5ogapKNMEKNMjibA==", "dev": true, "inBundle": true, "license": "ISC", @@ -15460,6 +15499,8 @@ }, "node_modules/npm/node_modules/debug/node_modules/ms": { "version": "2.1.2", + "resolved": "https://registry.npmjs.org/ms/-/ms-2.1.2.tgz", + "integrity": "sha512-sGkPx+VjMtmA6MX27oA4FBFELFCZZ4S4XqeGOXCv68tT+jb3vk/RyaKWP0PTKyWtmLSM0b+adUTEvbs1PEaH2w==", "dev": true, "inBundle": true, "license": "MIT" @@ -17277,6 +17318,8 @@ }, "node_modules/npm/node_modules/rimraf/node_modules/glob": { "version": "7.2.3", + "resolved": "https://registry.npmjs.org/glob/-/glob-7.2.3.tgz", + "integrity": "sha512-nFR0zLpU2YCaRxwoCJvL6UvCH2JFyFVIvwTLsIf21AuHlMskA1hhTdk+LlYJtOlYt9v6dvszD2BGRqBL+iQK9Q==", "dev": true, "inBundle": true, "license": "ISC", @@ -17341,6 +17384,8 @@ }, "node_modules/npm/node_modules/semver/node_modules/lru-cache": { "version": "6.0.0", + "resolved": "https://registry.npmjs.org/lru-cache/-/lru-cache-6.0.0.tgz", + "integrity": "sha512-Jo6dJ04CmSjuznwJSS3pUeWmd/H0ffTlkXXgwZi+eq1UCmqQwCh+eLsYOYCwY991i2Fah4h1BEMCx4qThGbsiA==", "dev": true, "inBundle": true, "license": "ISC", @@ -17808,6 +17853,8 @@ }, "node_modules/npm/node_modules/wrap-ansi/node_modules/ansi-styles": { "version": "6.2.1", + "resolved": "https://registry.npmjs.org/ansi-styles/-/ansi-styles-6.2.1.tgz", + "integrity": "sha512-bN798gFfQX+viw3R7yrGWRqnrN2oRkEkUjjl4JNn4E8GxxbjtG3FbrEIIY3l8/hrwUwIeCZvi4QuOTP4MErVug==", "dev": true, "inBundle": true, "license": "MIT", @@ -17828,6 +17875,8 @@ }, "node_modules/npm/node_modules/wrap-ansi/node_modules/string-width": { "version": "5.1.2", + "resolved": "https://registry.npmjs.org/string-width/-/string-width-5.1.2.tgz", + "integrity": "sha512-HnLOCR3vjcY8beoNLtcjZ5/nxn2afmME6lhrDrebokqMap+XbeW8n9TXpPDOqdGK5qcI3oT0GKTW6wC7EMiVqA==", "dev": true, "inBundle": true, "license": "MIT", diff --git a/package.json b/package.json index d552f44..5ba64d6 100644 --- a/package.json +++ b/package.json @@ -30,6 +30,7 @@ }, "dependencies": { "@docusaurus/core": "^2.4.1", + "@docusaurus/plugin-client-redirects": "^2.4.1", "@docusaurus/plugin-google-gtag": "^2.4.1", "@docusaurus/plugin-google-tag-manager": "^2.4.1", "@docusaurus/preset-classic": "^2.4.1", diff --git a/yarn.lock b/yarn.lock index 3ddc04b..113b1c8 100644 --- a/yarn.lock +++ b/yarn.lock @@ -1889,6 +1889,21 @@ react-helmet-async "*" react-loadable "npm:@docusaurus/react-loadable@5.5.2" +"@docusaurus/plugin-client-redirects@^2.4.1": + version "2.4.1" + resolved "https://registry.npmjs.org/@docusaurus/plugin-client-redirects/-/plugin-client-redirects-2.4.1.tgz" + integrity sha512-tp0j16gaLIJ4p+IR0P6KDOFsTOGGMY54MNPnmM61Vaqqt5omLqsuKUO8UlCGU1oW/4EIQOhXYy99XYY5MjE+7A== + dependencies: + "@docusaurus/core" "2.4.1" + "@docusaurus/logger" "2.4.1" + "@docusaurus/utils" "2.4.1" + "@docusaurus/utils-common" "2.4.1" + "@docusaurus/utils-validation" "2.4.1" + eta "^2.0.0" + fs-extra "^10.1.0" + lodash "^4.17.21" + tslib "^2.4.0" + "@docusaurus/plugin-content-blog@2.4.1": version "2.4.1" resolved "https://registry.npmjs.org/@docusaurus/plugin-content-blog/-/plugin-content-blog-2.4.1.tgz" @@ -6828,11 +6843,6 @@ fs.realpath@^1.0.0: resolved "https://registry.npmjs.org/fs.realpath/-/fs.realpath-1.0.0.tgz" integrity sha512-OO0pH2lK6a0hZnAdau5ItzHPI6pUlvI7jMVnxUQRtw4owF2wk8lOSabtGDCTP4Ggrg2MbGnWO9X8K1t4+fGMDw== -fsevents@~2.3.2: - version "2.3.2" - resolved "https://registry.npmjs.org/fsevents/-/fsevents-2.3.2.tgz" - integrity sha512-xiqMQR4xAeHTuB9uWm+fFRcIOgKBMiOBP+eXiyT7jsgVCq1bkVygt00oASowB7EdtpOHaaPgKt812P9ab+DDKA== - function-bind@^1.1.1: version "1.1.1" resolved "https://registry.npmjs.org/function-bind/-/function-bind-1.1.1.tgz"