docs: overhaul npm README + auto-sync pinned CDN version (#721)

Author: FelixTJDietrich

.github/workflows/pr-health-checks.yml

@@ -51,6 +51,25 @@ jobs:
               - 'pnpm-workspace.yaml'
               - '.github/workflows/pr-health-checks.yml'
 
+  # No path filter: a stale CDN version can drift in via a doc edit OR a bump,
+  # so check every PR. Pure Node — no pnpm install needed.
+  version-sync-check:
+    needs: [detect-changes]
+    if: needs.detect-changes.outputs.should-skip != 'true'
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
+
+      - name: Set up Node
+        uses: actions/setup-node@53b83947a5a98c8d113130e565377fae1a50d02f # v6
+        with:
+          node-version-file: ".nvmrc"
+
+      - name: Check README + docs version sync
+        run: node scripts/sync-library-version.mjs --check
+
   lint-and-format-check:
     needs: [detect-changes]
     if: needs.detect-changes.outputs.should-skip != 'true' && needs.detect-changes.outputs.code == 'true'
@@ -270,6 +289,7 @@ jobs:
     needs:
       [
         detect-changes,
+        version-sync-check,
         lint-and-format-check,
         library-node22-compat,
         e2e-tests,

.github/workflows/version-bump.yml

@@ -172,6 +172,10 @@ jobs:
           echo "standalone_version=${STANDALONE_VERSION}" >> "$GITHUB_OUTPUT"
           echo "vscode_version=${VSCODE_VERSION}" >> "$GITHUB_OUTPUT"
 
+      - name: Sync pinned library version in README + docs
+        # No-op for the standalone/vscode scopes — library version unchanged.
+        run: node scripts/sync-library-version.mjs
+
       - name: Regenerate pnpm-lock.yaml
         run: pnpm install --lockfile-only --ignore-scripts
 
@@ -190,7 +194,7 @@ jobs:
             library)
               BRANCH="chore/library-v${LIB_VERSION}"
               COMMIT_TITLE="chore: release @tumaet/apollon@${LIB_VERSION} + standalone v${STANDALONE_VERSION}"
-              FILES=(library/package.json standalone/webapp/package.json standalone/server/package.json pnpm-lock.yaml)
+              FILES=(library/package.json standalone/webapp/package.json standalone/server/package.json pnpm-lock.yaml library/README.md docs/library/embedding/vanilla.md docs/src/pages/index.tsx)
               ;;
             standalone)
               BRANCH="chore/standalone-v${STANDALONE_VERSION}"

README.md

