build: clone repository "docs" and configuration when syncing project docs (#467)

.github/maintainers_guide.md

@@ -90,6 +90,39 @@ level of information with labels. An issue should have **one** of the following
 Issues are closed when a resolution has been reached. If for any reason a closed issue seems
 relevant once again, reopening is great and better than creating a duplicate issue.
 
+## Docs
+
+This repo 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.
+
+We appreciate markdown edits from anyone!!! 
+
+### Sidebar
+
+`_sidebar.json` sets the slack github action docs sidebar 
+
+sidebar values take the form of "slack-github-action/path-within-docs/"
+
+or, in other words - full path but remove "docs":
+path: slack-github-action/docs/sending-variables.md
+value: slack-github-action/sending-variables
+
+for info on syntax see https://docusaurus.io/docs/sidebar
+
+this file is copied into slackapi.github.io/slack-github-action/sidebar.js it is then called in slackapi.github.io/sidebars.js
+
 ## Everything else
 
 When in doubt, find the other maintainers and ask.

.github/workflows/sync-docs.yml

@@ -1,77 +0,0 @@
-name: Sync docs to docs site repo
-
-on:
-  pull_request:
-    branches:
-      - main
-    paths:
-      - "docs/**"
-  workflow_dispatch:
-
-jobs:
-  config-sync:
-    name: Sync docs to docs site repo
-    runs-on: ubuntu-latest
-    permissions:
-      contents: read
-
-    steps:
-      - name: Generate a GitHub token
-        id: ghtoken
-        uses: actions/create-github-app-token@df432ceedc7162793a195dd1713ff69aefc7379e # v2.0.6
-        with:
-          app-id: ${{ secrets.GH_APP_ID }}
-          owner: slackapi
-          private-key: ${{ secrets.GH_APP_PRIVATE_KEY }}
-
-      - name: Checkout the tool repo (source)
-        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
-        with:
-          persist-credentials: false
-
-      - name: Checkout the docs site repo (destination)
-        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
-        with:
-          repository: slackapi/slackapi.github.io
-          path: "docs_repo"
-          token: ${{ steps.ghtoken.outputs.token }}
-          persist-credentials: false
-
-      - name: Update docs in docs site repo
-        run: |
-          rsync -av --delete ./docs/ "./docs_repo/content/$REPO/"
-        env:
-          REPO: ${{ github.event.repository.name }}
-
-      - name: Install dependencies
-        run: |
-          cd docs_repo
-          npm ci
-
-      - name: Build Docusaurus site
-        run: |
-          cd docs_repo
-          npm run build
-
-      - name: Create a pull request
-        if: ${{ github.event.pull_request.merged || github.event_name == 'workflow_dispatch' }}
-        id: site-pr
-        uses: peter-evans/create-pull-request@271a8d0340265f705b14b6d32b9829c1cb33d45e # v7.0.8
-        with:
-          token: ${{ steps.ghtoken.outputs.token }}
-          title: "From ${{ github.event.repository.name }}: ${{ github.event.pull_request.title || 'manual docs sync' }}"
-          body: "${{ github.event.pull_request.body }}"
-          author: "slackapi[bot] <186980925+slackapi[bot]@users.noreply.github.com>"
-          committer: "slackapi[bot] <186980925+slackapi[bot]@users.noreply.github.com>"
-          commit-message: "Sync docs from ${{ github.event.repository.name }} to docs site repo"
-          base: "main"
-          branch: "docs-sync-${{ github.event.repository.name }}-${{ github.sha }}"
-          labels: docs
-          path: "./docs_repo"
-
-      - name: Output the pull request link
-        if: ${{ steps.site-pr.outputs.pull-request-url }}
-        run: |
-          echo "Pull request created: $URL" >> $GITHUB_STEP_SUMMARY
-        env:
-          URL: ${{ steps.site-pr.outputs.pull-request-url }}

docs/_sidebar.json

@@ -0,0 +1,64 @@
+[
+    {
+      "type": "doc",
+      "id": "slack-github-action/slack-github-action",
+      "label": "Slack GitHub Action",
+      "className": "sidebar-title"
+    },
+    { "type": "html", "value": "<hr>" },
+    "slack-github-action/sending-variables",
+    {
+      "type": "category",
+      "label": "Sending techniques",
+      "collapsed": false,
+      "link": {
+        "type": "doc",
+        "id": "slack-github-action/sending-techniques/sending-techniques"
+      },
+      "items": [
+        "slack-github-action/sending-techniques/sending-techniques",
+        {
+          "type": "category",
+          "label": "Sending data via a webhook to start a Slack workflow",
+          "link": {
+            "type": "doc",
+            "id": "slack-github-action/sending-techniques/sending-data-webhook-slack-workflow/sending-data-webhook-slack-workflow"
+          },
+          "items": [
+            "slack-github-action/sending-techniques/sending-data-webhook-slack-workflow/sending-data-webhook-slack-workflow",
+            "slack-github-action/sending-techniques/sending-data-webhook-slack-workflow/format-generated-files",
+            "slack-github-action/sending-techniques/sending-data-webhook-slack-workflow/post-release-announcements",
+            "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": "slack-github-action/sending-techniques/sending-data-slack-api-method/sending-data-slack-api-method"
+          },
+          "items": [
+            "slack-github-action/sending-techniques/sending-data-slack-api-method/sending-data-slack-api-method",
+            "slack-github-action/sending-techniques/sending-data-slack-api-method/direct-message-author",
+            "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": "slack-github-action/sending-techniques/sending-data-slack-incoming-webhook/sending-data-slack-incoming-webhook"
+          },
+          "items": [
+            "slack-github-action/sending-techniques/sending-data-slack-incoming-webhook/sending-data-slack-incoming-webhook",
+            "slack-github-action/sending-techniques/sending-data-slack-incoming-webhook/post-inline-text-message",
+            "slack-github-action/sending-techniques/sending-data-slack-incoming-webhook/post-inline-block-message",
+            "slack-github-action/sending-techniques/sending-data-slack-incoming-webhook/post-blocks-found-in-file"
+          ]
+        }
+      ]
+    },
+    "slack-github-action/additional-configurations"
+  ] 

docs/sending-variables.md

@@ -1,4 +1,4 @@
-# Sending variables 
+# Sending variables
 
 There are different [techniques to send data](/slack-github-action/sending-techniques) into Slack and whichever one is chosen will require a certain set of customized inputs, as described later.