docs: streamlines doc structure

docs/_sidebar.json

@@ -1,78 +1,15 @@
 [
-    {
-      "type": "doc",
-      "id": "tools/slack-github-action/slack-github-action",
-      "label": "Slack GitHub Action",
-      "className": "sidebar-title"
-    },
-    { "type": "html", "value": "<hr>" },
-    "tools/slack-github-action/sending-variables",
-    {
-      "type": "category",
-      "label": "Sending techniques",
-      "collapsed": false,
-      "link": {
-        "type": "doc",
-        "id": "tools/slack-github-action/sending-techniques/sending-techniques"
-      },
-      "items": [
-        "tools/slack-github-action/sending-techniques/sending-techniques",
-        {
-          "type": "category",
-          "label": "Sending data via a webhook to start a Slack workflow",
-          "link": {
-            "type": "doc",
-            "id": "tools/slack-github-action/sending-techniques/sending-data-webhook-slack-workflow/sending-data-webhook-slack-workflow"
-          },
-          "items": [
-            "tools/slack-github-action/sending-techniques/sending-data-webhook-slack-workflow/sending-data-webhook-slack-workflow",
-            "tools/slack-github-action/sending-techniques/sending-data-webhook-slack-workflow/format-generated-files",
-            "tools/slack-github-action/sending-techniques/sending-data-webhook-slack-workflow/post-release-announcements",
-            "tools/slack-github-action/sending-techniques/sending-data-webhook-slack-workflow/update-a-channel-topic"
-          ]
-        },
-        {
-          "type": "category",
-          "label": "Sending data using a Slack API method",
-          "link": {
-            "type": "doc",
-            "id": "tools/slack-github-action/sending-techniques/sending-data-slack-api-method/sending-data-slack-api-method"
-          },
-          "items": [
-            "tools/slack-github-action/sending-techniques/sending-data-slack-api-method/sending-data-slack-api-method",
-            "tools/slack-github-action/sending-techniques/sending-data-slack-api-method/direct-message-author",
-            "tools/slack-github-action/sending-techniques/sending-data-slack-api-method/invite-usergroup-to-channel"
-          ]
-        },
-        {
-          "type": "category",
-          "label": "Sending data as a message with a Slack incoming webhook URL",
-          "link": {
-            "type": "doc",
-            "id": "tools/slack-github-action/sending-techniques/sending-data-slack-incoming-webhook/sending-data-slack-incoming-webhook"
-          },
-          "items": [
-            "tools/slack-github-action/sending-techniques/sending-data-slack-incoming-webhook/sending-data-slack-incoming-webhook",
-            "tools/slack-github-action/sending-techniques/sending-data-slack-incoming-webhook/post-inline-text-message",
-            "tools/slack-github-action/sending-techniques/sending-data-slack-incoming-webhook/post-inline-block-message",
-            "tools/slack-github-action/sending-techniques/sending-data-slack-incoming-webhook/post-blocks-found-in-file"
-          ]
-        },
-        {
-          "type": "category",
-          "label": "Running Slack CLI commands",
-          "link": {
-            "type": "doc",
-            "id": "tools/slack-github-action/sending-techniques/running-slack-cli-commands/running-slack-cli-commands"
-          },
-          "items": [
-            "tools/slack-github-action/sending-techniques/running-slack-cli-commands/running-slack-cli-commands",
-            "tools/slack-github-action/sending-techniques/running-slack-cli-commands/deploy-an-app",
-            "tools/slack-github-action/sending-techniques/running-slack-cli-commands/validate-a-manifest",
-            "tools/slack-github-action/sending-techniques/running-slack-cli-commands/manage-collaborators"
-          ]
-        }
-      ]
-    },
-    "tools/slack-github-action/additional-configurations"
-  ] 
+  {
+    "type": "doc",
+    "id": "tools/slack-github-action/slack-github-action",
+    "label": "Slack GitHub Action",
+    "className": "sidebar-title"
+  },
+  { "type": "html", "value": "<hr>" },
+  "tools/slack-github-action/gathering-variables",
+  "tools/slack-github-action/sending-data-webhook-slack-workflow",
+  "tools/slack-github-action/sending-data-slack-api-method",
+  "tools/slack-github-action/sending-data-slack-incoming-webhook",
+  "tools/slack-github-action/running-slack-cli-commands",
+  "tools/slack-github-action/additional-configurations"
+]

docs/additional-configurations.md

@@ -21,23 +21,6 @@ The `errors` option defaults to `false` so failed requests do not cause the step
 
 Invalid inputs to the GitHub Action, such as not including a payload, will always cause the GitHub step to fail.
 
