Revert "build: clone repository "docs" and configuration when syncing project docs + removing separate docusaurus build"

.github/dependabot.yml

@@ -17,6 +17,18 @@ updates:
     directory: "/"
     schedule:
       interval: "monthly"
+  - package-ecosystem: "npm"
+    directory: "/docs"
+    schedule:
+      interval: "monthly"
+    groups:
+      docusaurus:
+        patterns:
+          - "@docusaurus/*"
+      react:
+        patterns:
+          - "react"
+          - "react-dom"
   - package-ecosystem: "npm"
     directories:
       - "/examples/custom-properties"

.github/maintainers_guide.md

@@ -44,38 +44,9 @@ Remove cached project dependencies with `rm -r node_modules package-lock.json` b
 
 ### Managing Documentation
 
-If you're not touching the `/docs` folder, you don't need to worry about the docs setup affecting your PR.
-
-The `/docs` folder contains two types of docs files:
-
-* markdown files
-* sidebar.json
-
-The private repo containing the tools.slack.dev site pulls these in at build time.
-
-Maintainers need to use the `run workflow` button associated with the `deploy` workflow in that private repo to update the docs with changes from here. 
-
-#### Markdown Files
-
-The markdown files here are secretly mdx files in disguise.
-
-If you'd like to add images to pages, add the image files to the same folder the md file is in.
+See the [`/docs/README.md`](../docs/README.md) file for documentation instructions.
 
-We appreciate markdown edits from anyone!!! 
-
-#### Sidebar
-
-`_sidebar.json` sets the Bolt JS docs sidebar 
-
-Sidebar values take the form of `bolt-js/path-within-docs/`.
-
-or, in other words - full path but remove "docs":
-path: `bolt-js/docs/concepts/sending-variables.md`
-value: `bolt-js/concepts/sending-variables`
-
-For info on syntax see https://docusaurus.io/docs/sidebar.
-
-This file is copied to slackapi.github.io/bolt-js/_sidebar.json, then called in slackapi.github.io/sidebars.js
+If you're not touching the `/docs` folder, you don't need to worry about the docs setup affecting your PR.
 
 ### Releases
 _For beta releases, see Beta Releases section below:_

.github/workflows/docs-deploy.yml

@@ -0,0 +1,66 @@
+name: Deploy to GitHub Pages
+
+on:
+  pull_request:
+    branches:
+      - main
+    paths:
+      - "docs/**"
+  push:
+    branches:
+      - main
+    paths:
+      - "docs/**"
+  workflow_dispatch:
+
+jobs:
+  build:
+    name: Build Docusaurus
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+        with:
+          fetch-depth: 0
+          persist-credentials: false
+
+      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0
+        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@56afc609e74202658d3ffba0e8f6dda462b719fa # v3.0.1
+        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@d6db90164ac5ed86f2b6aed7e0febac5b3c0c03e # v4.0.5

README.md

