diff --git a/.github/maintainers_guide.md b/.github/maintainers_guide.md index f244d3ad..b7b251fa 100644 --- 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 deleted file mode 100644 index 19a46eeb..00000000 --- a/.github/workflows/sync-docs.yml +++ /dev/null @@ -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 }} diff --git a/docs/_sidebar.json b/docs/_sidebar.json new file mode 100644 index 00000000..e9b5e822 --- /dev/null +++ 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": "
" }, + "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" + ] \ No newline at end of file diff --git a/docs/sending-variables.md b/docs/sending-variables.md index f19d95ec..0e269ee0 100644 --- 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.