Enable Docusaurus future flags to prepare for v4

[roynakakawa]

Content

• Fixed styling issues after enabling future flags to prepare for Docusaurus v4.
• Migrated the deprecated onBrokenMarkdownLinks option to markdown.hooks.
• Fixed admonitions with a custom title.
• Fixed small regression bugs.
• Verified npm run build passes locally (Fedora Linux 44, kernel 7.0.13-200.fc44.x86_64)

Pre-submit checklist

N/A - minor change

Comments

My first PR, so let me know if any additional formatting required.

Issue(s)

Related to draft https://github.com/orgs/input-output-hk/projects/26/views/14?pane=issue&itemId=119928726

[github-actions]

Test Results

     5 files  ± 0     209 suites  ±0   45m 12s ⏱️ - 2h 37m 46s
 3 307 tests  - 76   3 307 ✅  - 76  0 💤 ±0  0 ❌ ±0 
11 033 runs   - 85  11 033 ✅  - 85  0 💤 ±0  0 ❌ ±0 

Results for commit 8d1fac3. ± Comparison against base commit e0e38d6.

This pull request removes 76 tests.

mithril-stm ‑ circuits::halo2::tests::golden::cases::negative::slow::index_out_of_bounds
mithril-stm ‑ circuits::halo2::tests::golden::cases::negative::slow::index_too_large_for_circuit_range
mithril-stm ‑ circuits::halo2::tests::golden::cases::negative::slow::indices_not_increasing
mithril-stm ‑ circuits::halo2::tests::golden::cases::negative::slow::leaf_merkle_path_mismatch
mithril-stm ‑ circuits::halo2::tests::golden::cases::negative::slow::leaf_swap_keep_merkle_path
mithril-stm ‑ circuits::halo2::tests::golden::cases::negative::slow::leaf_wrong_verification_key
mithril-stm ‑ circuits::halo2::tests::golden::cases::negative::slow::merkle_path_corrupt_sibling
mithril-stm ‑ circuits::halo2::tests::golden::cases::negative::slow::merkle_path_flip_position
mithril-stm ‑ circuits::halo2::tests::golden::cases::negative::slow::merkle_path_length_long
mithril-stm ‑ circuits::halo2::tests::golden::cases::negative::slow::merkle_path_length_short
…

♻️ This comment has been updated with latest results.

[Alenar]

Sadly there's two issues:

1. enabling useCssCascadeLayers just broke the website design except on the home page (see animation)
2. Admonitions with a custom title are broken (visible at the bottom of the animation, it now show "::note Note")

For 1. it's a limitation with the redesign (#2597) as it straight copied some docusaurus components, meaning that to update them for useCssCascadeLayers we basically have to redo the design.
Here's what the designer answered to that concern:

When upgrading to docusaurus 4 you may indeed need to stash the changed theme components and manually check what/where to change so that you get the same nav and footer component as right now - it may end up being a simple swap in depending on what components are reworked.

Though with it they appear to be shifting away from their .css file and moving to infima so a revision of the docs site will be required regardless of the theme directory components.

We may look into it, but I think that task will be difficult without a designer.

For 2. the fix is simple, the custom title must be surround by brackets, e.g.:

-:::info Update 2024/10/02
+:::info[Update 2024/10/02]

This have to be applied to all admonitions with a custom title (which can be found by tracking :::).

[roynakakawa]

thanks @Alenar. I'll take a look and try to fix it.

[Alenar]

It's better, but there's still some regression

Full page screen:

Focus on content with missing border:

Broken "on hover" code block buttons

From those animated images we can see:

• Missing accent color for the menu item of the current page (Manual)
• The Mithril logo is sightly smaller
• Container size differences: the left sidebar is sightly larger and the main content width is sightly less large (not an huge issue tbh)
• ⚠️ Missing borders:
  • on the Install it today! link
  • between the left and right sidebars and the content
  • On the left of the quoted "last update" date
  • below the selected tab (Mainnet)
  • around "back quoted" values (e.g. most values in the table second column). Note: the fix for single back quoted text should not impact "triple backquote" / "code blocks" (which is fine with your current code).
• Buttons visible "on hover" on code blocks are broken (missing border and content padding)

There's another regression in the dev blog article titles who lost their size :

• Before:

• After:

[Copilot]

Pull request overview

This PR prepares the documentation website for an eventual Docusaurus v4 upgrade by enabling v4 future flags, migrating deprecated config, and adjusting docs/CSS to match updated parsing and styling behavior.

Changes:

• Enabled Docusaurus v4 future flags and migrated onBrokenMarkdownLinks into markdown.hooks.
• Updated admonition syntax and list formatting in multiple docs/blog posts for MDX/Docusaurus compatibility.
• Added/adjusted CSS overrides to fix styling regressions (notably Tailwind preflight vs Infima interactions) and restore expected hover behavior.

Reviewed changes

Copilot reviewed 17 out of 17 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
docs/website/docusaurus.config.js	Enables Docusaurus v4 future flags and migrates broken-markdown-link handling to markdown.hooks.
docs/website/src/css/custom.css	Adds hover styles and multiple Infima override rules to resolve styling conflicts under future flags.
docs/website/root/mithril/advanced/threat-model.md	Updates admonition title syntax and minor formatting for compatibility.
docs/website/versioned_docs/version-maintained/mithril/advanced/threat-model.md	Same admonition/formatting adjustments for the maintained doc version.
docs/website/root/mithril/advanced/mithril-protocol/protocol.md	Updates admonition syntax and list formatting for compatibility.
docs/website/versioned_docs/version-maintained/mithril/advanced/mithril-protocol/protocol.md	Same admonition/formatting adjustments for the maintained doc version.
docs/website/versioned_docs/version-maintained/mithril/advanced/mithril-protocol/certificates.md	Updates admonition syntax for compatibility.
docs/website/root/manual/operate/run-signer-node.md	Adds spacing/formatting tweaks for stable rendering with new markdown behavior.
docs/website/versioned_docs/version-maintained/manual/operate/run-signer-node.md	Same formatting tweaks for the maintained doc version.
docs/website/root/manual/operate/run-aggregator-node.md	Adds spacing/formatting tweaks for stable rendering with new markdown behavior.
docs/website/versioned_docs/version-maintained/manual/operate/run-aggregator-node.md	Same formatting tweaks for the maintained doc version.
docs/website/blog/2026-01-06-multiple-aggregators-testing-program.md	Updates admonition title syntax for compatibility.
docs/website/blog/2026-01-06-dmq-testing-program.md	Updates admonition title syntax for compatibility.
docs/website/blog/2025-11-03-distribution-2543.md	Updates admonition title syntax for compatibility.
docs/website/blog/2025-06-17-client-cli-cardano-database-backends.md	Adds spacing/formatting tweaks for stable rendering.
docs/website/blog/2024-12-17-era-switch-pythagoras.md	Adds spacing/formatting tweaks for stable rendering.
docs/website/blog/2022-10-11-keys-certification-badge/index.md	Adds spacing/formatting tweaks for stable rendering.