Merge pull request #52 from Consensys/32-improvements

Update docs guide
Consensys · Sep 28, 2024 · 19083d5 · 19083d5
2 parents 0b7ff9b + 3102e3c
commit 19083d5
Show file tree

Hide file tree

Showing 8 changed files with 101 additions and 85 deletions.
diff --git a/docs/configure/openapi.md b/docs/configure/openapi.md
@@ -6,7 +6,6 @@ sidebar_label: OpenAPI docs
 
 # Configure OpenAPI docs
 
-There are currently no plugins available to support Docusaurus 3. Please refer to the
-solution implemented on Web3signer
+There are currently no plugins available to support OpenAPI in Docusaurus 3. Please refer to the solution implemented in the [Web3Signer REST API documentation](https://docs.web3signer.consensys.io/reference/api/rest).
 
-We will update this space when there is a plugin available from Redocusaurus or Palo Alto OpenAPI
+This page will be updated when there is a plugin available from [Redocusaurus](https://redocusaurus.vercel.app/docs/) or [Palo Alto OpenAPI](https://github.com/PaloAltoNetworks/docusaurus-template-openapi-docs).
diff --git a/docs/contribute/add-images.md b/docs/contribute/add-images.md
@@ -1,6 +1,6 @@
 ---
 description: Add screenshots and diagrams to the documentation.
-sidebar_position: 5
+sidebar_position: 4
 toc_max_heading_level: 3
 ---
 
@@ -12,13 +12,13 @@ import TabItem from '@theme/TabItem';
 You can add [screenshots](#screenshots) and [diagrams](#diagrams) to the Consensys documentation.
 
 Add your image to an `assets` or `images` folder within the documentation folder, and link to it in
-your doc content using [Markdown syntax](https://docusaurus.io/docs/markdown-features/assets#images).
+your doc content using
+[Markdown, CommonJS require, or ES imports](https://docusaurus.io/docs/markdown-features/assets#images).
 You can also use HTML to center the image.
 For example:
 
 <Tabs>
-
-  <TabItem value="markdown" label="markdown">
+<TabItem value="Markdown">
 
 ```markdown
 <p align="center">
@@ -28,16 +28,42 @@ For example:
 </p>
 ```
 
-  </TabItem>
-  <TabItem value="Rendered" label="Rendered">
+</TabItem>
+<TabItem value="CommonJS require">
+
+```jsx
+<p align="center">
+  <img 
+    src={require("../assets/transaction-insights.png").default} 
+    alt="Snap transaction insights UI" 
+  />
+</p>
+```
+
+</TabItem>
+<TabItem value="ES imports">
+
+```jsx
+import txnInsights from "../assets/transaction-insights.png";
+
+<p align="center">
+  <img 
+    src={txnInsights} 
+    alt="Snap transaction insights UI" 
+  />
+</p>
+```
+
+</TabItem>
+<TabItem value="Rendered" label="Rendered">
 
 <p align="center">
 
 ![Snap transaction insights UI](../assets/transaction-insights.png)
 
 </p>
 
-  </TabItem>
+</TabItem>
 </Tabs>
 
 ## Screenshots
@@ -53,28 +79,34 @@ for faster page loading:
 
 ## Diagrams
 
-Consensys doc sites contain diagrams created using [Figma](https://figma.com/).
-You must have access to the Consensys **Quorum Diagrams** template files on Figma to create a diagram.
+Consensys doc sites contain diagrams created using [Mermaid](https://mermaid.js.org/) and
+[Figma](https://figma.com/).
 
-Diagrams can illustrate:
+Use diagrams to illustrate:
 
 - Detailed or simplified product architecture.
 - Technical processes and flows.
 - Concept charts and tables.
 
-### Demo
+### Mermaid
 
-The following video demonstrates creating a diagram for the GoQuorum documentation using Figma:
+To use Mermaid diagrams in your site,
+[install the Mermaid theme plugin](https://docusaurus.io/docs/markdown-features/diagrams) and use
+the Mermaid diagram syntax, for example, for [flowcharts](https://mermaid.js.org/syntax/flowchart.html)
+or [sequence diagrams](https://mermaid.js.org/syntax/sequenceDiagram.html).
+
+### Figma
+
+The following video demonstrates creating a Figma diagram for the GoQuorum documentation:
 
 <!-- markdownlint-disable -->
 <p align="center">
   <iframe width="560" height="315" src="https://www.youtube.com/embed/2H-OeBkVOws" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>
 </p>
 <!-- markdownlint-restore -->
 
-### Create your Figma diagram
-
-Use the following general guidelines when creating Consensys diagrams on Figma.
+To create a Figma diagram, you must have access to the **Developer docs diagrams** template files on
+Figma, and use the following general guidelines.
 Refer to the [Figma help website](https://help.figma.com/hc/en-us) for more information on
 getting started with Figma, Figma design elements, and more.
 
@@ -151,7 +183,7 @@ See the
 [Figma documentation on the Arrow Tool](https://help.figma.com/hc/en-us/articles/360040450133-Using-Shape-Tools#h_677f8eba-73c4-4987-a64b-c0226aaec392)
 for more information.
 
-### Export your Figma diagram
+#### Export your Figma diagram
 
 1. Select the frame of your diagram.
    Make sure all elements of your diagram are contained in the frame.

diff --git a/docs/contribute/preview.md b/docs/contribute/preview.md
@@ -1,14 +1,12 @@
 ---
 description: Preview your documentation changes before submitting them.
-sidebar_position: 6
+sidebar_position: 5
 ---
 
 # Preview the docs
 
-Use [npm](#npm) or [Yarn](#yarn) to preview your documentation changes locally
-before pushing them to your remote branch.
-
-Make sure you have [Node.js version 16+ and npm](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm)
+Use [npm](#npm) to preview your documentation changes locally before pushing them to your remote branch.
+Make sure you have [Node.js version 18+ and npm](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm)
 installed.
 
 :::tip
@@ -17,15 +15,14 @@ If you're using Node.js with [nvm](https://github.com/nvm-sh/nvm/blob/master/REA
 :::
 
 :::note
-If you make changes to a versioned doc site
-(for example, [Teku](https://docs.teku.consensys.net/)),
+If you make changes to a versioned doc site (for example, [Teku](https://docs.teku.consensys.net/)),
 the changes only appear in the development version of the docs.
 Switch to the development version of the preview to see those changes.
 :::
 
-## npm
+## Use npm
 
-In the doc repository, run the following commands to start a local development server and preview
+In the root of the doc project, run the following commands to start a local development server and preview
 your changes:
 
 ```bash
@@ -34,23 +31,6 @@ npm start
 ```
 
 :::note
-If you make changes to the [redirects](../create/configure-docusaurus.md#redirects),
-you can preview them by running `npm run build && npm run serve`.
-:::
-
-## Yarn
-
-Make sure you have [Yarn](https://yarnpkg.com/getting-started/install) version 3 installed.
-
-In the doc repository, run the following commands to start a local development server and preview
-your changes:
-
-```bash
-yarn install
-yarn start
-```
-
-:::note
-If you make changes to the [redirects](../create/configure-docusaurus.md#redirects),
-you can preview them by running `yarn build && yarn serve`.
+If you make changes to the [redirects](../create/configure-docusaurus.md#redirects), you can preview them by
+running `npm run build && npm run serve`.
 :::
diff --git a/docs/create/configure-docusaurus.md b/docs/create/configure-docusaurus.md
@@ -3,19 +3,21 @@ description: Configure your Docusaurus site and use Docusaurus Markdown features
 sidebar_position: 1.5
 ---
 
-# Configure Docusaurus
+# Configure your site
 
 import Tabs from '@theme/Tabs';
 import TabItem from '@theme/TabItem';
 
-Most Consensys documentation sites are built using [Docusaurus](https://docusaurus.io/).
-A Docusaurus site organizes most of its [configuration](https://docusaurus.io/docs/configuration) in
-the `docusaurus.config.js` file, including the following key elements.
+Most Consensys documentation sites are built using [Docusaurus](https://docusaurus.io/) and hosted
+on [Vercel](https://vercel.com/).
+
+You can configure site components, including the top navigation, sidebar, and footer, in the
+`docusaurus.config.js` file, and server-side redirects in the `vercel.json` file.
 
 ## Top navigation
 
-Configure the top navigation in the [navbar](https://docusaurus.io/docs/api/themes/configuration#navbar)
-section of the theme configuration.
+In `docusaurus.config.js`, configure the top navigation in the
+[navbar](https://docusaurus.io/docs/api/themes/configuration#navbar) section of the theme configuration.
 
 <details>
 <summary>Example navbar configuration</summary>
@@ -68,8 +70,8 @@ module.exports = {
 
 ## Sidebar
 
-Pass the [sidebar](https://docusaurus.io/docs/sidebar) to the `sidebarPath` key in your docs
-instance, whether it's to the `docs` section of the [`classic`
+In `docusaurus.config.js`, pass the [sidebar](https://docusaurus.io/docs/sidebar) to the
+`sidebarPath` key in your docs instance, whether it's to the `docs` section of the [`classic`
 preset](https://docusaurus.io/docs/using-plugins#docusauruspreset-classic) or directly to the
 [`content-docs` plugin](https://docusaurus.io/docs/api/plugins/@docusaurus/plugin-content-docs).
 Define and customize your sidebar in a separate sidebar file (`sidebars.js` by default).
@@ -161,8 +163,8 @@ module.exports = {
 
 ## Footer
 
-Configure the footer in the [footer](https://docusaurus.io/docs/api/themes/configuration#footer-1)
-section of the theme configuration.
+In `docusaurus.config.js`, configure the footer in the
+[footer](https://docusaurus.io/docs/api/themes/configuration#footer-1) section of the theme configuration.
 
 <details>
 <summary>Example footer configuration</summary>
@@ -234,34 +236,31 @@ module.exports = {
 
 ## Redirects
 
-Use the [`plugin-client-redirects`](https://docusaurus.io/docs/api/plugins/@docusaurus/plugin-client-redirects)
-plugin to configure redirects.
+Use the Vercel configuration file `vercel.json` to configure
+[server-side redirects](https://vercel.com/docs/edge-network/redirects).
 
 <details>
 <summary>Example redirects configuration</summary>
 
-```js title="docusaurus.config.js"
-module.exports = {
-  plugins: [
-    [
-      '@docusaurus/plugin-client-redirects',
-      {
-        redirects: [
-          // /docs/oldDoc -> /docs/newDoc
-          {
-            to: '/docs/newDoc',
-            from: '/docs/oldDoc',
-          },
-          // Redirect from multiple old paths to the new path
-          {
-            to: '/docs/newDoc2',
-            from: ['/docs/oldDocFrom2019', '/docs/legacyDocFrom2016'],
-          },
-        ],
-      },
-    ],
-  ],
-};
+```js title="vercel.json"
+{
+  "cleanUrls": true,
+  "trailingSlash": true,
+  "redirects": [
+    {
+      "source": "/guide/",
+      "destination": "/wallet/"
+    },
+    {
+      "source": "/guide/common-terms/",
+      "destination": "/wallet/"
+    },
+    {
+      "source": "/guide/contributors/",
+      "destination": "/wallet/"
+    }
+  ]
+}
 ```
 
 </details>
diff --git a/docs/create/run-in-development.md b/docs/create/run-in-development.md
@@ -10,6 +10,10 @@ Docusaurus is a React-based project and uses npm and or Yarn project workflows.
 This page describes `npm` commands to start previews, lint, build, and do other necessary
 things in development.
 
+:::note
+Periodically run `npm install` before running Docusaurus to install or update dependencies.
+:::
+
 ## npm commands and scripts
 
 The following is a list of npm scripts in `package.json`.

diff --git a/docs/index.md b/docs/index.md
@@ -11,8 +11,8 @@ creating new documentation sites.
 ## Overview
 
 Each Consensys developer product has a documentation site, maintained by the [Consensys developer
-documentation team](https://consensyssoftware.atlassian.net/wiki/spaces/PEG/pages/398159216798/Documentation+Pliny)
-and/or a product team.
+documentation team](https://www.notion.so/consensys/Developer-documentation-team-Pliny-8965c72cd62648719e35a16935236194)
+(internal page) and/or a product team.
 The docs use a [docs-as-code](https://www.writethedocs.org/guide/docs-as-code/) approach and are
 mostly open source, empowering developers and community members to contribute to the docs alongside
 the docs team.
@@ -37,7 +37,8 @@ The following table shows the full list of developer documentation sites support
 | [Teku](https://docs.teku.consensys.net/)                                | [`consensys/doc.teku`](https://github.com/consensys/doc.teku)             | Docusaurus    | Vercel           | Maintained by the docs team.                                                                                                                                             |
 | [Hyperledger Besu](https://besu.hyperledger.org/)                       | [`hyperledger/besu-docs`](https://github.com/hyperledger/besu-docs)       | Docusaurus    | GitHub Pages     | Maintained by the docs team. This is a Hyperledger project and has its own [Besu docs contribution guidelines](https://wiki.hyperledger.org/display/BESU/Documentation). |
 | [Web3Signer](https://docs.web3signer.consensys.net/)                    | [`consensys/doc.web3signer`](https://github.com/consensys/doc.web3signer) | Docusaurus    | Vercel           | Maintained by the docs team.                                                                                                                                             |
-| [MetaMask](https://docs.metamask.io/)                                   | [`metamask/metamask-docs`](https://github.com/MetaMask/metamask-docs)     | Docusaurus    | GitHub Pages     | Maintained by the docs team. This project has additional [MetaMask docs contribution guidelines](https://github.com/MetaMask/metamask-docs/blob/main/CONTRIBUTING.md).   |
+| [MetaMask](https://docs.metamask.io/)                                   | [`metamask/metamask-docs`](https://github.com/MetaMask/metamask-docs)     | Docusaurus    | Vercel           | Maintained by the docs team. This project has additional [MetaMask docs contribution guidelines](https://github.com/MetaMask/metamask-docs/blob/main/CONTRIBUTING.md).   |
+| MetaMask Delegation Toolkit (private)                                   | `metamask/gator-docs` (private)                                           | Docusaurus    | Vercel           | Maintained by the docs team.                                                                                                                                             |
 | [Infura](https://docs.infura.io/infura/)                                | `infura/docs` (private)                                                   | Docusaurus    | Vercel           | Maintained by the docs team.                                                                                                                                             |
 | [Linea](https://docs.linea.build/)                                      | [`consensys/doc.zk-evm`](https://github.com/consensys/doc.zk-evm)         | Docusaurus    | Vercel           | Maintained by the docs team.                                                                                                                                             |
 | [MetaFi](https://fantastic-goggles-eyo7zmp.pages.github.io/)            | `consensys-vertical-apps/cx-api-docs` (private)                           | Docusaurus    | GitHub Pages     | Maintained by the docs team and the MetaFi team.                                                                                                                         |

diff --git a/docusaurus.config.js b/docusaurus.config.js
@@ -115,7 +115,6 @@ const config = {
       docs: {
         sidebar: {
           hideable: true,
-          autoCollapseCategories: true,
         },
       },
       navbar: {

diff --git a/sidebars.js b/sidebars.js
@@ -7,6 +7,7 @@ const sidebars = {
     {
       type: "category",
       label: "Contribute to the docs",
+      collapsed: false,
       link: {
         type: "generated-index",
         slug: "/contribute",
@@ -21,6 +22,7 @@ const sidebars = {
     {
       type: "category",
       label: "Create a new doc site",
+      collapsed: false,
       link: {
         type: "generated-index",
         slug: "/create",