Merge pull request #4672 from coralproject/spike/CORL-3186-update-docs

[CORL-3186]: Update docs packages and add lunrjs search

docs/.eslintignore

@@ -2,4 +2,5 @@
 *.graphql.ts
 **/__generated__/**
 docs/build
+build
 docs/.docusaurus

docs/.gitignore

@@ -9,6 +9,7 @@
 .cache-loader
 
 # Current generated documentation is excluded
+docs/schema
 docs/api
 
 # Misc

docs/README.md

@@ -1,6 +1,6 @@
 # Website
 
-This website is built using [Docusaurus 2](https://docusaurus.io/), a modern static website generator.
+This website is built using [Docusaurus](https://docusaurus.io/), a modern static website generator.
 
 ## Installation
 
@@ -18,6 +18,7 @@ The reason for this is that the docs references the `client/` and `server/` gene
 Then within `docs/` you can run the following:
 
 ```bash
+pnpm run build
 pnpm run start
 ```
 

docs/dev-notes/architecture/decisions/0002-use-relay-over-apollo-in-frontend.md

@@ -24,7 +24,6 @@ We reached out to the Apollo team but haven't received the required attention to
 
 For v5 we needed a better solution.
 
-
 ## Decision Drivers
 
 A framework that:
@@ -39,25 +38,25 @@ A framework that:
 
 ## Considered Options
 
-* Relay
+- Relay
 
 ## Decision Outcome
 
 At that time the only viable alternative to Apollo is Relay. In fact all the solutions we came up to make up for the missing Colocation support in Apollo looked a lot like Relay Classic anyway. A huge advantage was that Relay Modern was just released that has large improvments over Relay Classic and removed more Facebook related internals.
 
 ### Positive Consequences
 
-* First class Colocation support means we were able to simplify our graphql framework to a handful of lines mostly related to typing and wrapping.
-* Typescript support eventually came out, which was a dramatic improvement in maintainability.
-* A huge chunk of bugs in v4 was related to Apollo and how Data Colocation was not used properly. Relay entirely prevents these bugs from happening.
-* Persisted Queries support for better performance, bundle size and security.
-* Precompilation lead to better performance and bundle size.
-* Relay moves in our direction, every version upgrade is exciting news for us.
-* To understand how our graphql framework works we can now just point to the Relay documentation. It was an almost impossible task to explain our framework before.
-* Relay detects problems in Queries during build time, whereas previously problems were only highlighted during runtime. This has led to faster development.
-* Relay's Client Schema Extensions allowed us to replace Redux entirely. Wow.
+- First class Colocation support means we were able to simplify our graphql framework to a handful of lines mostly related to typing and wrapping.
+- Typescript support eventually came out, which was a dramatic improvement in maintainability.
+- A huge chunk of bugs in v4 was related to Apollo and how Data Colocation was not used properly. Relay entirely prevents these bugs from happening.
+- Persisted Queries support for better performance, bundle size and security.
+- Precompilation lead to better performance and bundle size.
+- Relay moves in our direction, every version upgrade is exciting news for us.
+- To understand how our graphql framework works we can now just point to the Relay documentation. It was an almost impossible task to explain our framework before.
+- Relay detects problems in Queries during build time, whereas previously problems were only highlighted during runtime. This has led to faster development.
+- Relay's Client Schema Extensions allowed us to replace Redux entirely. Wow.
 
 ### Negative Consequences
 
-* Supporting a plugin architecture becomes much more difficult but not impossible.
-* To use advanced features in Relay, we have to adhere to some conventions when structuring the schema. It's not a big issue however as our experience in v4 with Apollo has mostly led to the same or similar conventions.
+- Supporting a plugin architecture becomes much more difficult but not impossible.
+- To use advanced features in Relay, we have to adhere to some conventions when structuring the schema. It's not a big issue however as our experience in v4 with Apollo has mostly led to the same or similar conventions.

docs/dev-notes/forms.mdx

@@ -1,6 +1,6 @@
 ---
 name: Forms
-route: '/forms'
+route: "/forms"
 ---
 
 # Forms
@@ -9,10 +9,21 @@ Let's build some forms! We will use the following compoenents `InputLabel`, `Typ
 
 ### Examples
 
-import { Playground } from 'docz'
-import { InputLabel, CallOut, ValidationMessage, TextField, InputDescription, Flex, Button, FormField, Typography } from '../core/client/ui/components'
+import { Playground } from "docz";
+import {
+  InputLabel,
+  CallOut,
+  ValidationMessage,
+  TextField,
+  InputDescription,
+  Flex,
+  Button,
+  FormField,
+  Typography,
+} from "../core/client/ui/components";
 
 ## Simple Form
+
 <Playground>
   <Flex itemGutter="double" direction="column">
     <Typography variant="heading1">Sign up to join the conversation</Typography>
@@ -40,6 +51,7 @@ import { InputLabel, CallOut, ValidationMessage, TextField, InputDescription, Fl
     </FormField>
 
     <Button variant="filled" color="primary" size="large" fullWidth>Sign up and join the conversation</Button>
+
   </Flex>
 </Playground>
 
@@ -74,6 +86,7 @@ import { InputLabel, CallOut, ValidationMessage, TextField, InputDescription, Fl
     </FormField>
 
     <Button variant="filled" color="primary" size="large" fullWidth>Sign up and join the conversation</Button>
+
   </Flex>
 </Playground>
 
@@ -107,5 +120,6 @@ import { InputLabel, CallOut, ValidationMessage, TextField, InputDescription, Fl
     </FormField>
 
     <Button variant="filled" color="primary" size="large" fullWidth>Sign up and join the conversation</Button>
+
   </Flex>
 </Playground>

docs/dev-notes/introduction.mdx

@@ -16,11 +16,13 @@ sh initialize.sh
 Run these commands to start Coral V5+ in watch mode:
 
 In the `client/` folder in one terminal:
+
 ```sh
 npm run watch
 ```
 
 In the `server/` folder in a separate terminal:
+
 ```sh
 npm run watch
 ```

docs/docs/administration.md

@@ -176,7 +176,7 @@ as possible, so that the feed of comments doesn’t change as you’re reading j
 because new comments are coming in. This could be especially disruptive on
 breaking news and/or controversial stories with very active discussions.
 
-This option can be disabled by setting the environment variable: [DISABLE_LIVE_UPDATES](/environment-variables#disable-live-updates)
+This option can be disabled by setting the environment variable: [DISABLE_LIVE_UPDATES](/environment-variables#disable_live_updates)
 
 ### Permitted Domains
 

docs/docs/environment-variables.md

@@ -85,7 +85,7 @@ HTTPS, you must configure a proxy in front of Coral such as
 [Caddy](https://caddyserver.com/).
 
 **Troubleshooting**: If you are seeing redirect loops when trying to access
-pages like the admin, you may need to configure [`TRUST_PROXY`](#trust-proxy) to
+pages like the admin, you may need to configure [`TRUST_PROXY`](#trust_proxy) to
 tell Coral which upstream proxies to trust.
 
 **Warning**: When `FORCE_SSL=true`, Coral will send [HSTS](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Strict-Transport-Security)

docs/docs/graphql.md

@@ -2,6 +2,8 @@
 id: schema
 title: Getting Started with the Coral API
 sidebar_label: Coral API
+sidebar_position: 1
+displayed_sidebar: api
 description: Coral exposes a GraphQL API for performing administrative tasks.
 ---
 

docs/docs/sso.md

@@ -37,8 +37,8 @@ You will then have to generate a JWT with the following claims:
   presented inside Coral to moderators and other users. There are no username validations or restrictions enforced by Coral when you're using SSO.
 - `user.badges` _(optional)_ - array of strings to be displayed as badges and custom flair badges beside username inside Coral,
   visible to other users and moderators. Badges are configured by passing through strings and can be used to indicate a user's subscription status.
-   - Custom flair badges are configured by passing through names that link to the desired flair badge image.
-   - To use custom flair badges, they must also be enabled in the admin, and each custom flair badge name, image URL must be added in the admin as well. If you include the badges claim, but you are not passing a badge value, then use an empty array instead of null.
+  - Custom flair badges are configured by passing through names that link to the desired flair badge image.
+  - To use custom flair badges, they must also be enabled in the admin, and each custom flair badge name, image URL must be added in the admin as well. If you include the badges claim, but you are not passing a badge value, then use an empty array instead of null.
 - `user.role` _(optional)_ - one of "COMMENTER", "STAFF", "MODERATOR", "ADMIN". Will create/update
   Coral user with this permission level. When users have both an assigned role greather than COMMENTER and a badge, both will be displayed.
 - `user.url` _(optional)_ - url for user account management, where a user will
@@ -108,7 +108,7 @@ as follows:
   `requestAccountDeletion` does.
 - `requestUserCommentsDownload` lets you retrieve a given account's comments download. This mutation will provide you with a `archiveURL` that can be used to download a ZIP file containing the user's comment export.
 
-If you're unsure on how to call GraphQL API's, refer to the section here on [Making your first GraphQL request](/api/schema#making-your-first-request).
+If you're unsure on how to call GraphQL API's, refer to the section here on [Making your first GraphQL request](/api/schema#quick-start).
 
 ## Login Prompts
 

docs/docusaurus.config.js → docs/docusaurus.config.ts

@@ -1,22 +1,38 @@
-const lightCodeTheme = require("prism-react-renderer/themes/github");
-const darkCodeTheme = require("prism-react-renderer/themes/dracula");
+import type * as Preset from "@docusaurus/preset-classic";
+import type { Config } from "@docusaurus/types";
+import { themes as prismThemes } from "prism-react-renderer";
 
-/** @type {import('@docusaurus/types').DocusaurusConfig} */
-module.exports = {
+const config: Config = {
   title: "Coral",
   tagline: "A better commenting experience from Vox Media",
   url: "https://docs.coralproject.net",
   baseUrl: "/",
-  onBrokenLinks: "throw",
-  onBrokenMarkdownLinks: "warn",
-  favicon: "img/favicon.ico",
   organizationName: "coralproject",
   projectName: "talk",
+  onBrokenLinks: "warn",
+  onBrokenMarkdownLinks: "warn",
+  i18n: {
+    defaultLocale: "en",
+    locales: ["en"],
+  },
+
+  presets: [
+    [
+      "classic",
+      {
+        docs: {
+          routeBasePath: "/",
+          sidebarPath: "./sidebars.ts",
+          editUrl: "https://github.com/coralproject/talk/edit/develop/docs/",
+        },
+        theme: {
+          customCss: "./src/css/custom.css",
+        },
+      } satisfies Preset.Options,
+    ],
+  ],
+
   themeConfig: {
-    algolia: {
-      apiKey: "259b9f08146e7407341fa04498544ad6",
-      indexName: "coralproject",
-    },
     navbar: {
       logo: {
         alt: "Coral by Vox Media",
@@ -85,34 +101,28 @@ module.exports = {
       copyright: `Copyright © ${new Date().getFullYear()} Vox Media, Inc.`,
     },
     prism: {
-      theme: lightCodeTheme,
-      darkTheme: darkCodeTheme,
+      theme: prismThemes.github,
+      darkTheme: prismThemes.dracula,
     },
   },
-  presets: [
-    [
-      "@docusaurus/preset-classic",
-      {
-        docs: {
-          routeBasePath: "/",
-          sidebarPath: require.resolve("./sidebars.js"),
-          editUrl: "https://github.com/coralproject/talk/edit/develop/docs/",
-        },
-        theme: {
-          customCss: require.resolve("./src/css/custom.css"),
-        },
-      },
-    ],
-  ],
   plugins: [
     [
-      "@edno/docusaurus2-graphql-doc-generator",
+      "@graphql-markdown/docusaurus",
       {
         schema: "../server/src/core/server/graph/schema/schema.graphql",
         rootPath: "./docs",
         baseURL: "api",
         homepage: "./docs/graphql.md",
+        loaders: {
+          GraphQLFileLoader: "@graphql-tools/graphql-file-loader",
+        },
+        docOptions: {
+          index: true,
+        },
       },
     ],
+    "docusaurus-lunr-search",
   ],
 };
+
+export default config;

docs/package.json

@@ -4,20 +4,25 @@
   "private": true,
   "scripts": {
     "docusaurus": "docusaurus",
-    "start": "docusaurus graphql-to-doc && docusaurus start",
-    "build": "export NODE_OPTIONS=\"--openssl-legacy-provider\" && docusaurus graphql-to-doc && docusaurus build",
-    "preinstall": "npx only-allow pnpm",
+    "start": "docusaurus start",
+    "build": "docusaurus graphql-to-doc && docusaurus build",
+    "swizzle": "docusaurus swizzle",
+    "deploy": "docusaurus deploy",
+    "clear": "docusaurus clear",
+    "serve": "docusaurus serve",
     "write-translations": "docusaurus write-translations",
     "write-heading-ids": "docusaurus write-heading-ids",
+    "typecheck": "tsc",
     "lint": "eslint './**/*.{js,ts,tsx}'"
   },
   "dependencies": {
-    "@docusaurus/core": "2.0.0-beta.1",
-    "@docusaurus/preset-classic": "2.0.0-beta.1",
-    "@docusaurus/theme-search-algolia": "^2.0.0-beta.1",
-    "@edno/docusaurus2-graphql-doc-generator": "^1.2.2",
-    "@mdx-js/react": "^1.6.21",
-    "@svgr/webpack": "^5.5.0",
+    "@docusaurus/core": "3.5.2",
+    "@docusaurus/preset-classic": "3.5.2",
+    "@graphql-markdown/docusaurus": "^1.26.2",
+    "@graphql-tools/graphql-file-loader": "^8.0.1",
+    "@mdx-js/react": "^3.0.0",
+    "clsx": "^2.0.0",
+    "docusaurus-lunr-search": "^3.5.0",
     "eslint": "^8.54.0",
     "eslint-config-prettier": "^6.11.0",
     "eslint-plugin-jest-dom": "^4.0.1",
@@ -26,11 +31,22 @@
     "eslint-plugin-prettier": "^3.1.4",
     "eslint-plugin-react": "^7.33.2",
     "eslint-plugin-react-hooks": "^4.6.0",
-    "file-loader": "^6.2.0",
-    "prism-react-renderer": "^1.2.1",
-    "react": "^17.0.1",
-    "react-dom": "^17.0.1",
-    "url-loader": "^4.1.1"
+    "graphql": "^16.9.0",
+    "graphql-config": "^5.1.2",
+    "lunr": "^2.3.9",
+    "prism-react-renderer": "^2.3.0",
+    "react": "^18.0.0",
+    "react-dom": "^18.0.0"
+  },
+  "devDependencies": {
+    "@docusaurus/module-type-aliases": "3.5.2",
+    "@docusaurus/tsconfig": "3.5.2",
+    "@docusaurus/types": "3.5.2",
+    "@typescript-eslint/eslint-plugin": "^5.62.0",
+    "@typescript-eslint/eslint-plugin-tslint": "^5.62.0",
+    "@typescript-eslint/parser": "^5.62.0",
+    "prettier": "^2.7.1",
+    "typescript": "~5.5.2"
   },
   "browserslist": {
     "production": [
@@ -39,15 +55,12 @@
       "not op_mini all"
     ],
     "development": [
-      "last 1 chrome version",
-      "last 1 firefox version",
-      "last 1 safari version"
+      "last 3 chrome version",
+      "last 3 firefox version",
+      "last 5 safari version"
     ]
   },
-  "devDependencies": {
-    "@docusaurus/types": "^2.0.0-beta.1",
-    "@typescript-eslint/eslint-plugin": "^5.62.0",
-    "@typescript-eslint/eslint-plugin-tslint": "^5.62.0",
-    "@typescript-eslint/parser": "^5.62.0"
+  "engines": {
+    "node": ">=18.0"
   }
 }