feat: enable search and production deploy

docs/advanced/configuration-files/_category_.json

@@ -1,6 +1,6 @@
 {
   "label": "Configuration Files",
-  "position": 7,
+  "position": 9,
   "link": {
     "type": "generated-index",
     "description": "Advanced customization of configuration files."

docs/advanced/enabling-search.md

@@ -0,0 +1,111 @@
+---
+sidebar_position: 8
+---
+
+# Enable search bar
+
+Docusaurus has official support for [Algolia Search](https://docusaurus.io/docs/search#using-algolia-docsearch) as the primary method of integrating search into docs.
+
+We have an [open-source account](https://docsearch.algolia.com/docs/who-can-apply/) with [Algolia](https://www.algolia.com/) to hold the indexes for our documentation but it is limited to **only** open-source projects (not just the documentation but the originating source code). If your project does not have any source code (general guidelines or tutorials), then it will satisfy the conditions as long as the documentation is open-source.
+
+:::tip
+
+This template repo assumes that the project and its source code is open-source, so it is set up out of the box to be able to integrate Algolia directly.
+
+Please follow the additional instructions below on how to set up local search to avoid an index if you do not satisfy those conditions.
+
+:::
+
+## Docs and source code is open-source
+
+Join the [#documentation](https://consensys.slack.com/archives/C0272B5P1CY) Slack channel and ask for Algolia search integration for your docs site. Make sure to provide details of your project so that we can determine whether you are eligible for the Algolia account.
+
+We will get back to you with the `appId`, `apiKey` (it's ok to expose this) and your `indexName`.
+
+You will need to fill those three fields in your `docusaurus.config.js` as shown below.
+
+```js {7-10} title="docusaurus.config.js"
+const config = {
+  themeConfig:
+    /** @type {import('@docusaurus/preset-classic').ThemeConfig} */
+    ({
+      algolia: {
+        // The application ID provided by Algolia
+        appId: "NSRFPEJ4NC", # // cspell:disable-line
+        // Public API key: it is safe to commit it
+        apiKey: "cea41b975ad6c9a01408dfda6e0061d3",
+        indexName: "docs-template", // Ping #documentation on Slack for your index name
+      },
+    }),
+};
+```
+
+## Source code is not open-source
+
+Unfortunately, if your project does not satisfy the [checklist](https://docsearch.algolia.com/docs/who-can-apply/) then we cannot use Algolia (for free).
+
+In this scenario, there are two options:
+
+1. Make a decision with your team and team lead whether there is [budget](https://www.algolia.com/pricing/) for integrating Algolia Search
+2. Install a [local search plugin](https://github.com/easyops-cn/docusaurus-search-local) and do not use Algolia
+
+If you decide on _option 1_ and have obtained Finance approval, then you can follow the steps from above and contact us with this information.
+
+If you decide on _option 2_, you can easily install the [local search plugin](https://github.com/easyops-cn/docusaurus-search-local). However, please note there are some small caveats.
+
+- Local search means that at build-time this is part of the build. For very large documentation sites there may be some marginal performance deficits and additional size to the bundle. Usually, it would require the docs site to be **very large** before it is even a consideration.
+- Search will not work when running in a dev environment (`npm run start`). You must `npm run build` and `npm run serve` locally to get the local search to work.
+
+### Steps to install plugin for local search
+
+1. `cd` into the root of your repository where your `package.json` is located
+2. Install the plugin with `npm`
+
+```bash
+npm i @easyops-cn/docusaurus-search-local
+```
+
+3. Remove the `algolia` key entirely under `config > themeConfig`.
+
+   ```js title="DELETE ME in docusaurus.config.js"
+   algolia: {
+     // The application ID provided by Algolia
+     appId: "NSRFPEJ4NC", # // cspell:disable-line
+     // Public API key: it is safe to commit it
+     apiKey: "cea41b975ad6c9a01408dfda6e0061d3",
+     indexName: "docs-template", // Ping #documentation on Slack for your index name
+     // Optional: see doc section below
+     contextualSearch: true,
+     // Optional: Specify domains where the navigation should occur through window.location instead on history.push. Useful when our Algolia config crawls multiple documentation sites and we want to navigate with window.location.href to them.
+     externalUrlRegex: "external\\.com|domain\\.com",
+     // Optional: Algolia search parameters
+     searchParameters: {},
+     // Optional: path for search page that enabled by default (`false` to disable it)
+     searchPagePath: "search",
+     // ... other Algolia params
+   },
+   ```
+
+   This is to ensure that Algolia search bar is overridden by the plugin.
+
+4. Apply the config options for the local plugin, like below under `config > themes` in `docusaurus.config.js`:
+
+   ```js
+   themes: [
+     [
+       require.resolve("@easyops-cn/docusaurus-search-local"),
+       /** @type {import("@easyops-cn/docusaurus-search-local").PluginOptions} */
+       ({
+         hashed: true,
+         docsRouteBasePath: "/",
+         indexBlog: false,
+       }),
+     ],
+   ],
+   ```
+
+:::tip
+
+You can find more options that you supply the plugin for your needs [here](https://github.com/easyops-cn/docusaurus-search-local#theme-options).
+
+:::

docs/advanced/google-analytics.mdx

@@ -4,25 +4,38 @@ sidebar_position: 6
 
 # Google Analytics
 
-[Google Analytics](https://docusaurus.io/docs/api/plugins/@docusaurus/plugin-google-analytics) and [GTag](https://docusaurus.io/docs/api/plugins/@docusaurus/plugin-google-gtag) are Docusaurus plugins available depending on whether you need Google Analytics or Google Tag Manager.
+[Google Tag Manager](https://docusaurus.io/docs/api/plugins/@docusaurus/plugin-google-tag-manager) and [GTag](https://docusaurus.io/docs/api/plugins/@docusaurus/plugin-google-gtag) are Docusaurus plugins available for Google Analytics.
 
-:::tip Recommendation
+:::info
 
-The **Google Tag Manager** plugin is _pre-installed_ by default with this template repo.
+The **Google Tag Manager** and **GTAag** plugin is _pre-installed_ by default with this template repo.
 
 :::
 
-## Setting up Google Tag Manager in `docusaurus.config.js`
+:::tip
 
-Uncomment the highlighted lines shown below in the `docusaurus.config.js` file to enable and set up Google Tag Manager.
+Please join the [#documentation](https://consensys.slack.com/archives/C0272B5P1CY) Slack channel and request for your tags. Make sure to provide some information about your project in your request.
 
-```js title="docusaurus.config.js" {4-7}
+:::
+
+## Setting up GTag and GTM in `docusaurus.config.js`
+
+Fill in with the provided values in the highlighted lines shown below in the `docusaurus.config.js`.
+
+```js title="docusaurus.config.js" {6,13}
 const config = {
   plugins: [
+    [
+      "@docusaurus/plugin-google-gtag",
+      {
+        trackingID: "G-",
+        anonymizeIP: true,
+      },
+    ],
     [
       "@docusaurus/plugin-google-tag-manager",
       {
-        containerId: "YOUR_ID",
+        containerId: "GTM-",
       },
     ],
   ],

docs/advanced/production-deployment.md

@@ -0,0 +1,113 @@
+---
+sidebar_position: 7
+---
+
+# Production deployment
+
+The recommended method to deploying your docs site is by using [**Vercel**](https://vercel.com/).
+
+The main benefits of using Vercel over GitHub Pages is the ease of integration with GitHub repos and also deploying automatic previews on Pull Requests. The only caveat is that private GitHub repos require all pushes to a PR to also be members of the Vercel account which increases the cost of the subscription. In such a case, there is a workaround that allows Vercel to still host the docs and provide previews but requires a little more setup.
+
+## Scenario A: Public GitHub repo
+
+Once you are ready to deploy to Vercel, ensure that you have done the following:
+
+1. Copy the `vercel.json` file in the root of this template repo to the root of your documentation repo
+
+   1. This file contains some URL redirects from older MkDocs docs that we had at the company before we moved to Docusaurus. If your documentation did not pre-exist in MkDocs, then you can remove these fields.
+
+   :::caution
+
+   Please ensure the `cleanUrls` is set to true and specified in the `vercel.json`. This is necessary to make sure that Vercel deploys the app properly without expecting trailing slashes.
+
+   :::
+
+2. Determine the public URL that you want to use to expose the docs site. It is common practice for the URL to follow the format of `https://docs.<YOUR_PRODUCT>.consensys.net`; however, that may be different depending on your needs.
+3. Join the [#documentation](https://consensys.slack.com/archives/C0272B5P1CY) Slack channel and ask for Vercel integration for your repo. Make sure to provide a link to your repo in your message.
+
+Once integration has occurred, any new PRs should have a Vercel bot update with a preview link on all new commits to that PR.
+
+<details>
+  <summary>
+    See example Github comment
+  </summary>
+  <div>
+    <img src={require("./img/vercelGithubComment.png").default} alt="vercelGithub" />
+  </div>
+</details>
+
+## Scenario B: Private GitHub repo
+
+1. Join the [#documentation](https://consensys.slack.com/archives/C0272B5P1CY) Slack channel and ask for Vercel integration for your **_private_** repo. Make sure to provide a link to your repo in your message.
+2. Your `build.yml` file under `.github/workflows` will be modified to look like below (you **do not** need to take this action yourself). Essentially, we will bypass the Vercel limitation by having GitHub Actions build and push the static build directly to Vercel. The Action will also take care of commenting the preview URLs in the PR on new commits.
+
+<details>
+  <summary>
+    Updated <code>build.yml</code>
+  </summary>
+  <div>
+
+```yaml title=".github/workflows/build.yml"
+---
+name: Build and Preview
+
+on:
+  pull_request:
+    branches:
+      - main
+  push:
+    branches:
+      - main
+
+jobs:
+  build:
+    name: Build
+    runs-on: ubuntu-latest
+    # the environment to deploy to / use secrets from
+    environment: vercel
+    # modify the default permissions of the GITHUB_TOKEN, so as to only allow least privileges
+    permissions:
+      contents: read
+      pull-requests: write
+    steps:
+      - uses: actions/checkout@v3
+      - name: Build
+        uses: ConsenSys/docs-gha/build@main
+        with:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+      - run: cp vercel.json ./build
+      - uses: amondnet/vercel-action@v25.1.1 # // cspell:disable-line
+        id: vercel-action-staging
+        if: github.event_name == 'pull_request'
+        with:
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+          vercel-token: ${{ secrets.VERCEL_TOKEN }}
+          vercel-org-id: ${{ secrets.ORG_ID }}
+          vercel-project-id: ${{ secrets.PROJECT_ID }}
+          working-directory: ./build
+          scope: infura-web
+      - uses: amondnet/vercel-action@v25.1.1 # // cspell:disable-line
+        id: vercel-action-production
+        if: github.event_name == 'push'
+        with:
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+          vercel-token: ${{ secrets.VERCEL_TOKEN }}
+          vercel-org-id: ${{ secrets.ORG_ID }}
+          vercel-project-id: ${{ secrets.PROJECT_ID }}
+          working-directory: ./build
+          vercel-args: "--prod "
+          scope: infura-web
+          github-comment: false
+```
+
+  </div>
+</details>
+
+<details>
+  <summary>
+    Example Action comment in PR
+  </summary>
+  <div>
+    <img src={require("./img/privateRepoVercel.png").default} alt="privateRepoVercel" />
+  </div>
+</details>

docs/advanced/remove-openapi-demo.mdx

@@ -57,7 +57,11 @@ const redocusaurus = [
 
 Above is an example of how to configure the _Redocusaurus_ plugin; this is also the same configuration used in this repo as part of the demo.
 
-## _docusaurus-plugin-openapi-docs_ configuration
+## ~~_docusaurus-plugin-openapi-docs_ configuration~~
+
+<details>
+  <summary>See more</summary>
+  <div>
 
 ```js title="./docusaurus.config.js"
 const docusaurusApi2 = [
@@ -81,6 +85,10 @@ const docusaurusApi2 = [
 ];
 ```
 
+  </div>
+
+</details>
+
 ## Removing a Plugin
 
 As these plugins are `npm` modules installed into the project, they can be easily removed by doing the following:

docusaurus.config.js

@@ -142,7 +142,7 @@ const config = {
         // Public API key: it is safe to commit it
         apiKey: "cea41b975ad6c9a01408dfda6e0061d3",
 
-        indexName: "docs-template", // Ping @Galileo for your index name
+        indexName: "docs-template", // Ping #documentation on Slack for your index name
 
         // Optional: see doc section below
         contextualSearch: true,
@@ -319,7 +319,21 @@ const config = {
         // },
       ],
     }),
-  plugins: [], // remove if not using docusaurus-plugin-openapi-docs
+  plugins: [
+    [
+      "@docusaurus/plugin-google-gtag",
+      {
+        trackingID: "G-",
+        anonymizeIP: true,
+      },
+    ],
+    [
+      "@docusaurus/plugin-google-tag-manager",
+      {
+        containerId: "GTM-",
+      },
+    ],
+  ], // remove if not using docusaurus-plugin-openapi-docs
   themes: [], // remove if not using docusaurus-plugin-openapi-docs
 };
 

package.json

@@ -32,6 +32,7 @@
   "dependencies": {
     "@docusaurus/core": "^2.3.1",
     "@docusaurus/plugin-google-gtag": "^2.3.1",
+    "@docusaurus/plugin-google-tag-manager": "^2.3.1",
     "@docusaurus/preset-classic": "^2.3.1",
     "@mdx-js/react": "^1.6.22",
     "clsx": "^1.2.1",