docs: add info on how to troubleshoot and better errors (#4803)

This PR adds some troubleshooting information to the website readme and
also makes it so that we get more readable errors in the build logs when
something goes wrong.

.github/workflows/build_doc_prs.yaml

@@ -17,4 +17,9 @@ jobs:
           UNLEASH_PROXY_URL: ${{ secrets.UNLEASH_PROXY_URL_DEVELOPMENT }}
         run: |
           # Build the site
-          cd website && yarn && yarn build
+          cd website && yarn
+          # give better error messages when the build fails (refer to website/readme.md#troubleshooting)
+          echo "Removing references to chalk in node_modules/@docusaurus/core/lib/client/serverEntry.js"
+          sed -i 's/chalk\(\w\|\.\)\+//g' node_modules/@docusaurus/core/lib/client/serverEntry.js
+          echo "Chalk removed"
+          yarn build

website/README.md

@@ -39,3 +39,61 @@ GIT_USER=<Your GitHub username> USE_SSH=true yarn deploy
 ```
 
 If you are using GitHub pages for hosting, this command is a convenient way to build the website and push to the `gh-pages` branch.
+
+## Troubleshooting
+
+### `TypeError: source_default(...).bold is not a function`
+
+If you get an error like this, it's probably due to a formatting issue within one of the markdown files. It could be
+
+- unescaped angle brackets (markdown will try to parse `<your-key>` (when it's not quoted) as HTML, which breaks the build)
+- incorrectly formatted titles or missing pieces of files
+- a lot of other stuff.
+
+```console
+Component Figure was not imported, exported, or provided by MDXProvider as global scope
+
+TypeError: source_default(...).bold is not a function
+[ERROR] Unable to build website for locale en.
+```
+
+This error is very hard to debug, but there is a trick that appears to work (as shared in [this discussion on docusaurus' repo](https://github.com/facebook/docusaurus/issues/7686#issuecomment-1486771382)):
+
+In `node_modules/@docusaurus/core/lib/client/serverEntry.js`, remove all references to `chalk`. You can use a regex replace for that, by replacing `chalk(\w|\.)+` with the empty string.
+
+Depending on your editor, that regex might need more escapes. For instance, here's a command to run with `evil-ex` in Emacs:
+
+```
+%s/chalk\(\w\|\.\)+//g
+```
+
+For macOS `sed`, it'd be:
+
+```shell
+sed -i '' 's/chalk\(\w\|\.\)\+//g' node_modules/@docusaurus/core/lib/client/serverEntry.js
+```
+
+For GNU `sed`:
+
+```shell
+sed -i 's/chalk\(\w\|\.\)\+//g' node_modules/@docusaurus/core/lib/client/serverEntry.js
+```
+
+That might turn your error into something like this:
+
+```console
+[ERROR] Docusaurus server-side rendering could not render static page with path /reference/api/unleash/change-requests.
+[ERROR] Docusaurus server-side rendering could not render static page with path /reference/api/unleash/feature-types.
+[ERROR] Docusaurus server-side rendering could not render static page with path /reference/api/unleash/frontend-api.
+[ERROR] Docusaurus server-side rendering could not render static page with path /reference/api/unleash/maintenance.
+[ERROR] Docusaurus server-side rendering could not render static page with path /reference/api/unleash/notifications.
+[ERROR] Docusaurus server-side rendering could not render static page with path /reference/api/unleash/personal-access-tokens.
+[ERROR] Docusaurus server-side rendering could not render static page with path /reference/api/unleash/segments.
+[ERROR] Docusaurus server-side rendering could not render static page with path /reference/api/unleash/service-accounts.
+[ERROR] Docusaurus server-side rendering could not render static page with path /reference/api/unleash/telemetry.
+[ERROR] Docusaurus server-side rendering could not render static page with path /reference/api/unleash/unstable.
+Component Figure was not imported, exported, or provided by MDXProvider as global scope
+
+Error: Unexpected: cant find current sidebar in context
+[ERROR] Unable to build website for locale en.
+```