The Continuous Delivery workflow has been failing on every push to main since #71 bumped Docusaurus to 3.10.0 (see run https://github.com/cloudnative-pg/docs/actions/runs/24657495260).
Two things broke at once.
First, 3.10 now requires @docusaurus/faster as an explicit dependency whenever future.v4: true is set, instead of pulling it in transitively. The build stops with To enable Docusaurus Faster options, your site must add the @docusaurus/faster package as a dependency.
Second, future.v4: true also flips mdx1CompatDisabledByDefault to true, so HTML comments in .md files are no longer parsed. The markdown block we already have in website/docusaurus.config.ts was supposed to keep them enabled, but it is misplaced (nested inside themeConfig) and uses invalid keys (allowComments, allowHtml instead of comments, admonitions, headingIds), so it has been a silent no-op. It only worked on 3.9 because the defaults happened to be right.
Fix: add @docusaurus/faster 3.10.0 to website/package.json, and move the markdown block to the top level of Config with the correct mdx1Compat keys.
The
Continuous Deliveryworkflow has been failing on every push tomainsince #71 bumped Docusaurus to3.10.0(see run https://github.com/cloudnative-pg/docs/actions/runs/24657495260).Two things broke at once.
First, 3.10 now requires
@docusaurus/fasteras an explicit dependency wheneverfuture.v4: trueis set, instead of pulling it in transitively. The build stops withTo enable Docusaurus Faster options, your site must add the @docusaurus/faster package as a dependency.Second,
future.v4: truealso flipsmdx1CompatDisabledByDefaulttotrue, so HTML comments in.mdfiles are no longer parsed. Themarkdownblock we already have inwebsite/docusaurus.config.tswas supposed to keep them enabled, but it is misplaced (nested insidethemeConfig) and uses invalid keys (allowComments,allowHtmlinstead ofcomments,admonitions,headingIds), so it has been a silent no-op. It only worked on 3.9 because the defaults happened to be right.Fix: add
@docusaurus/faster3.10.0towebsite/package.json, and move themarkdownblock to the top level ofConfigwith the correctmdx1Compatkeys.