@@ -3,14 +3,14 @@
 [![npm version](https://img.shields.io/npm/v/@tumaet/apollon)](https://www.npmjs.com/package/@tumaet/apollon)
 [![npm license](https://img.shields.io/npm/l/@tumaet/apollon)](./LICENSE)
 
-Apollon is an open-source UML modeling editor for the web. Draw 13 UML and modeling diagram types — including class, component, activity, BPMN, and SFC — in the browser, collaborate in real time, and export to SVG, PNG, PDF, or JSON.
+Apollon is an open-source UML modeling editor for the web. Draw 13 UML and modeling diagram types (class, component, activity, BPMN, SFC, and more) in the browser, collaborate in real time, and export to SVG, PNG, PDF, or JSON.
 
 This monorepo contains every piece of the Apollon platform:
 
-- **[`library/`](./library)** — the embeddable `@tumaet/apollon` React component ([npm](https://www.npmjs.com/package/@tumaet/apollon)).
-- **[`standalone/`](./standalone)** — standalone web app (server + webapp) built on the library.
-- **[`vscode-extension/`](./vscode-extension)** — the Apollon VS Code extension.
-- **[`docs/`](./docs)** — Docusaurus documentation site, published at <https://ls1intum.github.io/Apollon/>.
+- **[`library/`](./library)**: the embeddable `@tumaet/apollon` editor ([npm](https://www.npmjs.com/package/@tumaet/apollon)).
+- **[`standalone/`](./standalone)**: the standalone web app (server and webapp) built on the library.
+- **[`vscode-extension/`](./vscode-extension)**: the Apollon VS Code extension.
+- **[`docs/`](./docs)**: the Docusaurus documentation site, published at <https://ls1intum.github.io/Apollon/>.
 
 ## Use the library
 
@@ -36,15 +36,15 @@ pnpm dev
 - Server (`tsx watch`) on a printed local HTTP port with a matching WebSocket relay port.
 - Webapp (Vite HMR) on a printed local dev URL.
 
-The launcher handles the boring parts:
+The launcher handles the setup:
 
 - Resolves port collisions for the webapp, server, WebSocket relay, and Redis.
-- Reuses an existing local Redis if one is running; otherwise starts a Redis container on a free host port (Docker required only in that case).
-- Needs no `.env` files — defaults match the local setup.
+- Reuses an existing local Redis if one is running; otherwise it starts a Redis container on a free host port (Docker is only required in that case).
+- Needs no `.env` files. The defaults match the local setup.
 
 Override ports via `APOLLON_WEBAPP_PORT`, `APOLLON_SERVER_PORT`, `APOLLON_WS_PORT`, or `APOLLON_REDIS_PORT`.
 
-To preview the documentation site instead, run `pnpm dev:docs` from the repo root — it builds the library and starts the Docusaurus dev server.
+To preview the documentation site instead, run `pnpm dev:docs` from the repo root. It builds the library and starts the Docusaurus dev server.
 
 ## Tech stack
 
@@ -58,24 +58,24 @@ To preview the documentation site instead, run `pnpm dev:docs` from the repo roo
 
 ## Requirements
 
-- **Node.js** — version pinned in [`.nvmrc`](./.nvmrc) (Node 24 LTS).
-- **pnpm 11+** — the package manager. The exact version is pinned in `package.json` (`packageManager` field). Install with `npm install -g pnpm@11`.
-- **Docker** — only when `pnpm dev` needs to start a local Redis.
+- **Node.js**: version pinned in [`.nvmrc`](./.nvmrc) (Node 24 LTS).
+- **pnpm 11+**: the package manager. The exact version is pinned in the `packageManager` field of `package.json`. Install it with `npm install -g pnpm@11`.
+- **Docker**: only when `pnpm dev` needs to start a local Redis.
 
 ## Documentation
 
-The docs are a [Docusaurus](https://docusaurus.io/) site published at <https://ls1intum.github.io/Apollon/>. Sources live in [`docs/`](./docs); preview locally with `pnpm dev:docs`.
+The docs are a [Docusaurus](https://docusaurus.io/) site published at <https://ls1intum.github.io/Apollon/>. Sources live in [`docs/`](./docs); preview them locally with `pnpm dev:docs`.
 
-- [Library](https://ls1intum.github.io/Apollon/library/) — embedding the `@tumaet/apollon` React component.
-- [User Guide](https://ls1intum.github.io/Apollon/user/) — getting started, requirements, and self-hosting.
-- [Contributor](https://ls1intum.github.io/Apollon/contributor/) — project structure, scripts, deployment, and troubleshooting.
+- [Library](https://ls1intum.github.io/Apollon/library/): embedding the `@tumaet/apollon` editor.
+- [User Guide](https://ls1intum.github.io/Apollon/user/): getting started, requirements, and self-hosting.
+- [Contributor](https://ls1intum.github.io/Apollon/contributor/): project structure, scripts, deployment, and troubleshooting.
 
-Operations, legal-pages, and TUM DSMS material lives in [`ops/`](./ops) in this repo.
+Operations, legal pages, and TUM DSMS material live in [`ops/`](./ops) in this repo.
 
 ## Contributing
 
 Open an issue or a pull request at <https://github.com/ls1intum/Apollon>. Guidelines live in [`CONTRIBUTING.md`](./CONTRIBUTING.md); see also the [`CODE_OF_CONDUCT.md`](./CODE_OF_CONDUCT.md).
 
 ## License
 
-MIT — see [LICENSE](./LICENSE).
+MIT. See [LICENSE](./LICENSE).

docs/contributor/deployment/npm-publishing.md

@@ -18,6 +18,8 @@ Standalone starts at `4.2.18` (the library version at the time of the release-pi
 
 All three workflows trigger automatically when their version changes on `main`. There is **one** manual step per release: merge the bump PR.
 
+The `library` bump also rewrites the pinned `@tumaet/apollon@X.Y.Z` CDN URLs in the README and docs (via `scripts/sync-library-version.mjs`) so the published examples never lag the package version. PR Health Checks run the same script with `--check`, so a drift can never merge — run `pnpm sync:version` locally to fix one.
+
 ## Cut a release
 
 1. Actions → **Version Bump** → pick `scope` and bump type. Merge the PR that opens.

docs/library/embedding/vanilla.md

@@ -42,7 +42,7 @@ can shift between releases. [jsDelivr's `esm.run`](https://www.jsdelivr.com/esm)
 is an equivalent substitute.
 
 :::warning Pin the CDN version
-Both URLs above pin an exact version (`@4.4.0`). An **unpinned** URL —
+Both URLs above pin an exact version. An **unpinned** URL —
 `@tumaet/apollon` with no version — always resolves to the latest release, so
 a new major can land on the next page refresh and break your embed without
 any change on your side. Always pin to a known-good version and bump it