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

lukegalbraithrussell · web-flow · commit a7f5b68f29d9 · 2025-06-24T18:25:16.000-07:00
diff --git a/.github/maintainers_guide.md b/.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.
diff --git a/.github/workflows/sync-docs.yml b/.github/workflows/sync-docs.yml
diff --git a/docs/_sidebar.json b/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"
+  ] 
diff --git a/docs/sending-variables.md b/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.
 

Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		`-# Sending variables`
	`1`	`+# Sending variables`
`2`	`2`
`3`	`3`	`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.`
`4`	`4`