-## Flattening nested payloads
-
-Variables and data provided in the payload might contain nested fields that need to be flattened before being sent with a [webhook trigger](/tools/slack-github-action/sending-techniques/sending-data-webhook-slack-workflow) to match the expected input format of [Workflow Builder](https://slack.com/features/workflow-automation).
-
-The `payload-delimiter` option will flatten the input payload using the provided delimiter and will also make values stringified:
-
-```yaml
-- name: Flatten the default GitHub payload
-  uses: slackapi/[email protected]
-  with:
-    payload-delimiter: "_"
-    webhook: ${{ secrets.SLACK_WEBHOOK_URL }}
-    webhook-type: webhook-trigger
-```
-
-Reference to the flattening implementation is available for exploration from within the [`flat`](https://www.npmjs.com/package/flat) package.
-
 ## Parsing templated variables
 
 Additional variables provided in the GitHub event [context](https://github.com/actions/toolkit/blob/main/packages/github/src/context.ts#L6) and event [payload](https://docs.github.com/en/webhooks/webhook-events-and-payloads) can be used to replace templated variables in the input payload with the `payload-templated` option:

docs/sending-variables.md → docs/gathering-variables.md

@@ -1,6 +1,6 @@
-# Sending variables
+# Gathering variables
 
-There are different [techniques to send data](/tools/slack-github-action/sending-techniques) into Slack and whichever one is chosen will require a certain set of customized inputs, as described later.
+There are different techniques to send data into Slack and whichever one is chosen will require a certain set of customized inputs, as described later.
 
 You can provide data to send to Slack from this GitHub Action and either source:
 

docs/sending-techniques/running-slack-cli-commands/running-slack-cli-commands.md → docs/running-slack-cli-commands.md

@@ -1,7 +1,3 @@
----
-sidebar_label: Overview
----
-
 # Running Slack CLI commands
 
 The Slack CLI technique installs and runs [Slack CLI](/tools/slack-cli/) commands directly from a GitHub Actions workflow.
@@ -82,6 +78,17 @@ steps:
       token: ${{ secrets.SLACK_SERVICE_TOKEN }}
 ```
 
+<details>
+<summary><strong>Workflow: Validate a manifest</strong></summary>
+
+This workflow validates the app manifest on pull requests to catch configuration issues early.
+
+```js reference
+https://github.com/slackapi/slack-github-action/blob/main/example-workflows/Technique_4_Slack_CLI_Command/manifest.yml
+```
+
+</details>
+
 ### Deploy an app with a service token
 
 ```yaml
@@ -93,8 +100,29 @@ steps:
       token: ${{ secrets.SLACK_SERVICE_TOKEN }}
 ```
 
-## Example workflows
+<details>
+<summary><strong>Workflow: Deploy an app</strong></summary>
+
+This workflow deploys a Slack app when changes are pushed to the main branch. It uses a service token to authenticate the deploy command.
+
+```js reference
+https://github.com/slackapi/slack-github-action/blob/main/example-workflows/Technique_4_Slack_CLI_Command/deploy.yml
+```
+
+</details>
+
+### Manage collaborators 
+
+<details>
+
+<summary><strong>Workflow: Manage collaborators</strong></summary>
+
+This workflow adds or removes an app collaborator using a manually triggered workflow.
+
+This example combines the Slack API technique ([`users.lookupByEmail`](https://docs.slack.dev/reference/methods/users.lookupByEmail), [`chat.postMessage`](https://docs.slack.dev/reference/methods/chat.postMessage)) with the CLI technique ([`collaborators add`](https://docs.slack.dev/tools/slack-cli/reference/commands/slack_collaborators_add)/[`remove`](https://docs.slack.dev/tools/slack-cli/reference/commands/slack_collaborators_remove)) to look up a user by email, update collaborators, and post a confirmation message.
+
+```js reference
+https://github.com/slackapi/slack-github-action/blob/main/example-workflows/Technique_4_Slack_CLI_Command/collaborators.yml
+```
 
-* [**Deploy an app**](/tools/slack-github-action/sending-techniques/running-slack-cli-commands/deploy-an-app): Deploy to Slack on push to the main branch.
-* [**Validate a manifest**](/tools/slack-github-action/sending-techniques/running-slack-cli-commands/validate-a-manifest): Check the app manifest on pull requests.
-* [**Manage collaborators**](/tools/slack-github-action/sending-techniques/running-slack-cli-commands/manage-collaborators): Add or remove an app collaborator using CLI and API techniques together.
+</details>

docs/sending-techniques/sending-data-slack-api-method/sending-data-slack-api-method.md → docs/sending-data-slack-api-method.md

@@ -1,7 +1,3 @@
----
-sidebar_label: Overview
----
-
 # Sending data using a Slack API method
 
 A bot token or user token or [token of some other kind](/authentication/tokens) must be used to call one of [the Slack API methods](/reference/methods) with this technique.
@@ -139,7 +135,47 @@ Calling [a Slack API method](/reference/methods) with [`@slack/web-api`](/tools/
       filename: "results-${{ github.sha }}.out"
 ```
 
+## Expected outputs
+
+The technique, like all Slack Github Action techniques, [outputs values](https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/passing-information-between-jobs) that can be used as inputs in following steps of a GitHub workflow.
+
+The following outputs are returned with each of the techniques:
+
+| Output | Type  | Description|
+|---|---|---|
+|`time` | `number` | The Unix [epoch time](https://en.wikipedia.org/wiki/Unix_time) that the step completed.
+| `ok` | `boolean` | If the request completed with success.
+| `response` | `string` | The [response](/apis/web-api/#responses) from the request as stringified JSON.
+
+While these outputs are returned with certain Slack API methods:
+
+| Output | Type  | Description|
+|---|---|---|
+|`channel_id` | `string` | The [channel ID](/reference/objects/conversation-object) included in the response.
+| `ts`| `string` | The [timestamp](/messaging/retrieving-messages#individual_messages) of the Slack event or message.
+| `thread_ts` | `string` | The [timestamp](/messaging/retrieving-messages#individual_messages) of a parent Slack message with [threaded replies](/messaging/retrieving-messages#pulling_threads).
+
 ## Example workflows
 
-- [**Direct message the author**](/tools/slack-github-action/sending-techniques/sending-data-slack-api-method/direct-message-author): Write to the Slack user with a matching email.
-- [**Invite a usergroup to channel**](/tools/slack-github-action/sending-techniques/sending-data-slack-api-method/invite-usergroup-to-channel): Create a channel and invite members.
+<details>
+<summary><strong>Direct message the author</strong></summary>
+
+This workflow sends a direct message to the user that pushed the most recent commits. It does so by grabbing the email of the pusher.
+
+```js reference
+https://github.com/slackapi/slack-github-action/blob/main/example-workflows/Technique_2_Slack_API_Method/author.yml
+```
+
+</details>
+
+<details>
+<summary><strong>Invite a usergroup to channel</strong></summary>
+
+This workflow creates a channel after a bug is reported and add members of a usergroup by chaining multiple Slack API method calls together.
+
+
+```js reference
+https://github.com/slackapi/slack-github-action/blob/main/example-workflows/Technique_2_Slack_API_Method/invite.yml
+```
+
+</details>

docs/sending-techniques/sending-data-slack-incoming-webhook/sending-data-slack-incoming-webhook.md → docs/sending-data-slack-incoming-webhook.md

@@ -1,7 +1,3 @@
----
-sidebar_label: Overview
----
-
 # Sending data as a message with a Slack incoming webhook URL
 
 This technique uses this Action to post a message to a channel or direct message with [incoming webhooks](/messaging/sending-messages-using-incoming-webhooks) and a Slack app.
@@ -44,8 +40,57 @@ Add the collected webhook from above to a GitHub workflow and configure the step
             text: "GitHub Action build result: ${{ job.status }}\n${{ github.event.pull_request.html_url || github.event.head_commit.url }}"
 ```
 
+## Expected outputs
+
+The technique, like all Slack Github Action techniques, [outputs values](https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/passing-information-between-jobs) that can be used as inputs in following steps of a GitHub workflow.
+
+The following outputs are returned with each of the techniques:
+
+| Output | Type  | Description|
+|---|---|---|
+|`time` | `number` | The Unix [epoch time](https://en.wikipedia.org/wiki/Unix_time) that the step completed.
+| `ok` | `boolean` | If the request completed with success.
+| `response` | `string` | The [response](/apis/web-api/#responses) from the request as stringified JSON.
+
 ## Example workflows
 
-* [**Post an inline text message**](/tools/slack-github-action/sending-techniques/sending-data-slack-incoming-webhook/post-inline-text-message)
-* [**Post an inline block message**](/tools/slack-github-action/sending-techniques/sending-data-slack-incoming-webhook/post-inline-block-message)
-* [**Post blocks found in a file**](/tools/slack-github-action/sending-techniques/sending-data-slack-incoming-webhook/post-blocks-found-in-file)
+<details>
+<summary><strong>Post an inline text message</strong></summary>
+
+This workflow uses incoming webhooks to post a plain text message.
+
+```js reference
+https://github.com/slackapi/slack-github-action/blob/main/example-workflows/Technique_3_Slack_Incoming_Webhook/text.yml
+```
+
+</details>
+
+<details>
+<summary><strong>Post an inline block message</strong></summary>
+
+This workflow uses incoming webhooks to post a message with Block Kit.
+
+```js reference
+https://github.com/slackapi/slack-github-action/blob/main/example-workflows/Technique_3_Slack_Incoming_Webhook/blocks.yml
+```
+
+</details>
+
+<details>
+<summary><strong>Post blocks found in a file</strong></summary>
+
+This workflow uses file data when posting to an incoming webhook. It links to the GitHub Actions job in progress.
+
+Payload file being sent
+
+```js reference
+https://github.com/slackapi/slack-github-action/blob/main/example-workflows/Technique_3_Slack_Incoming_Webhook/saved.data.json
+```
+
+### Workflow 
+
+```js reference
+https://github.com/slackapi/slack-github-action/blob/main/example-workflows/Technique_3_Slack_Incoming_Webhook/saved.gha.yml
+```
+
+</details>