website/.github/workflows/sync-docs.yml at main · stenopress/website · GitHub

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
name: Sync docs from steno release

on:
  schedule:
    - cron: "0 */6 * * *" # every 6 hours
  workflow_dispatch: {}

permissions:
  contents: write
  pull-requests: write

jobs:
  sync:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout website
        uses: actions/checkout@v4

      - name: Resolve latest GitHub release
        id: release
        run: |
          release="$(curl -fsSL -H 'Accept: application/vnd.github+json' https://api.github.com/repos/stenopress/steno/releases/latest)"
          tag="$(printf '%s\n' "$release" | sed -n 's/^[[:space:]]*"tag_name":[[:space:]]*"\([^"]*\)".*/\1/p' | head -n 1)"
          if [ -z "$tag" ]; then
            echo "Could not resolve latest release tag from GitHub" >&2
            exit 1
          fi
          version="${tag#v}"
          echo "version=${version}" >> "$GITHUB_OUTPUT"
          echo "tag=${tag}" >> "$GITHUB_OUTPUT"

      - name: Checkout steno docs at release tag
        uses: actions/checkout@v4
        with:
          repository: stenopress/steno
          ref: ${{ steps.release.outputs.tag }}
          sparse-checkout: |
            docs
          sparse-checkout-cone-mode: false
          path: upstream-steno

      - name: Sync docs-source
        run: |
          rsync -a --delete upstream-steno/docs/ docs-source/
          printf "%s\n" "${{ steps.release.outputs.tag }}" > docs-source/.upstream-release
          rm -rf upstream-steno

      - name: Escape literal {@include "..."} examples
        # Steno's own Tau docs demonstrate `{@include "path"}` as prose - left
        # unescaped, Steno's content-level include scanner (which runs on raw
        # Markdown, code fences included) tries to resolve those as real
        # includes and hard-fails the build. Every occurrence found in this
        # docs-source corpus so far has been illustrative, never a real
        # include, so this blanket escape is safe here. See
        # docs-source/content.md#markdown-includes for the mechanism.
        run: |
          perl -pi -e 's/\{(\@include\s+"[^"]*")\}/&#123;$1}/g' docs-source/*.md

      - name: Set up Deno
        uses: denoland/setup-deno@v2
        with:
          deno-version: v2.x

      - name: Reconcile docs navigation
        # Adds any docs-source page missing from the sidebar nav (under an
        # "Unsorted (needs placement)" section, so a new page is never
        # silently orphaned) and drops nav entries for pages upstream
        # removed. See .github/scripts/sync_docs_navigation.ts.
        run: deno run -A .github/scripts/sync_docs_navigation.ts

      - name: Check for changes
        id: diff
        run: |
          if git diff --quiet -- docs-source content/_data/docs_navigation.yml; then
            echo "changed=false" >> "$GITHUB_OUTPUT"
          else
            echo "changed=true" >> "$GITHUB_OUTPUT"
          fi

      - name: Check for unsorted navigation entries
        id: unsorted
        run: |
          if grep -q '^- label: Unsorted (needs placement)$' content/_data/docs_navigation.yml; then
            echo "found=true" >> "$GITHUB_OUTPUT"
          else
            echo "found=false" >> "$GITHUB_OUTPUT"
          fi

      - name: Open pull request
        if: steps.diff.outputs.changed == 'true'
        uses: peter-evans/create-pull-request@v7
        with:
          token: ${{ secrets.DOCS_SYNC_TOKEN || github.token }}
          commit-message: "chore(docs): sync docs-source to steno ${{ steps.release.outputs.tag }}"
          title: "chore(docs): sync docs-source to steno ${{ steps.release.outputs.tag }}"
          body: >
            Automated sync of `docs-source/` from the latest published
            [stenopress/steno](https://github.com/stenopress/steno)
            GitHub release (`${{ steps.release.outputs.tag }}`), using that
            tag as the source of `docs/`. Literal `{@include "..."}` examples
            were escaped and `content/_data/docs_navigation.yml` was
            reconciled with the synced pages automatically.
            ${{ steps.unsorted.outputs.found == 'true' && '⚠️ New pages landed in an "Unsorted (needs placement)" nav section - move them into the right place before merging.' || '' }}
            Review the diff before merging - a doc rename or removal can
            break `/docs/*` routes here.
          branch: sync-docs-source
          delete-branch: true