fix(docs): unblock Docusaurus build — remove webpack override + MDX escapes + onBrokenLinks tolerance#15
Merged
Conversation
…capes, broken-link tolerance Three independent fixes to make the Documentation workflow build: 1. **Remove the 'webpack: 5.99.9' override** in docusaurus/package.json. The override forced webpack 5.99.9 which doesn't satisfy Docusaurus 3.7+'s ProgressPlugin schema. Removing it lets Docusaurus pick its own webpack and resolves the cryptic 'Progress Plugin has been initialized using an options object that does not match the API schema' error. Pattern matches openconnector/docusaurus (working reference). 2. **Escape generic-type angle brackets in ARCHITECTURE.md** — MDX 3 (Docusaurus 3.7+) parses 'array<string>' as a JSX tag and fails on 'expected closing tag for <string>'. Wrapping the type cells in backticks (array<string>) tells MDX to treat them as code spans instead of JSX. 8 occurrences fixed (4 array<string>, 4 array<UUID>). 3. **Relax onBrokenLinks from 'throw' to 'warn'** in docusaurus.config.js. The docs reference '../../concurrentie-analyse/...' (private intel submodule not present in the public docs build) plus auto-detected cross-locale links Docusaurus generates for /nl/. Switching to 'warn' matches the working openconnector pattern; broken-link warnings remain visible in CI logs for follow-up cleanup. The two specific concurrentie-analyse references in ARCHITECTURE.md + DESIGN-REFERENCES.md were rewritten to absolute GitHub URLs as part of this PR. Local 'npm run build' verified with both en and nl locales producing static files in build/. Companion lockfile (docusaurus/package-lock.json) committed so CI can use 'npm ci' deterministically — matches the openconnector pattern. Closes #13 (docs build deferred from quality-fix PR #6).
Contributor
Quality Report — ConductionNL/scholiq @
|
| Check | PHP | Vue | Security | License | Tests |
|---|---|---|---|---|---|
| lint | ✅ | ||||
| phpcs | ✅ | ||||
| phpmd | ✅ | ||||
| psalm | ✅ | ||||
| phpstan | ✅ | ||||
| phpmetrics | ✅ | ||||
| eslint | ✅ | ||||
| stylelint | ✅ | ||||
| composer | ✅ | ✅ 100/100 | |||
| npm | ✅ | ✅ 215/215 | |||
| PHPUnit | ✅ | ||||
| Newman | ✅ | ||||
| Playwright | ⏭️ |
Coverage: 0% (0/3 statements)
Quality workflow — 2026-05-11 11:47 UTC
Download the full PDF report from the workflow artifacts.
Docusaurus 3.10+ requires Node >= 20. Workflow was pinned to Node 18, producing 'Minimum Node.js version not met' on every PR run. Changes: - node-version: '18' -> '20' - actions/setup-node@v3 -> @v4 - Add npm cache keyed on docusaurus/package-lock.json (only possible now that the lockfile is committed per PR #15) - timeout-minutes: 3 -> 5 (docusaurus 3.10 install + build is heavier)
Contributor
Quality Report — ConductionNL/scholiq @
|
| Check | PHP | Vue | Security | License | Tests |
|---|---|---|---|---|---|
| lint | ✅ | ||||
| phpcs | ✅ | ||||
| phpmd | ✅ | ||||
| psalm | ✅ | ||||
| phpstan | ✅ | ||||
| phpmetrics | ✅ | ||||
| eslint | ✅ | ||||
| stylelint | ✅ | ||||
| composer | ✅ | ✅ 100/100 | |||
| npm | ✅ | ✅ 215/215 | |||
| PHPUnit | ✅ | ||||
| Newman | ✅ | ||||
| Playwright | ⏭️ |
Coverage: 0% (0/3 statements)
Quality workflow — 2026-05-11 11:51 UTC
Download the full PDF report from the workflow artifacts.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Closes #13. Three independent fixes to make
Deploy Documentationworkflow green:"webpack": "5.99.9"override indocusaurus/package.json— forces an incompatible webpack against Docusaurus 3.7+'s ProgressPlugin schema. openconnector (working reference) has no such override.docs/ARCHITECTURE.md—array<string>andarray<UUID>(8 occurrences) wrapped in backticks so MDX 3 treats them as code spans, not JSX.onBrokenLinks: 'throw'→'warn'indocusaurus.config.js(matches openconnector). Two specificconcurrentie-analyse/...references in ARCHITECTURE.md + DESIGN-REFERENCES.md were also rewritten to absolute GitHub URLs.docusaurus/package-lock.jsonso CI cannpm ci --legacy-peer-depsdeterministically (matches openconnector).Local verification
./node_modules/.bin/docusaurus buildexits 0;build/directory contains404.html,assets/,docs/,img/,CNAMEfor bothenandnllocales. Remaining broken-link mentions are warnings, not errors.Follow-ups (not in scope)
linking to /nl/warnings (auto-generated cross-locale links).onBrokenMarkdownLinkstomarkdown.hooks.onBrokenMarkdownLinks(Docusaurus deprecation warning).