docs: general page cleanup

docs/content/concepts/actions.md

@@ -64,7 +64,6 @@ app.action('approve_button', async ({ ack, say }) => {
 });
 ```
 
-
 ### Using the `respond()` utility 
 
 Since `respond()` is a utility for calling the `response_url`, it behaves in the same way. You can pass a JSON object with a new message payload that will be published back to the source of the original interaction with optional properties like `response_type` (which has a value of `in_channel` or `ephemeral`), `replace_original`, and `delete_original`.

docs/content/concepts/authorization.md

@@ -6,7 +6,11 @@ slug: /concepts/authorization
 
 Authorization is the process of deciding which Slack credentials (such as a bot token) should be available while processing a specific incoming request.
 
-Custom apps installed on a single workspace can simply use the `token` option at the time of `App` initialization. However, when your app needs to handle several tokens, such as cases where it will be installed on multiple workspaces or needs access to more than one user token, the `authorize` option should be used instead. <b>If you're using the [built-in OAuth support](/concepts/authenticating-oauth) authorization is handled by default, so you do not need to pass in an `authorize` option.</b>
+Custom apps installed on a single workspace can simply use the `token` option at the time of `App` initialization. However, when your app needs to handle several tokens, such as cases where it will be installed on multiple workspaces or needs access to more than one user token, the `authorize` option should be used instead. 
+
+:::tip
+If you're using the [built-in OAuth support](/concepts/authenticating-oauth) authorization is handled by default, so you do not need to pass in an `authorize` option.
+:::
 
 The `authorize` option can be set to a function that takes an event source as its input, and should return a Promise for an object containing the authorized credentials. The source contains information about who and where the request is coming from by using properties like `teamId` (always available), `userId`, `conversationId`, and `enterpriseId`.
 

docs/content/concepts/custom-routes.md

@@ -48,11 +48,7 @@ const app = new App({
 })();
 ```
 
-<details>
-<summary>
-Custom ExpressReceiver routes
-</summary>
-
+## Custom ExpressReceiver routes
 
 Adding custom HTTP routes is quite straightforward when using Bolt’s built-in ExpressReceiver. Since `v2.1.0`, `ExpressReceiver` added a `router` property, which exposes the Express [Router](http://expressjs.com/en/4x/api.html#router) on which additional routes and middleware can be added.
 
@@ -91,5 +87,4 @@ receiver.router.post('/secret-page', (req, res) => {
   await app.start();
   console.log('⚡️ Bolt app started');
 })();
-```
-</details>
+```

docs/content/concepts/custom-steps.md

@@ -29,10 +29,7 @@ app.function('sample_custom_step', async ({ inputs, complete, fail, logger }) =>
 });
 ```
 
-<details>
-<summary>
-Example app manifest definition
-</summary>
+### Example app manifest definition
 
 ```json
 ...
@@ -60,8 +57,6 @@ Example app manifest definition
 }
 ```
 
-</details>
-
 ---
 
 ## Listening to custom step interactivity events
@@ -131,10 +126,7 @@ app.action('sample_button', async ({ ack, body, client, complete, fail, logger }
 });
 ```
 
-<details>
-<summary>
-Example app manifest definition
-</summary>
+### Example app manifest definition
 
 ```json
 ...
@@ -162,6 +154,4 @@ Example app manifest definition
 }
 ```
 
