ci(docs): docs workflow with Nx affected gating and iconized steps

[kattsushi]

• Add docs.yml workflow for GitHub Pages\n- Gate build via nx affected with project filter @effectify/docs\n- English messages and iconized step names consistent with CI/CD\n- Remove legacy docs-pages.yml\n\nThis PR standardizes docs deployment and aligns workflow style.

Summary by CodeRabbit

• Chores
  • Added an automated workflow to build and deploy project documentation to GitHub Pages on pushes to the main branch. The pipeline installs dependencies with caching, runs targeted documentation builds, uploads artifacts, deploys when docs have changed, and skips deployment with a clear message when documentation is unaffected.

[coderabbitai]

📝 Walkthrough

Walkthrough

Adds a new GitHub Actions workflow .github/workflows/docs.yml that builds documentation with pnpm and nx on pushes to master and conditionally deploys apps/docs/dist to GitHub Pages when docs are affected.

Changes

Cohort / File(s)	Summary
Documentation Deployment Workflow .github/workflows/docs.yml	Adds a new GitHub Actions workflow "📚 Docs": checks out full history, sets up Node.js and pnpm with caching, installs deps, runs nx affected --target=build --projects=@effectify/docs (derives BASE from previous commit), determines should_deploy by checking apps/docs/dist, uploads artifact and configures/deploys to GitHub Pages when docs are affected; otherwise skips deployment.

Sequence Diagram(s)

sequenceDiagram
  participant Push as Developer Push
  participant GH as GitHub Actions
  participant Repo as Repository
  participant Node as Node/pnpm Setup
  participant NX as nx Build
  participant Art as Artifact Upload
  participant Pages as GitHub Pages

  Push->>GH: push to master
  GH->>Repo: checkout (full history)
  GH->>Node: install Node + pnpm (with cache)
  GH->>Repo: pnpm install
  GH->>NX: run `nx affected --target=build --projects=@effectify/docs` (BASE from previous commit)
  NX-->>GH: build output (`apps/docs/dist`) or nothing
  alt docs produced
    GH->>Art: upload `apps/docs/dist`
    GH->>Pages: configure & deploy artifact
  else no docs affected
    GH-->>Push: skip deployment (message)
  end

Loading

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~12 minutes

Poem

🐰 A tiny workflow hops into place,
Fetches, builds, then checks the docs' case.
If dist appears, it sails to Pages high,
If not, it nods and passes by.
Pipelines hum — a rabbit's quiet sigh. 🥕

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and specifically describes the main change: adding a docs workflow with Nx affected gating and iconized steps, which directly aligns with the PR's primary objective of adding a new GitHub Actions workflow for documentation deployment.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch chore/docs-workflow-icons

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[nx-cloud]

View your CI Pipeline Execution ↗ for commit a24ce9e

Command	Status	Duration	Result
nx affected --target=test --base=87c40a1ce45893...	✅ Succeeded	10s	View ↗
nx affected --target=build --base=87c40a1ce4589...	✅ Succeeded	3s	View ↗
nx affected --target=typecheck --base=origin/ma...	✅ Succeeded	<1s	View ↗
nx affected --target=lint --base=origin/master ...	✅ Succeeded	<1s	View ↗

---

☁️ Nx Cloud last updated this comment at 2026-02-07 15:15:56 UTC

[coderabbitai]

Actionable comments posted: 2

🤖 Fix all issues with AI agents

In @.github/workflows/docs.yml:
- Around line 75-77: The YAML parser misinterprets the colon in the run string
for the step named "⏭️ Skip deploy (docs not affected)"; replace the single-line
run value with a block scalar to avoid ambiguity (use run: | and put the echo
command on the next line), e.g. convert the current run: echo "Skipping deploy:
`@effectify/docs` is not affected in this push." into a block scalar that contains
the echo command so the colon is treated as part of the string rather than a
mapping separator.
- Around line 43-58: The step currently swallows real build failures via the
trailing "|| true" on the pnpm nx command; remove the "|| true", run the pnpm nx
affected -t build --base="${BASE}" --head="${HEAD}" --projects="@effectify/docs"
command and immediately capture its exit code (e.g., rc=$?), then: if rc is
non-zero, echo "should_deploy=false" to GITHUB_OUTPUT and exit with that rc so
the job fails on real build errors; otherwise (rc == 0) check for the
apps/docs/dist directory and set should_deploy=true/false accordingly. Reference
the affected_build job id and the pnpm nx affected invocation plus the
apps/docs/dist existence check to locate where to apply this change.

[coderabbitai]

Actionable comments posted: 2

🤖 Fix all issues with AI agents

In @.github/workflows/docs.yml:
- Around line 52-57: The echo and pnpm commands are using backticks around the
project identifier `@effectify/docs`, causing shell command substitution and
failing; replace those backticks with single or double quotes so the literal
string `@effectify/docs` is used. Update the two occurrences inside the if/else
block (the echo message "pnpm nx build `@effectify/docs`" and the echo "Running
nx affected build for `@effectify/docs`...") and the pnpm nx build invocation to
use quoted "@effectify/docs" (or '@effectify/docs') instead of backticks.
- Around line 80-83: The echo line inside the "⏭️ Skip deploy (docs not
affected)" step uses backticks around `@effectify/docs` which triggers shell
command substitution; change the echo to use safe quoting (e.g., single quotes)
or escape the backticks so the literal string `@effectify/docs` is printed when
the condition on steps.affected_build.outputs.should_deploy is not 'true'.