@inditextech/docouture-cli 0.1.0-SNAPSHOT.40.1

package/build/templates/workflows/docouture-publish.yml

@@ -0,0 +1,138 @@
+name: docouture-publish
+
+# Builds this site, then publishes it with `docouture publish <target>` — see
+# that command's own usage (`docouture --help`) and
+# @inditextech/docouture-cli's publish.ts for the mechanism: `<target>` resolves
+# by convention to the npm package `@inditextech/docouture-publish-<target>`
+# (e.g. `gh-pages` → `@inditextech/docouture-publish-gh-pages`), which this site
+# must add to its own devDependencies to opt in, alongside a
+# `"docouture": { "publish": { "<target>": { ... } } }` block in this site's own
+# package.json for that driver's options. There is no publish-target Antora
+# extension and no `antora.extensions` involvement at all — publishing is a
+# CLI concern, decoupled from `antora build`, which is why Build and Publish
+# are two separate steps below: re-publishing an already-built site never
+# needs a rebuild.
+#
+# Replace `gh-pages` in the Publish step with whatever target this site's
+# own devDependencies declare a driver for, or drop the step entirely for a
+# site that only wants a build artifact for now — this file makes no
+# platform assumption.
+#
+# `permissions: contents: write` and `GITHUB_TOKEN` below are only ever used
+# by @inditextech/docouture-publish-gh-pages specifically (pushing to a
+# `gh-pages` branch needs both); harmless to leave granted for any other
+# driver, which simply never reads them.
+#
+# Not triggered by push — docouture-release.yml calls this workflow directly
+# (as a reusable job, via `uses:` + `needs:`) as its last step, once a
+# release has actually been cut, so ordering is a real dependency rather
+# than a coincidence of two workflows independently reacting to the same
+# git push. `workflow_call` is what makes that direct call possible.
+# `workflow_dispatch` is kept alongside it for a manual rebuild+republish
+# of whatever is currently on `main`, without cutting a new release.
+on:
+  workflow_call: {}
+  workflow_dispatch: {}
+
+concurrency:
+  group: docouture-publish
+  cancel-in-progress: false
+
+jobs:
+  publish:
+    name: Build and publish
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    # Needed only by @inditextech/docouture-publish-gh-pages, if this site uses
+    # it — pushing to a `gh-pages` branch needs write access to repository
+    # contents. Harmless to leave granted for any other publish target.
+    permissions:
+      contents: write
+    # `docouture new` scaffolds this site's package.json, antora-playbook.yml
+    # etc. under docs/ (not the repository root) — see the docs-site-package
+    # skill's reference/versioning-modes.md. Every step below runs from
+    # there; only .github/workflows itself has to live at the true repo
+    # root, since that is the one path GitHub Actions requires.
+    defaults:
+      run:
+        working-directory: docs
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          # Antora aggregates every ref content.sources[] matches into one
+          # build, not just whichever ref triggered this run — a shallow,
+          # single-branch checkout would leave the others unreachable.
+          fetch-depth: 0
+
+      # __DOCOUTURE_PM_SETUP_STEP__
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          # Reads engines.node from docs/package.json — no separate version
+          # file to keep in sync.
+          node-version-file: docs/package.json
+          cache: __DOCOUTURE_PM_CACHE__
+          # `defaults.run.working-directory: docs` above only applies to
+          # `run:` steps, not to this action's own inputs — without this,
+          # setup-node looks for a lockfile from the repo root and fails.
+          cache-dependency-path: docs/__DOCOUTURE_LOCKFILE__
+
+      - name: Install dependencies
+        run: __DOCOUTURE_INSTALL_CI__
+
+      # See docouture-pr-verify.yml's own comment: this build reads the real
+      # antora-playbook.yml (Build below), unlike pr-verify/release which
+      # build antora-playbook.local.yml — so the enabled check looks at the
+      # same file this job actually builds.
+      - name: Kroki / Detect enabled
+        id: kroki-check
+        run: |
+          if grep -qE "^\s*kroki-enabled:\s*['\"]?true['\"]?\s*(#.*)?$" antora-playbook.yml; then
+            echo "enabled=true" >> "$GITHUB_OUTPUT"
+          else
+            echo "enabled=false" >> "$GITHUB_OUTPUT"
+          fi
+
+      # See docouture-pr-verify.yml's own comment: primes the runner's Docker
+      # image store before Build's implicit Kroki startup, so a fresh runner
+      # doesn't pull all 4 images from scratch on every publish.
+      - name: Kroki / Docker image cache
+        id: kroki-cache
+        if: steps.kroki-check.outputs.enabled == 'true'
+        uses: actions/cache@v4
+        with:
+          path: /tmp/kroki-images.tar
+          key: ${{ runner.os }}-kroki-images-${{ hashFiles('**/kroki-compose.yml') }}
+
+      - name: Kroki / Load cached images
+        if: steps.kroki-check.outputs.enabled == 'true' && steps.kroki-cache.outputs.cache-hit == 'true'
+        run: docker load -i /tmp/kroki-images.tar
+
+      - name: Kroki / Pull and save images
+        if: steps.kroki-check.outputs.enabled == 'true' && steps.kroki-cache.outputs.cache-hit != 'true'
+        run: |
+          compose_file="$(find . -name kroki-compose.yml 2>/dev/null | head -1)"
+          docker compose -f "$compose_file" pull
+          docker save -o /tmp/kroki-images.tar $(docker compose -f "$compose_file" config --images)
+
+      - name: Build
+        run: __DOCOUTURE_PM__ run build
+
+      # See docouture-pr-verify.yml's own comment: Antora's strict mode already
+      # catches broken cross-references during Build above; check-links
+      # (package.json's own script, see scripts/check-links.mjs) covers what
+      # it can't — raw http(s) links in content — before this site actually
+      # gets published. Only a broken EXTERNAL link fails this step; a
+      # broken local one is a warning only.
+      - name: Check links
+        run: __DOCOUTURE_PM__ run check-links
+
+      # `GITHUB_TOKEN` is read by @inditextech/docouture-publish-gh-pages
+      # specifically (unused, and unnecessary to set, for any other publish
+      # target). See this file's own header comment for the `<target>`
+      # naming convention and where its options come from.
+      - name: Publish
+        run: npx docouture publish gh-pages
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

