From 0b320fc3fc248d99119e870ab01a81f5f9981f01 Mon Sep 17 00:00:00 2001 From: Alexandra Tran Date: Fri, 27 Sep 2024 14:00:14 -0700 Subject: [PATCH] more edits --- docs/contribute/add-images.md | 64 ++++++++++++++++++++------- docs/contribute/preview.md | 36 ++++------------ docs/create/configure-docusaurus.md | 67 ++++++++++++++--------------- docs/create/run-in-development.md | 4 ++ docusaurus.config.js | 1 - sidebars.js | 1 + 6 files changed, 94 insertions(+), 79 deletions(-) diff --git a/docs/contribute/add-images.md b/docs/contribute/add-images.md index e50189c..4252ca8 100644 --- 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: - - + ```markdown

@@ -28,8 +28,34 @@ For example:

``` - - + + + +```jsx +

+ Snap transaction insights UI +

+``` + + + + +```jsx +import txnInsights from "../assets/transaction-insights.png"; + +

+ Snap transaction insights UI +

+``` + + +

@@ -37,7 +63,7 @@ For example:

- + ## Screenshots @@ -53,18 +79,25 @@ 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:

@@ -72,9 +105,8 @@ The following video demonstrates creating a diagram for the GoQuorum documentati

-### 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 index 049c94b..96cc054 100644 --- 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 index 4d27a39..c81cc60 100644 --- 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.
Example navbar configuration @@ -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.
Example footer configuration @@ -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).
Example redirects configuration -```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/" + } + ] +} ```
diff --git a/docs/create/run-in-development.md b/docs/create/run-in-development.md index f974a13..100fc61 100644 --- 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/docusaurus.config.js b/docusaurus.config.js index af481d2..81e0635 100644 --- 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 index a1fa875..33a46c9 100644 --- a/sidebars.js +++ b/sidebars.js @@ -22,6 +22,7 @@ const sidebars = { { type: "category", label: "Create a new doc site", + collapsed: false, link: { type: "generated-index", slug: "/create",