From 8c7fa74d79d1104ebf6bea6d6dace59d2c207082 Mon Sep 17 00:00:00 2001 From: Tai Sakuma Date: Sat, 21 Mar 2026 14:56:07 -0400 Subject: [PATCH 1/5] refactor: move override_site_url.py to .github/scripts/ Co-Authored-By: Claude Opus 4.6 (1M context) --- {scripts => .github/scripts}/override_site_url.py | 0 .github/workflows/docs-pr-preview.yml | 2 +- .github/workflows/docs-release.yml | 2 +- .github/workflows/docs.yml | 2 +- 4 files changed, 3 insertions(+), 3 deletions(-) rename {scripts => .github/scripts}/override_site_url.py (100%) diff --git a/scripts/override_site_url.py b/.github/scripts/override_site_url.py similarity index 100% rename from scripts/override_site_url.py rename to .github/scripts/override_site_url.py diff --git a/.github/workflows/docs-pr-preview.yml b/.github/workflows/docs-pr-preview.yml index 878e225..293268f 100644 --- a/.github/workflows/docs-pr-preview.yml +++ b/.github/workflows/docs-pr-preview.yml @@ -22,7 +22,7 @@ jobs: - name: Build docs run: | - uv run --group docs python scripts/override_site_url.py "pr/${{ github.event.number }}" + uv run --group docs python .github/scripts/override_site_url.py "pr/${{ github.event.number }}" uv run --group docs zensical build --clean --config-file zensical.local.toml cp -r site /tmp/built-site diff --git a/.github/workflows/docs-release.yml b/.github/workflows/docs-release.yml index 5b6dd9e..1b48709 100644 --- a/.github/workflows/docs-release.yml +++ b/.github/workflows/docs-release.yml @@ -33,7 +33,7 @@ jobs: - name: Build docs run: | - uv run --group docs python scripts/override_site_url.py "${{ steps.version.outputs.version }}" + uv run --group docs python .github/scripts/override_site_url.py "${{ steps.version.outputs.version }}" uv run --group docs zensical build --clean --config-file zensical.local.toml cp -r site /tmp/built-site diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index 0ea5444..fb743cd 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -22,7 +22,7 @@ jobs: - name: Build docs run: | - uv run --group docs python scripts/override_site_url.py dev + uv run --group docs python .github/scripts/override_site_url.py dev uv run --group docs zensical build --clean --config-file zensical.local.toml cp -r site /tmp/built-site From 7b69015f723835e6f23830377bafe6e679cfbf0c Mon Sep 17 00:00:00 2001 From: Tai Sakuma Date: Sat, 21 Mar 2026 14:56:27 -0400 Subject: [PATCH 2/5] refactor: extract build-docs composite action Co-Authored-By: Claude Opus 4.6 (1M context) --- .github/actions/build-docs/action.yml | 16 ++++++++++++++++ .github/workflows/docs-pr-preview.yml | 8 +++----- .github/workflows/docs-release.yml | 8 +++----- .github/workflows/docs.yml | 8 +++----- 4 files changed, 25 insertions(+), 15 deletions(-) create mode 100644 .github/actions/build-docs/action.yml diff --git a/.github/actions/build-docs/action.yml b/.github/actions/build-docs/action.yml new file mode 100644 index 0000000..0e1bf9a --- /dev/null +++ b/.github/actions/build-docs/action.yml @@ -0,0 +1,16 @@ +name: Build docs +description: Build docs with site_url overridden for subdirectory deployment + +inputs: + subdir: + description: Subdirectory to deploy to (e.g., dev, 1.0.0, pr/3) + required: true + +runs: + using: composite + steps: + - shell: bash + run: | + uv run --group docs python .github/scripts/override_site_url.py "${{ inputs.subdir }}" + uv run --group docs zensical build --clean --config-file zensical.local.toml + cp -r site /tmp/built-site diff --git a/.github/workflows/docs-pr-preview.yml b/.github/workflows/docs-pr-preview.yml index 293268f..241eff4 100644 --- a/.github/workflows/docs-pr-preview.yml +++ b/.github/workflows/docs-pr-preview.yml @@ -20,11 +20,9 @@ jobs: - uses: astral-sh/setup-uv@v7 - - name: Build docs - run: | - uv run --group docs python .github/scripts/override_site_url.py "pr/${{ github.event.number }}" - uv run --group docs zensical build --clean --config-file zensical.local.toml - cp -r site /tmp/built-site + - uses: ./.github/actions/build-docs + with: + subdir: pr/${{ github.event.number }} - name: Get preview URL id: preview diff --git a/.github/workflows/docs-release.yml b/.github/workflows/docs-release.yml index 1b48709..1779f17 100644 --- a/.github/workflows/docs-release.yml +++ b/.github/workflows/docs-release.yml @@ -31,11 +31,9 @@ jobs: - uses: astral-sh/setup-uv@v7 - - name: Build docs - run: | - uv run --group docs python .github/scripts/override_site_url.py "${{ steps.version.outputs.version }}" - uv run --group docs zensical build --clean --config-file zensical.local.toml - cp -r site /tmp/built-site + - uses: ./.github/actions/build-docs + with: + subdir: ${{ steps.version.outputs.version }} - uses: ./.github/actions/deploy-to-gh-pages with: diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index fb743cd..87a14d1 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -20,11 +20,9 @@ jobs: - uses: astral-sh/setup-uv@v7 - - name: Build docs - run: | - uv run --group docs python .github/scripts/override_site_url.py dev - uv run --group docs zensical build --clean --config-file zensical.local.toml - cp -r site /tmp/built-site + - uses: ./.github/actions/build-docs + with: + subdir: dev - uses: ./.github/actions/deploy-to-gh-pages with: From 02860329ebf44baa49160cf640a6c482f5f22d67 Mon Sep 17 00:00:00 2001 From: Tai Sakuma Date: Sat, 21 Mar 2026 14:58:20 -0400 Subject: [PATCH 3/5] refactor: modify zensical.toml in place instead of creating a copy Co-Authored-By: Claude Opus 4.6 (1M context) --- .github/actions/build-docs/action.yml | 2 +- .github/scripts/override_site_url.py | 7 +++---- .github/workflows/docs-pr-preview.yml | 2 +- 3 files changed, 5 insertions(+), 6 deletions(-) diff --git a/.github/actions/build-docs/action.yml b/.github/actions/build-docs/action.yml index 0e1bf9a..d6243a8 100644 --- a/.github/actions/build-docs/action.yml +++ b/.github/actions/build-docs/action.yml @@ -12,5 +12,5 @@ runs: - shell: bash run: | uv run --group docs python .github/scripts/override_site_url.py "${{ inputs.subdir }}" - uv run --group docs zensical build --clean --config-file zensical.local.toml + uv run --group docs zensical build --clean cp -r site /tmp/built-site diff --git a/.github/scripts/override_site_url.py b/.github/scripts/override_site_url.py index fb29fa3..03d426d 100644 --- a/.github/scripts/override_site_url.py +++ b/.github/scripts/override_site_url.py @@ -3,18 +3,17 @@ from pathlib import Path import tomlkit -INPUT_PATH = Path('zensical.toml') -OUTPUT_PATH = Path('zensical.local.toml') +CONFIG_PATH = Path('zensical.toml') def main(): - config = tomlkit.loads(INPUT_PATH.read_text()) + config = tomlkit.loads(CONFIG_PATH.read_text()) url = config.get('project', {}).get('site_url') if url: subdir = sys.argv[1] new_url = url.rstrip('/') + '/' + subdir.strip('/') + '/' config['project']['site_url'] = new_url - OUTPUT_PATH.write_text(tomlkit.dumps(config)) + CONFIG_PATH.write_text(tomlkit.dumps(config)) main() diff --git a/.github/workflows/docs-pr-preview.yml b/.github/workflows/docs-pr-preview.yml index 241eff4..642f6e1 100644 --- a/.github/workflows/docs-pr-preview.yml +++ b/.github/workflows/docs-pr-preview.yml @@ -27,7 +27,7 @@ jobs: - name: Get preview URL id: preview run: | - url=$(uv run --group docs python -c "import tomlkit; print(tomlkit.loads(open('zensical.local.toml').read()).get('project', {}).get('site_url', ''))") + url=$(uv run --group docs python -c "import tomlkit; print(tomlkit.loads(open('zensical.toml').read()).get('project', {}).get('site_url', ''))") echo "url=${url}" >> "$GITHUB_OUTPUT" - uses: ./.github/actions/deploy-to-gh-pages From d689f37084a9613b8b2eb57f040b13c6acdce2ac Mon Sep 17 00:00:00 2001 From: Tai Sakuma Date: Sat, 21 Mar 2026 15:15:00 -0400 Subject: [PATCH 4/5] refactor: output deploy URL from deploy action The deploy action now outputs the default GitHub Pages URL, eliminating the separate "Get preview URL" step. Co-Authored-By: Claude Opus 4.6 (1M context) --- .github/actions/deploy-to-gh-pages/action.yml | 9 ++++++++- .github/workflows/docs-pr-preview.yml | 10 ++-------- 2 files changed, 10 insertions(+), 9 deletions(-) diff --git a/.github/actions/deploy-to-gh-pages/action.yml b/.github/actions/deploy-to-gh-pages/action.yml index b59bc99..2c12f58 100644 --- a/.github/actions/deploy-to-gh-pages/action.yml +++ b/.github/actions/deploy-to-gh-pages/action.yml @@ -9,10 +9,16 @@ inputs: description: Commit message required: true +outputs: + url: + description: Default GitHub Pages URL for the deployed subdirectory + value: ${{ steps.deploy.outputs.url }} + runs: using: composite steps: - - shell: bash + - id: deploy + shell: bash run: | git config user.name "github-actions[bot]" git config user.email "github-actions[bot]@users.noreply.github.com" @@ -32,3 +38,4 @@ runs: git add .nojekyll "$TARGET" git diff --cached --quiet || git commit -m "${{ inputs.commit-message }}" git push origin gh-pages + echo "url=https://${{ github.repository_owner }}.github.io/${{ github.event.repository.name }}/${TARGET}/" >> "$GITHUB_OUTPUT" diff --git a/.github/workflows/docs-pr-preview.yml b/.github/workflows/docs-pr-preview.yml index 642f6e1..e3e6535 100644 --- a/.github/workflows/docs-pr-preview.yml +++ b/.github/workflows/docs-pr-preview.yml @@ -24,24 +24,18 @@ jobs: with: subdir: pr/${{ github.event.number }} - - name: Get preview URL - id: preview - run: | - url=$(uv run --group docs python -c "import tomlkit; print(tomlkit.loads(open('zensical.toml').read()).get('project', {}).get('site_url', ''))") - echo "url=${url}" >> "$GITHUB_OUTPUT" - - uses: ./.github/actions/deploy-to-gh-pages + id: deploy with: target: pr/${{ github.event.number }} commit-message: "Deploy PR #${{ github.event.number }} preview" - name: Post or update PR comment - if: steps.preview.outputs.url != '' uses: actions/github-script@v7 with: script: | const marker = ''; - const url = '${{ steps.preview.outputs.url }}'; + const url = '${{ steps.deploy.outputs.url }}'; const body = `${marker}\nšŸ“– Docs preview: ${url}`; const { data: comments } = await github.rest.issues.listComments({ owner: context.repo.owner, From 65964eb811b66a7055873d918de5e7cc8c664200 Mon Sep 17 00:00:00 2001 From: Tai Sakuma Date: Sat, 21 Mar 2026 15:17:29 -0400 Subject: [PATCH 5/5] fix: restore zensical.toml after build to allow branch switch The in-place modification of zensical.toml blocks the subsequent git checkout to gh-pages. Restore it after building since the built site is already copied to /tmp. Co-Authored-By: Claude Opus 4.6 (1M context) --- .github/actions/build-docs/action.yml | 1 + 1 file changed, 1 insertion(+) diff --git a/.github/actions/build-docs/action.yml b/.github/actions/build-docs/action.yml index d6243a8..f3c17ef 100644 --- a/.github/actions/build-docs/action.yml +++ b/.github/actions/build-docs/action.yml @@ -14,3 +14,4 @@ runs: uv run --group docs python .github/scripts/override_site_url.py "${{ inputs.subdir }}" uv run --group docs zensical build --clean cp -r site /tmp/built-site + git checkout -- zensical.toml