@@ -1,4 +1,4 @@
-# Bolt <img src="https://raw.githubusercontent.com/slackapi/bolt-js/main/docs/img/bolt.svg" alt="Bolt logo" width="32"/> for JavaScript
+# Bolt <img src="https://raw.githubusercontent.com/slackapi/bolt-js/main/docs/static/img/bolt.svg" alt="Bolt logo" width="32"/> for JavaScript
 
 [![codecov](https://codecov.io/gh/slackapi/bolt-js/branch/main/graph/badge.svg?token=x4oCgiexvp)](https://codecov.io/gh/slackapi/bolt-js)
 [![Node.js CI](https://github.com/slackapi/bolt-js/actions/workflows/ci-build.yml/badge.svg)](https://github.com/slackapi/bolt-js/actions/workflows/ci-build.yml)

app.json

@@ -2,7 +2,7 @@
   "name": "Deploying to Heroku ⚡️ Bolt for JavaScript",
   "description": "This is a Slack app built with the Bolt for JavaScript framework that showcases deploying to the Heroku platform.",
   "keywords": ["slack", "heroku", "nodejs", "bolt", "bolt-js", "javascript"],
-  "logo": "https://raw.githubusercontent.com/slackapi/bolt-js/main/docs/img/bolt-logo.svg",
+  "logo": "https://raw.githubusercontent.com/slackapi/bolt-js/main/docs/static/img/bolt-logo.svg",
   "image": "heroku/nodejs",
   "website": "https://tools.slack.dev/bolt-js/",
   "repository": "https://github.com/slackapi/bolt-js",

biome.json

@@ -1,7 +1,7 @@
 {
   "$schema": "./node_modules/@biomejs/biome/configuration_schema.json",
   "files": {
-    "ignore": ["examples/**/dist"]
+    "ignore": ["docs/.docusaurus", "examples/**/dist"]
   },
   "formatter": {
     "enabled": true,

docs/.gitignore

@@ -0,0 +1,4 @@
+node_modules/
+.docusaurus
+.DS_Store
+build/

docs/README.md

@@ -0,0 +1,126 @@
+# tools.slack.dev/bolt-js
+
+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
+│   └── concepts
+│       └── sending-message.md
+├── i18n/ja-jp/ (the japanese translations)
+│   ├── docusaurus-theme-classic/ (footer/navbar translations)
+│   └── docusaurus-plugin-content-docs/
+│       └── current/ (this folder's file names need to match **/content/)
+│           ├── getting-started.md
+│           └── concepts
+│               └── sending-message.md
+├── static/
+│   ├── css/
+│   │   └── custom.css (the css for everything!)
+│   └── img/ (the pictures for the site)
+│       ├── rory.png 
+│       └── oslo.svg 
+├── src/
+│   ├── pages/ (stuff that isn't docs content. This is empty for this repo!)
+│   └── theme (only contains the 404 page)
+├── docusaurus.config.js (main config file)
+├── footerConfig.js (footer. go to main repo to change)
+├── navbarConfig.js (navbar. go to main repo to change)
+└── sidebar.js (manually set where the content docs are in the sidebar.)
+```
+
+A cheat-sheet:
+* _I want to edit a doc._ `content/*/*.md`
+* _I want to edit a Japanese doc._ `i18n/ja-jp/docusaurus-plugin-content-docs/current/*/*.md`. See the [Japanese docs README](./docs/README.md)
+* _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.
+3. Add the doc's path to the sidebar within `docusaurus.config.js`. Where ever makes most sense for you.
+4. 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://raw.githubusercontent.com/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
+open http://localhost:3000/bolt-python/getting-started # visit a page
+```
+
+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 Bolt-JS docs right now.
+
+#### Running locally in Japanese
+
+For local runs, Docusaurus treats each language as a different instance of the website. You'll want to specify the language to run the japanese site locally:
+
+```
+npm run start -- --locale ja-jp
+```
+
+Don't worry - both languages will be built/served on deployment. 
+
+---
+
+## 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.
+
+---
+
+## Something's broken
+
+Luke goofed. Open an issue please! `:bufo-appreciates-the-insight:`

docs/babel.config.js

@@ -0,0 +1,3 @@
+module.exports = {
+  presets: [require.resolve('@docusaurus/core/lib/babel/preset')],
+};

docs/english/building-an-app.md → docs/content/building-an-app.md

@@ -23,7 +23,7 @@ After you fill out an app name (_you can change it later_) and pick a workspace
 
 This page contains an overview of your app in addition to important credentials you'll need later, like the `Signing Secret` under the **App Credentials** header.
 
-![Basic Information page](/img/bolt-js/basic-information-page.png "Basic Information page")
+![Basic Information page](/img/basic-information-page.png "Basic Information page")
 
 Look around, add an app icon and description, and then let's start configuring your app. 🔩
 
@@ -49,7 +49,7 @@ We're going to use bot and app tokens for this guide.
 
 4. Once you authorize the installation, you'll land on the **OAuth & Permissions** page and see a **Bot User OAuth Access Token**.
 
-![OAuth Tokens](/img/bolt-js/bot-token.png "Bot OAuth Token")
+![OAuth Tokens](/img/bot-token.png "Bot OAuth Token")
 
 :::tip[Not sharing is sometimes caring]
 
@@ -136,7 +136,7 @@ To listen for events happening in a Slack workspace (like when a message is post
 
 For those just starting, we recommend using [Socket Mode](https://docs.slack.dev/apis/events-api/using-socket-mode/). Socket Mode allows your app to use the Events API and interactive features without exposing a public HTTP Request URL. This can be helpful during development, or if you're receiving requests from behind a firewall.
 
-That being said, you're welcome to set up an app with a public HTTP Request URL. HTTP is more useful for apps being deployed to hosting environments (like [AWS](/bolt-js/deployments/aws-lambda) or [Heroku](/bolt-js/deployments/heroku)) to stably respond within a large corporate Slack workspaces/organization, or apps intended for distribution via the Slack Marketplace.
+That being said, you're welcome to set up an app with a public HTTP Request URL. HTTP is more useful for apps being deployed to hosting environments (like [AWS](/deployments/aws-lambda) or [Heroku](/deployments/heroku)) to stably respond within a large corporate Slack workspaces/organization, or apps intended for distribution via the Slack Marketplace.
 
 We've provided instructions for both ways in this guide.
 
@@ -490,8 +490,8 @@ Now that you have a basic app up and running, you can start exploring how to mak
 
 - Read through the concepts pages to learn about the different methods and features your Bolt app has access to.
 
-- Explore the different events your bot can listen to with the [`events()`](/bolt-js/concepts/event-listening) method. All of the events are listed on the [API docs site](https://docs.slack.dev/reference/events).
+- Explore the different events your bot can listen to with the [`events()`](/concepts/event-listening) method. All of the events are listed on the [API docs site](https://docs.slack.dev/reference/events).
 
-- Bolt allows you to [call Web API methods](/bolt-js/concepts/web-api) with the client attached to your app. There are [over 200 methods](https://docs.slack.dev/reference/methods) on the API docs site.
+- Bolt allows you to [call Web API methods](/concepts/web-api) with the client attached to your app. There are [over 200 methods](https://docs.slack.dev/reference/methods) on the API docs site.
 
 - Learn more about the different token types [on the API docs site](https://docs.slack.dev/authentication/tokens). Your app may need different tokens depending on the actions you want it to perform.

docs/english/concepts/acknowledge.md → docs/content/concepts/acknowledge.md

@@ -1,7 +1,7 @@
 ---
 title: Acknowledging requests
 lang: en
-slug: /bolt-js/concepts/acknowledge
+slug: /concepts/acknowledge
 ---
 
 Actions, commands, and options requests must **always** be acknowledged using the `ack()` function. This lets Slack know that the request was received and updates the Slack user interface accordingly. Depending on the type of request, your acknowledgement may be different. For example, when acknowledging a modal submission you will call `ack()` with validation errors if the submission contains errors, or with no parameters if the submission is valid.

docs/english/concepts/actions.md → docs/content/concepts/actions.md

@@ -1,7 +1,7 @@
 ---
 title: Listening & responding to actions
 lang: en
-slug: /bolt-js/concepts/actions
+slug: /concepts/actions
 ---
 
 Your app can listen and respond to user actions like button clicks, and menu selects, using the `action` method.
@@ -10,7 +10,7 @@ Your app can listen and respond to user actions like button clicks, and menu sel
 
 Actions can be filtered on an `action_id` of type string or RegExp object. `action_id`s act as unique identifiers for interactive components on the Slack platform. 
 
-You’ll notice in all `action()` examples, `ack()` is used. It is required to call the `ack()` function within an action listener to acknowledge that the request was received from Slack. This is discussed in the [acknowledging requests section](/bolt-js/concepts/acknowledge).
+You’ll notice in all `action()` examples, `ack()` is used. It is required to call the `ack()` function within an action listener to acknowledge that the request was received from Slack. This is discussed in the [acknowledging requests section](/concepts/acknowledge).
 
 View more information about the `block_actions` payload within the [relevant API documentation page](https://docs.slack.dev/reference/interaction-payloads). To access the full payload of a view from within a listener, reference the `body` argument within your callback function.
 

docs/english/concepts/ai-apps.md → docs/content/concepts/ai-apps.md

@@ -1,7 +1,7 @@
 ---
 title: AI Apps
 lang: en
-slug: /bolt-js/concepts/ai-apps
+slug: /concepts/ai-apps
 ---
 
 :::info[This feature requires a paid plan]
@@ -25,12 +25,12 @@ AI apps comprise a new messaging experience for Slack. If you're unfamiliar with
   * [`message.im`](https://docs.slack.dev/reference/events/message.im)
 
 :::info
-You _could_ implement your own AI app by [listening](/bolt-js/concepts/event-listening) for the `assistant_thread_started`, `assistant_thread_context_changed`, and `message.im` events. That being said, using the `Assistant` class will streamline the process. And we already wrote this nice guide for you!
+You _could_ implement your own AI app by [listening](/concepts/event-listening) for the `assistant_thread_started`, `assistant_thread_context_changed`, and `message.im` events. That being said, using the `Assistant` class will streamline the process. And we already wrote this nice guide for you!
 :::
 
 ## The `Assistant` class instance
 
-The [`Assistant`](/bolt-js/reference#the-assistantconfig-configuration-object) can be used to handle the incoming events expected from a user interacting with an AI app in Slack. A typical flow would look like:
+The [`Assistant`](/reference#the-assistantconfig-configuration-object) can be used to handle the incoming events expected from a user interacting with an AI app in Slack. A typical flow would look like:
 
 1. [The user starts a thread](#handling-new-thread). The `Assistant` class handles the incoming [`assistant_thread_started`](https://docs.slack.dev/reference/events/assistant_thread_started) event.
 2. [The thread context may change at any point](#handling-thread-context-changes). The `Assistant` class can handle any incoming [`assistant_thread_context_changed`](https://docs.slack.dev/reference/events/assistant_thread_context_changed) events. The class also provides a default `context` store to keep track of thread context changes as the user moves through Slack.
@@ -57,7 +57,7 @@ While the `assistant_thread_started` and `assistant_thread_context_changed` even
 If you do provide your own `threadContextStore` property, it must feature `get` and `save` methods.
 
 :::tip
-Be sure to give the [AI apps reference docs](/bolt-js/reference#agents-assistants) a look!
+Be sure to give the [AI apps reference docs](/reference#agents--assistants) a look!
 :::
 
 ## Handling a new thread {#handling-new-thread}
@@ -108,7 +108,7 @@ When the user messages your AI app, the [`message.im`](https://docs.slack.dev/re
 
 Messages sent to the app do not contain a [subtype](https://docs.slack.dev/reference/events/message/#subtypes) and must be deduced based on their shape and any provided [message metadata](https://docs.slack.dev/messaging/message-metadata/).
 
-There are three [utilities](/bolt-js/reference#the-assistantconfig-configuration-object) that are particularly useful in curating the user experience:
+There are three [utilities](/reference#the-assistantconfig-configuration-object) that are particularly useful in curating the user experience:
 * `say`
 * `setTitle`
 * `setStatus`