-</details>
-
 Learn more about responding to interactivity, see the [Slack API documentation](https://api.slack.com/automation/functions/custom-bolt#interactivity).

docs/content/concepts/deferring-initialization.md

@@ -8,7 +8,7 @@ Bolt offers a way to defer full initialization via the `deferInitialization` opt
 
 :::info
 
-If you call `start()` before `init()`, Bolt will raise an exception._
+If you call `start()` before `init()`, Bolt will raise an exception.
 
 :::
 

docs/content/concepts/error-handling.md

@@ -62,10 +62,7 @@ app.error(async (error) => {
 });
 ```
 
-<details>
-<summary>
-Accessing more data in the error handler
-</summary>
+## Accessing more data in the error handler
 
 There may be cases where you need to log additional data from a request in the global error handler. Or you may simply wish to have access to the `logger` you've passed into Bolt.
 
@@ -90,5 +87,4 @@ app.error(async ({ error, logger, context, body }) => {
     // Do something with the team's ID for debugging purposes
   }
 });
-```
-</details>
+```

docs/content/concepts/listener-middleware.md

@@ -10,7 +10,7 @@ There’s a collection of [built-in listener middleware](/reference#built-in-lis
 
 But of course, you can write your own middleware for more custom functionality. While writing your own middleware, your function must call `await next()` to pass control to the next middleware, or `throw` to pass an error back up the previously-executed middleware chain.
 
-As an example, let’s say your listener should only deal with messages from humans. You can write a listener middleware th
+As an example, let’s say your listener should only deal with messages from humans. You can write a listener middleware that excludes any bot messages.
 
 ```javascript
 // Listener middleware that filters out messages with 'bot_message' subtype

docs/content/concepts/logging.md

@@ -18,10 +18,7 @@ const app = new App({
 });
 ```
 
-<details>
-<summary>
-Sending log output somewhere besides the console
-</summary>
+## Sending log output somewhere besides the console
 
 If you want to send logs to somewhere besides the console or want more control over the logger, you can implement a custom logger. A custom logger must implement specific methods (known as the `Logger` interface):
 
@@ -57,4 +54,3 @@ const app = new App({
   },
 });
 ```
-</details>

docs/content/concepts/message-sending.md

@@ -15,10 +15,7 @@ app.message('knock knock', async ({ message, say }) => {
 });
 ```
 
-<details>
-<summary>
-Sending a message with blocks
-</summary>
+## Sending a message with blocks
 
 `say()` accepts more complex message payloads to make it easy to add functionality and structure to your messages.
 
@@ -48,5 +45,4 @@ app.event('reaction_added', async ({ event, say }) => {
     });
   }
 });
-```
-</details>
+```

docs/content/concepts/receiver.md

@@ -107,7 +107,7 @@ class SimpleReceiver  {
     })
   }
 
-  // This is a very simple implementation. Look at the ExpressReceiver source for more detail
+  // This is a simple implementation. Look at the ExpressReceiver source for more detail
   async requestHandler(req, res) {
     let ackCalled = false;
     // Assume parseBody function exists to parse incoming requests

docs/content/concepts/select-menu-options.md

@@ -4,7 +4,7 @@ lang: en
 slug: /concepts/options
 ---
 
-The `options()` method listens for incoming option request payloads from Slack. [Similar to `action()`](/concepts/actions),
+The `options()` method listens for incoming option request payloads from Slack. Similar to the [`action()`](/concepts/actions) method,
 an `action_id` or constraints object is required.
 
 While it's recommended to use `action_id` for `external_select` menus, dialogs do not yet support Block Kit so you'll have to 

docs/content/concepts/shortcuts.md

@@ -76,59 +76,55 @@ app.shortcut('open_modal', async ({ shortcut, ack, client, logger }) => {
 });
 ```
 
-<details>
-  <summary>
-  Listening to shortcuts using a constraint object
-  </summary>
+## Listening to shortcuts using a constraint object
 
-  You can use a constraints object to listen to `callback_id` and `type` values. Constraints in the object can be of type string or RegExp object.
+You can use a constraints object to listen to `callback_id` and `type` values. Constraints in the object can be of type string or RegExp object.
 
-  ```javascript
-  // Your middleware will only be called when the callback_id matches 'open_modal' AND the type matches 'message_action'
-  app.shortcut({ callback_id: 'open_modal', type: 'message_action' }, async ({ shortcut, ack, client, logger }) => {
-    try {
-      // Acknowledge shortcut request
-      await ack();
-
-      // Call the views.open method using one of the built-in WebClients
-      const result = await client.views.open({
-        trigger_id: shortcut.trigger_id,
-        view: {
-          type: "modal",
-          title: {
-            type: "plain_text",
-            text: "My App"
-          },
-          close: {
-            type: "plain_text",
-            text: "Close"
+```javascript
+// Your middleware will only be called when the callback_id matches 'open_modal' AND the type matches 'message_action'
+app.shortcut({ callback_id: 'open_modal', type: 'message_action' }, async ({ shortcut, ack, client, logger }) => {
+  try {
+    // Acknowledge shortcut request
+    await ack();
+
+    // Call the views.open method using one of the built-in WebClients
+    const result = await client.views.open({
+      trigger_id: shortcut.trigger_id,
+      view: {
+        type: "modal",
+        title: {
+          type: "plain_text",
+          text: "My App"
+        },
+        close: {
+          type: "plain_text",
+          text: "Close"
+        },
+        blocks: [
+          {
+            type: "section",
+            text: {
+              type: "mrkdwn",
+              text: "About the simplest modal you could conceive of :smile:\n\nMaybe <https://api.slack.com/reference/block-kit/interactive-components|*make the modal interactive*> or <https://api.slack.com/surfaces/modals/using#modifying|*learn more advanced modal use cases*>."
+            }
           },
-          blocks: [
-            {
-              type: "section",
-              text: {
+          {
+            type: "context",
+            elements: [
+              {
                 type: "mrkdwn",
-                text: "About the simplest modal you could conceive of :smile:\n\nMaybe <https://api.slack.com/reference/block-kit/interactive-components|*make the modal interactive*> or <https://api.slack.com/surfaces/modals/using#modifying|*learn more advanced modal use cases*>."
+                text: "Psssst this modal was designed using <https://api.slack.com/tools/block-kit-builder|*Block Kit Builder*>"
               }
-            },
-            {
-              type: "context",
-              elements: [
-                {
-                  type: "mrkdwn",
-                  text: "Psssst this modal was designed using <https://api.slack.com/tools/block-kit-builder|*Block Kit Builder*>"
-                }
-              ]
-            }
-          ]
-        }
-      });
-
-      logger.info(result);
-    }
-    catch (error) {
-      logger.error(error);
-    }
-  });
-  ```
-</details>
+            ]
+          }
+        ]
+      }
+    });
+
+    logger.info(result);
+  }
+  catch (error) {
+    logger.error(error);
+  }
+});
+```

docs/content/concepts/socket-mode.md

@@ -23,10 +23,7 @@ const app = new App({
 })();
 ```
 
-<details>
-<summary>
-Custom SocketMode Receiver
-</summary>
+## Custom SocketMode Receiver
 
 You can define a custom `SocketModeReceiver` by importing it from `@slack/bolt`.
 
@@ -53,6 +50,4 @@ const app = new App({
   await app.start();
   console.log('⚡️ Bolt app started');
 })();
-```
-
-</details>
+```

docs/content/concepts/updating-pushing-views.md

@@ -4,15 +4,15 @@ lang: en
 slug: /concepts/updating-pushing-views
 ---
 
-Modals contain a stack of views. When you call [`views.open`](https://api.slack.com/methods/views.open), you add the root view to the modal. After the initial call, you can dynamically update a view by calling [`views.update`](https://api.slack.com/methods/views.update), or stack a new view on top of the root view by calling [`views.push`](https://api.slack.com/methods/views.push).
+Modals contain a stack of views. When you call the [`views.open`](https://api.slack.com/methods/views.open) method, you add the root view to the modal. After the initial call, you can dynamically update a view by calling the [`views.update`](https://api.slack.com/methods/views.update) method, or stack a new view on top of the root view by calling the [`views.push`](https://api.slack.com/methods/views.push) method.
 
-**`views.update`**
+## The `views.update` method
 
-To update a view, you can use the built-in client to call `views.update` with the `view_id` that was generated when you opened the view, and a new `view` including the updated `blocks` array. If you're updating the view when a user interacts with an element inside of an existing view, the `view_id` will be available in the `body` of the request.
+To update a view, you can use the built-in client to call the `views.update` method with the `view_id` parameter that was generated when you opened the view, and a new `view` object including the updated `blocks` array. If you're updating the view when a user interacts with an element inside of an existing view, the `view_id` parameter will be available in the `body` of the request.
 
-**`views.push`**
+## The `views.push` method
 
-To push a new view onto the view stack, you can use the built-in client to call `views.push` with a valid `trigger_id` a new [view payload](https://api.slack.com/reference/block-kit/views). The arguments for `views.push` is the same as [opening modals](/concepts/creating-modals). After you open a modal, you may only push two additional views onto the view stack.
+To push a new view onto the view stack, you can use the built-in client to call the `views.push` method by passing a valid `trigger_id` parameter and a new [view payload](https://api.slack.com/reference/block-kit/views). The arguments for the `views.push` method is the same as [`views.open`](/concepts/creating-modals). After you open a modal, you may only push two additional views onto the view stack.
 
 Learn more about updating and pushing views in our [API documentation](https://api.slack.com/surfaces/modals/using#modifying)
 

docs/content/concepts/view-submissions.md

@@ -10,7 +10,7 @@ Slack will send a `view_submission` request when a user submits a view. To recei
 If the `notify_on_close` field of a view has been set to `true`, Slack will also send a `view_closed` request if a user clicks the close button. See the section on **Handling views on close** for more detail.
 To listen to either a `view_submission` request or `view_closed` request, you can use the built-in `view()` method.
 
-`view()` requires a `callback_id` of type `string` or `RegExp` or a constraint object with properties `type` and `callback_id`. 
+The `view()` method requires a `callback_id` of type `string` or `RegExp` or a constraint object with properties `type` and `callback_id`. 
 
 ---
 
@@ -35,9 +35,11 @@ Read more about view submissions in our [API documentation](https://api.slack.co
 
 ## Handling views on close
 
-💡 When listening for `view_closed` requests, you must pass an object containing `type: 'view_closed'` and the view `callback_id`. See below for an example of this:
+When listening for `view_closed` requests, you must pass an object containing `type: 'view_closed'` and the view `callback_id`. See below for an example of this.
 
+:::tip 
 See the [API documentation](https://api.slack.com/surfaces/modals/using#modal_cancellations) for more information about `view_closed`.
+:::
 
 #### Handle a `view_closed` request
 

docs/content/concepts/web-api.md

@@ -8,9 +8,9 @@ You can call any [Web API method](https://api.slack.com/methods) using the [`Web
 
 Your Bolt app also has a top-level `app.client` which you can manually pass the `token` parameter. If the incoming request is not authorized or you're calling a method from outside of a listener, use the top-level `app.client`.
 
-Calling one of the [`WebClient`](https://tools.slack.dev/node-slack-sdk/web-api)'s methods will return a Promise containing the response from Slack, regardless of whether you use the top-level or listener's client.
+Calling one of the [`WebClient`](https://tools.slack.dev/node-slack-sdk/web-api) methods will return a Promise containing the response from Slack, regardless of whether you use the top-level or listener's client.
 
-Since the introduction of [org wide app installations](https://api.slack.com/enterprise/apps), [some web-api methods](https://api.slack.com/enterprise/apps/changes-apis#methods) now require `team_id` to indicate which workspace to act on. Bolt for JavaScript will attempt to infer the `team_id` based on incoming payloads and pass it along to `client`. This is handy for existing applications looking to add support for org wide installations and not spend time updating all of these web-api calls.
+Since the introduction of [org wide app installations](https://api.slack.com/enterprise/apps), [some web-api methods](https://api.slack.com/enterprise/apps/changes-apis#methods) now require a `team_id` parameter to indicate which workspace to act on. Bolt for JavaScript will attempt to infer the `team_id` value based on incoming payloads and pass it along to `client`. This is handy for existing applications looking to add support for org wide installations and not spend time updating all of these web-api calls.
 
 ```javascript
 // Unix Epoch time for September 30, 2019 11:59:59 PM