package/build/templates/workflows/docouture-release-preview.yml

@@ -0,0 +1,198 @@
+name: docouture-release-preview
+
+# Comments on a pull request labeled `docs/release`, previewing what
+# docouture-release.yml (this workflow's sibling) will do when the PR merges —
+# same 3-job shape as this monorepo's own .github/workflows/code-release_preview.yml
+# (check-changes-in-paths / release-preview / release-preview-no-*-changes /
+# release-preview-no-release-label), adapted to docs-release's own signal
+# (the `docs/release` label + versioning-mode detection) instead of
+# code-release's (`release-type/*` labels + a CHANGELOG.md diff).
+#
+# Read-only: this workflow never touches git, tags, or docs/antora.yml — it
+# only reports what docouture-release.yml would do, so a reviewer can catch a
+# missing docs/.release-version (versioned mode) or an about-to-be-overwritten
+# tag before merging, not after.
+#
+# Reuses docouture-release.yml's own "Detect mode" (grep antora-playbook.yml's
+# content.sources[] tags) and "Resolve version" (stable, or
+# docs/.release-version's contents) logic verbatim — see that workflow's own
+# comments, and the docs-site-package skill's reference/versioning-modes.md,
+# for the full mechanism.
+on:
+  pull_request:
+    types: [labeled, synchronize, ready_for_review, opened]
+    branches: ['main*']
+
+concurrency:
+  group: release-preview
+  cancel-in-progress: true
+
+jobs:
+  check-changes-in-paths:
+    name: Check for changes in corresponding paths
+    runs-on: ubuntu-latest
+    if: ${{ github.event.pull_request.draft == false || contains(github.event.pull_request.labels.*.name, 'docs/release') }}
+    outputs:
+      detected: ${{ steps.changes.outputs.paths }}
+    steps:
+      - name: Check for changed files in specific paths
+        id: changes
+        uses: dorny/paths-filter@ebc4d7e9ebcb0b1eb21480bb8f43113e996ac77a # v3
+        with:
+          filters: |
+            paths:
+              - 'docs/**'
+              - '.github/workflows/docouture-release*.yml'
+
+  release-preview:
+    name: Release Preview
+    needs: check-changes-in-paths
+    if: ${{ contains(github.event.pull_request.labels.*.name, 'docs/release') && needs.check-changes-in-paths.outputs.detected == 'true' }}
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      pull-requests: write
+    # `docouture new` scaffolds this site's antora-playbook.yml, docs/antora.yml
+    # etc. under docs/ (not the repository root) — same layout
+    # docouture-release.yml itself runs against. Every step below runs from
+    # there; only .github/workflows itself has to live at the true repo
+    # root.
+    defaults:
+      run:
+        working-directory: docs
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      # Same signal docouture-release.yml's own "Detect mode" step reads:
+      # antora-playbook.yml's content.sources[] tags, not docs/antora.yml
+      # (identical on main for both modes, so it carries no mode signal).
+      - name: Detect mode
+        id: detect
+        run: |
+          line=$(grep -E "tags:" antora-playbook.yml | head -1)
+
+          case "$line" in
+            *"v*"*) mode=versioned ;;
+            *stable*) mode=standalone ;;
+            *)
+              echo "::error::antora-playbook.yml's content.sources[] has tags: '${line}' — expected something matching 'v*' (versioned) or 'stable' (standalone)."
+              exit 1
+              ;;
+          esac
+
+          echo "mode=${mode}" >> "$GITHUB_OUTPUT"
+          echo "Detected ${mode} (antora-playbook.yml: ${line})"
+
+      # Standalone always targets 'stable'; versioned reads the plain-text
+      # docs/.release-version this PR is expected to have committed — same
+      # source docouture-release.yml's pull_request trigger reads (there is no
+      # workflow_dispatch input to fall back to here, since this workflow
+      # only ever runs on pull_request).
+      - name: Resolve version
+        id: resolve
+        env:
+          MODE: ${{ steps.detect.outputs.mode }}
+        run: |
+          if [ "$MODE" = "versioned" ]; then
+            if [ -f .release-version ]; then
+              version=$(tr -d '[:space:]' < .release-version)
+            else
+              version=""
+            fi
+            tag="v${version}"
+          else
+            version="stable"
+            tag="stable"
+          fi
+
+          echo "version=${version}" >> "$GITHUB_OUTPUT"
+          echo "tag=${tag}" >> "$GITHUB_OUTPUT"
+
+      # Query the remote directly — no local tag fetch needed. A hit here
+      # means docouture-release.yml's "Push release tag" step will force-move an
+      # existing tag (a republish) rather than create a new one.
+      - name: Check for existing tag
+        id: check
+        env:
+          MODE: ${{ steps.detect.outputs.mode }}
+          TAG: ${{ steps.resolve.outputs.tag }}
+        run: |
+          if [ "$MODE" = "versioned" ] && [ -z "${{ steps.resolve.outputs.version }}" ]; then
+            echo "existed=unknown" >> "$GITHUB_OUTPUT"
+            exit 0
+          fi
+
+          if git ls-remote --exit-code --tags origin "refs/tags/${TAG}" >/dev/null 2>&1; then
+            echo "existed=true" >> "$GITHUB_OUTPUT"
+          else
+            echo "existed=false" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Comment on PR
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          MODE: ${{ steps.detect.outputs.mode }}
+          VERSION: ${{ steps.resolve.outputs.version }}
+          TAG: ${{ steps.resolve.outputs.tag }}
+          EXISTED: ${{ steps.check.outputs.existed }}
+        run: |
+          if [ "$MODE" = "versioned" ] && [ -z "$VERSION" ]; then
+            gh pr comment ${{ github.event.number }} --body "
+          ### :x: docs/release: no target version
+          This site is on Versioned (Full History) mode, but no \`docs/.release-version\` file was found in this PR — add one with the target version (e.g. \`1.2.0\`) before merging with the \`docs/release\` label, or the release workflow will fail on merge."
+            exit 0
+          fi
+
+          MESSAGE="
+          ### :rocket: Docs Release Preview
+          Merging this Pull Request will release **\`${TAG}\`**."
+
+          if [ "$EXISTED" = "true" ]; then
+            MESSAGE="${MESSAGE}
+
+          ### :warning: Tag already exists
+          \`${TAG}\` already exists and will be **force-overwritten** on merge."
+          fi
+
+          gh pr comment ${{ github.event.number }} --body "$(echo -e "$MESSAGE")"
+
+  release-preview-no-docs-changes:
+    name: Add PR comment with configuration management information
+    needs: check-changes-in-paths
+    if: ${{ contains(github.event.pull_request.labels.*.name, 'docs/release') && needs.check-changes-in-paths.outputs.detected == 'false' }}
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      pull-requests: write
+    env:
+      GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Add PR comment with release preview
+        run: |
+          gh pr comment ${{ github.event.number }} --body "
+          ### :exclamation: This Pull Request will not trigger a meaningful release
+          The \`docs/release\` label is set, but this Pull Request has no changes under \`docs/**\` — merging it will still cut a release, just with nothing new in it."
+
+  release-preview-no-release-label:
+    name: Add PR comment with release information
+    needs: check-changes-in-paths
+    if: ${{ !contains(github.event.pull_request.labels.*.name, 'docs/release') && needs.check-changes-in-paths.outputs.detected == 'true' && github.event.pull_request.draft == false }}
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      pull-requests: write
+    env:
+      GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Add PR comment with release preview
+        run: |
+          gh pr comment ${{ github.event.number }} --body "
+          ### :exclamation: This Pull Request will not trigger a release
+          A Pull Request with no \`docs/release\` label will not trigger a release — label it \`docs/release\` if you want this merge to release the docs site."