Upgrade docusaurus from 2 to 3. (#1768)

This is an attempt to upgrade docurusarus in response to the baffling
bug observed in
https://github.com/cardano-scaling/hydra/actions/runs/12433830444/job/34716776448?pr=1715.

Todo:

- [x] Restore the deleted `mdx` sections with appropriate new
functionality from docusaurus -
https://docusaurus.io/blog/2022/09/01/docusaurus-2.1#doccardlist-improvements
- [x] Make sure the site works as-before (test it locally)
- [x] Make a note in our changelog
- [x] Update the readme in `./docs/`; it says Docusaurus 2 and has a
bunch of other dead/old links.

---

<!-- Consider each and tick it off one way or the other -->
* [x] CHANGELOG updated or not needed
* [x] Documentation updated or not needed
* [x] Haddocks updated or not needed
* [x] No new TODOs introduced or explained herafter

CHANGELOG.md

@@ -10,6 +10,8 @@ changes.
 
 ## [0.20.0] - UNRELEASED
 
+- Bump docusaurus version
+
 - **IMPORTANT - Do not release this version**
    - Incremental commits - off-chain changes to make the incremental commits possible.
      Important to note is that on-chain security is not implemented and hydra-node in this

docs/README.md

@@ -4,7 +4,7 @@ Sources for the [user manual 📖](https://input-output-hk.github.io/hydra).
 
 # Building
 
-The user-manual is built using [Docusaurus 2](https://docusaurus.io/), which combines React components and markdown into a customisable static website. Docusaurus supports a set of plugins and basic features (coming in the form of _'presets'_). We use it to create the actual user manual (docs), documenting our [architectural decision records](https://input-output-hk.github.io/hydra/head-protocol/adr), a custom page for the [API reference](https://input-output-hk.github.io/hydra/head-protocol/api-reference), and various other documentation pages around the Hydra Head protocol. 
+The user-manual is built using [Docusaurus 3](https://docusaurus.io/), which combines React components and markdown into a customisable static website. Docusaurus supports a set of plugins and basic features (coming in the form of _'presets'_). We use it to create the actual user manual (docs), documenting our [architectural decision records](https://input-output-hk.github.io/hydra/head-protocol/adr), a custom page for the [API reference](https://input-output-hk.github.io/hydra/head-protocol/api-reference), and various other documentation pages around the Hydra Head protocol.
 
 #### Installation
 
@@ -30,14 +30,15 @@ This command generates static content into the `build` directory and can be serv
 
 Note that this will have quite some broken links as we are referring to
 generated documentation, test data and benchmarks. To put these artifacts at the
-right place before, you can use these `nix` builds from the repository root:
+right place before, you can use these `nix` builds from this folder:
 
 ```console
-nix build .#spec && ln -s $(readlink result)/hydra-spec.pdf docs/static/hydra-spec.pdf
-nix build .#haddocks -o docs/static/haddock
-
-(cd hydra-node; nix develop .#hydra-node-bench --command tx-cost --output-directory $(pwd)/../docs/benchmarks)
-(cd hydra-cluster; nix develop .#hydra-cluster-bench --command bench-e2e --scaling-factor 1 --output-directory $(pwd)/../docs/benchmarks)
+nix build .#spec && ln -s $(readlink result)/hydra-spec.pdf static/hydra-spec.pdf
+nix build .#haddocks && \
+      rm -rf static/haddock && \
+      mkdir -p static/haddock && \
+      cp -r result/* static/haddock && \
+      chmod +rwx -R static/haddock
 ```
 
 # Style guide

docs/adr/2021-06-09_005-use-io-sim-classes.md

@@ -16,7 +16,7 @@ Although we try to contain the use of IO at the outskirt of the Hydra node using
 
 Testing asynchronous and concurrent code is notoriously painful
 
-The ouroboros consensus test suite and [hydra-sim](https://github.com/input-output-hk/hydra-sim) simulation have demonstrated the effectiveness of abstracting concurrent primitives through the use of typeclasses (MTL-style pattern) and being able to run these as pure code, harvesting and analysing produced execution traces.
+The ouroboros consensus test suite and [hydra-sim](https://github.com/cardano-scaling/hydra-sim) simulation have demonstrated the effectiveness of abstracting concurrent primitives through the use of typeclasses (MTL-style pattern) and being able to run these as pure code, harvesting and analysing produced execution traces.
 
 There are other such libraries, e.g. [concurrency](https://hackage.haskell.org/package/concurrency) and [dejafu](https://hackage.haskell.org/package/dejafu), as well as the venerable [exceptions](https://hackage.haskell.org/package/exceptions) (for abstracting exception throwing).
 

docs/adr/2022-03-17_015-admin-api.md

@@ -18,7 +18,7 @@ Proposed
 * Having static network configuration is probably not sustainable in the long run, even if we don't add any fancy multihead capabilities to the node, as it would make it significantly harder to have automated creation of Heads.
 * There's been an [attempt](https://github.com/cardano-scaling/hydra/pull/222) at providing a file-based network configuration but this was deemed unconvincing
 * [Hydra paper (sec. 4, p. 13)](https://eprint.iacr.org/2020/299.pdf) explicitly assumes the existence of a _setup_ phase
-  * This _setup_ is currently left aside, e.g. exchange of keys for setting up multisig and identifying peers. The [hydra-node](https://github.com/input-output-hk/hydra/blob/abailly-iohk/admin-api-adr/hydra-node/exe/hydra-node/Main.hs#L41) executable is statically configured and those things are assumed to be known beforehand
+  * This _setup_ is currently left aside, e.g. exchange of keys for setting up multisig and identifying peers. The [hydra-node](https://github.com/cardano-scaling/hydra/blob/abailly-iohk/admin-api-adr/hydra-node/exe/hydra-node/Main.hs#L41) executable is statically configured and those things are assumed to be known beforehand
 
 ## Decision
 
@@ -41,7 +41,7 @@ The following picture sketches the proposed architectural change:
   * This API is an interface over a specific _resource_ controlled by the Hydra node, namely its knowledge of other peers with which new _Head_s can be opened. As such a proper REST interface (_not_ RPC-in-disguise) seems to make sense here, rather than stream/event-based [duplex communication channels](/adr/3)
   * We can easily extend such an API with WebSockets to provide notifications (e.g. peers connectivity, setup events...)
 * *Why a separate component?*
-  * We could imagine extending the existing [APIServer](https://github.com/input-output-hk/hydra/blob/9129c7c013fe2cdc77db048a54981e1ace0843b8/hydra-node/src/Hydra/API/Server.hs) interface with new messages related to this network configuration, however this seems to conflate different responsibilities in a single place: Configuring and managing the Hydra node itself, and configuring, managing, and interacting with the Head itself
+  * We could imagine extending the existing [APIServer](https://github.com/cardano-scaling/hydra/blob/9129c7c013fe2cdc77db048a54981e1ace0843b8/hydra-node/src/Hydra/API/Server.hs) interface with new messages related to this network configuration, however this seems to conflate different responsibilities in a single place: Configuring and managing the Hydra node itself, and configuring, managing, and interacting with the Head itself
   * "Physical" separation of endpoints makes it easier to secure a very sensitive part of the node, namely its administration, e.g by ensuring this can only be accessed through a specific network interface, without relying on application level authentication mechanisms
 
 ## Consequences

docs/adr/2022-03-23_016-keep-rejected-adr.md

@@ -14,7 +14,7 @@ Accepted
 
 We have started using _Architecture Decision Records_ as our primary way to document the most important design decisions we take while developing Hydra Node, and this has proved effective in fostering fruitful discussions about major architecture changes.
 
-During the course of this project, we have sometimes had debates on various topics leading to rejection of [some ADRs](https://github.com/input-output-hk/hydra/pull/230). It could be the case that  a previously rejected proposal turns out to be interesting, either because the context and situation have changed enough to reevaluate a proposal, or as background for some new proposal.
+During the course of this project, we have sometimes had debates on various topics leading to rejection of [some ADRs](https://github.com/cardano-scaling/hydra/pull/230). It could be the case that  a previously rejected proposal turns out to be interesting, either because the context and situation have changed enough to reevaluate a proposal, or as background for some new proposal.
 
 ## Decision
 

docs/adr/2022-04-13_018-single-state.md

@@ -16,7 +16,7 @@ Superseded by [ADR 23](/adr/23) and [ADR 26](/adr/26)
   1. A `HeadState tx` provided by the `HydraHead tx m` handle interface and part of the `Hydra.Node` module. It provides the basis for the main `hydra-node` business logic in `Hydra.Node.processNextEvent` and `Hydra.HeadLogic.update`
   [Creation](https://github.com/cardano-scaling/hydra/blob/a98e2907c4e425de2736782793383aad63132c14/hydra-node/src/Hydra/Node.hs#L256-L257), [Usage](https://github.com/cardano-scaling/hydra/blob/a98e2907c4e425de2736782793383aad63132c14/hydra-node/src/Hydra/Node.hs#L174)
   2. `SomeOnChainHeadState` is kept in the `Hydra.Chain.Direct` to keep track of the latest known head state, including notable transaction outputs and information how to spend it (e.g. scripts and datums)
-  [Code](https://github.com/input-output-hk/hydra/blob/a98e2907c4e425de2736782793383aad63132c14/hydra-node/src/Hydra/Chain/Direct.hs#L156-L162), [Usage 1](https://github.com/input-output-hk/hydra/blob/a98e2907c4e425de2736782793383aad63132c14/hydra-node/src/Hydra/Chain/Direct.hs#L449), [Usage 2](https://github.com/input-output-hk/hydra/blob/a98e2907c4e425de2736782793383aad63132c14/hydra-node/src/Hydra/Chain/Direct.hs#L414), [Usage 3](https://github.com/input-output-hk/hydra/blob/a98e2907c4e425de2736782793383aad63132c14/hydra-node/src/Hydra/Chain/Direct.hs#L349-L352)
+  [Code](https://github.com/cardano-scaling/hydra/blob/a98e2907c4e425de2736782793383aad63132c14/hydra-node/src/Hydra/Chain/Direct.hs#L156-L162), [Usage 1](https://github.com/cardano-scaling/hydra/blob/a98e2907c4e425de2736782793383aad63132c14/hydra-node/src/Hydra/Chain/Direct.hs#L449), [Usage 2](https://github.com/cardano-scaling/hydra/blob/a98e2907c4e425de2736782793383aad63132c14/hydra-node/src/Hydra/Chain/Direct.hs#L414), [Usage 3](https://github.com/cardano-scaling/hydra/blob/a98e2907c4e425de2736782793383aad63132c14/hydra-node/src/Hydra/Chain/Direct.hs#L349-L352)
   (There are other unrelated things kept in memory like the event history in the API server or a peer map in the network heartbeat component.)
 * The interface between the `Hydra.Node` and a `Hydra.Chain` component consists of 
   - constructing certain Head protocol transactions given a description of it (`PostChainTx tx`):
@@ -27,7 +27,7 @@ Superseded by [ADR 23](/adr/23) and [ADR 26](/adr/26)
     ```hs
     type ChainCallback tx m = OnChainTx tx -> m ()
     ```
-* Given by the usage sites above, the `Hydra.Chain.Direct` module requires additional info to do both, construct protocol transactions with `postTx` as well as observe potential `OnChainTx` ([here](https://github.com/input-output-hk/hydra/blob/a98e2907c4e425de2736782793383aad63132c14/hydra-node/src/Hydra/Chain/Direct.hs#L333-L336)). Hence we see that, operation of the `Hydra.Chain.Direct` component (and likely any implementing the interface fully) is **inherently stateful**.
+* Given by the usage sites above, the `Hydra.Chain.Direct` module requires additional info to do both, construct protocol transactions with `postTx` as well as observe potential `OnChainTx` ([here](https://github.com/cardano-scaling/hydra/blob/a98e2907c4e425de2736782793383aad63132c14/hydra-node/src/Hydra/Chain/Direct.hs#L333-L336)). Hence we see that, operation of the `Hydra.Chain.Direct` component (and likely any implementing the interface fully) is **inherently stateful**.
 * We are looking at upcoming features to [handle rollbacks](https://github.com/cardano-scaling/hydra/issues/185) and dealing with [persisting the head state](https://github.com/cardano-scaling/hydra/issues/187).
   - Both could benefit from the idea, that the `HeadState` is just a result of pure `Event` processing (a.k.a event sourcing).
   - Right now the `HeadState` kept in `Hydra.Node` alone, is not enough to fully describe the state of the `hydra-node`. Hence it would not be enough to just persist all the `Event`s and replaying them to achieve persistence, nor resetting to some previous `HeadState` in the presence of a rollback.

docs/adr/2022-12-06_022-model-based-testing.md

@@ -13,7 +13,7 @@ Accepted
 ## Context
 
 - We have been experimenting with [quickcheck-dynamic](https://hackage.org/packages/quickcheck-dynamic) for a while, leading to the implementation of basic [Model-Based tests](https://github.com/cardano-scaling/hydra/blob/master/hydra-node/test/Hydra/ModelSpec.hs) for the Hydra Head Protocol
-- These tests fill a gap in our testing strategy, between [BehaviorSpec](https://github.com/input-output-hk/hydra/blob/master/hydra-node/test/Hydra/BehaviorSpec.hs) tests which test a "network" of nodes but only at the level of the off-chain Head logic, and [EndToEndSpec](https://github.com/input-output-hk/hydra/blob/master/hydra-cluster/test/Test/EndToEndSpec.hs) tests which test a full blown network of nodes interconnected through real network connections and to a real cardano-node:
+- These tests fill a gap in our testing strategy, between [BehaviorSpec](https://github.com/cardano-scaling/hydra/blob/master/hydra-node/test/Hydra/BehaviorSpec.hs) tests which test a "network" of nodes but only at the level of the off-chain Head logic, and [EndToEndSpec](https://github.com/cardano-scaling/hydra/blob/master/hydra-cluster/test/Test/EndToEndSpec.hs) tests which test a full blown network of nodes interconnected through real network connections and to a real cardano-node:
   - The former are fast but do not test the complete lifecycle of a Head. Furthermore, they are only unit tests so do not provide coverage into various corner cases that could arise in practice
   - The latter exercise the full lifecycle but are very slow and brittle
 - Because they run in [io-sim](https://github.com/input-output-hk/io-sim), those Model-based tests are fast and robust as they don't depend on system interactions. Moreover, decoupling the _System-under-Test_ from `IO` makes it easy to simulate an environment that deviates from the "happy path" such as delays from the network, filesystem errors, or even adversarial behaviour from the node, or the chain.

docs/adr/2023-06-19_024-event-sourced-persistence.md

@@ -13,7 +13,7 @@ Accepted
 ## Context
 
 - The state of a Hydra Head is currently persisted as a whole upon each `NewState` _outcome_ from the `update` function: The new state is serialised and the `state` file is overwritten with the corresponding bytes. While this is a straightforward strategy to implement, it has a huge impact on the performance of a Hydra Head as serialising a large data structure like the `HeadState` and completely overwriting a file is costly
-  - We revisited our benchmarks and [found](https://github.com/input-output-hk/hydra/issues/186#issuecomment-1584292265) that persistence was the major bottleneck when measuring roundtrip confirmation time,e g. the time it takes from a client's perspective to submit a transaction and observe in a `ConfirmedSnapshot`
+  - We revisited our benchmarks and [found](https://github.com/cardano-scaling/hydra/issues/186#issuecomment-1584292265) that persistence was the major bottleneck when measuring roundtrip confirmation time,e g. the time it takes from a client's perspective to submit a transaction and observe in a `ConfirmedSnapshot`
 - Furthermore, the way we currently handle changes to the `HeadState` in the hydra-node, while conceptually being an `Effect` is handled differently from other `Effect`s: The state is updated transactionally through a dedicated `modifyHeadState` function in the core loop of processing events, and _then_ effects are processed.
 
 ## Decision
@@ -55,4 +55,4 @@ sequenceDiagram
   - Instead of having the `HeadLogic` emits directly a `ClientEffect`, the latter could be the result of a client-centric _interpretation_ of a `StateChanged`.
   - Pushing this a little further, we could maintain a _Query Model_ for clients with a dedicated [Query API](https://github.com/cardano-scaling/hydra/discussions/686) to ease implementation of stateless clients.
 
-- Calling `StateChanged` an _event_ while treating it in the code alongside _effects_ might introduce some confusion as we already use the word [Event](https://github.com/input-output-hk/hydra/blob/45913954eb18ef550a31017daa443cee6720a00c/hydra-node/src/Hydra/HeadLogic.hs#L64) to designate the inputs (a.k.a. commands) to the Head logic state machine. We might want at some later point to unify the terminology.
+- Calling `StateChanged` an _event_ while treating it in the code alongside _effects_ might introduce some confusion as we already use the word [Event](https://github.com/cardano-scaling/hydra/blob/45913954eb18ef550a31017daa443cee6720a00c/hydra-node/src/Hydra/HeadLogic.hs#L64) to designate the inputs (a.k.a. commands) to the Head logic state machine. We might want at some later point to unify the terminology.

docs/adr/2023-09-09_027-network-resilience.md

@@ -43,7 +43,7 @@ Therefore, the scope of this ADR is to address only point 1. above: Ensure broad
         withOuroborosNetwork (contramap Network tracer) localhost peers
     ```
 
-  * This has the nice property that we can basically swap the lower layers should we need to, for example to use [UDP](https://github.com/input-output-hk/hydra/blob/abailly-iohk/multi-node-udp/hydra-node/src/Hydra/Network/UDP.hs), or add other layers for example to address specific head instances in presence of [multiple heads](https://github.com/input-output-hk/hydra/blob/abailly-iohk/multi-node-udp/hydra-node/src/Hydra/Network/MultiHead.hs#L26)
+  * This has the nice property that we can basically swap the lower layers should we need to, for example to use [UDP](https://github.com/cardano-scaling/hydra/blob/abailly-iohk/multi-node-udp/hydra-node/src/Hydra/Network/UDP.hs), or add other layers for example to address specific head instances in presence of [multiple heads](https://github.com/cardano-scaling/hydra/blob/abailly-iohk/multi-node-udp/hydra-node/src/Hydra/Network/MultiHead.hs#L26)
 
 ## Decision
 

docs/adr/2023-12-06_030-use-cbor-for-tx.md

@@ -12,7 +12,7 @@ Accepted
 
 ## Context
 
-* The [Hydra.Ledger.Cardano](https://github.com/input-output-hk/hydra/blob/b2dc5a0da4988631bd2c1e94b66ba6217d5db595/hydra-node/src/Hydra/Ledger/Cardano.hs#L127) module provides `ToJSON/FromJSON` instances for `Tx` and [AlonzoTx](https://github.com/input-output-hk/hydra/blob/b2dc5a0da4988631bd2c1e94b66ba6217d5db595/hydra-node/src/Hydra/Ledger/Cardano/Json.hs#L361)
+* The [Hydra.Ledger.Cardano](https://github.com/cardano-scaling/hydra/blob/b2dc5a0da4988631bd2c1e94b66ba6217d5db595/hydra-node/src/Hydra/Ledger/Cardano.hs#L127) module provides `ToJSON/FromJSON` instances for `Tx` and [AlonzoTx](https://github.com/cardano-scaling/hydra/blob/b2dc5a0da4988631bd2c1e94b66ba6217d5db595/hydra-node/src/Hydra/Ledger/Cardano/Json.hs#L361)
   * We have specified this format as part of [Hydra API](https://github.com/cardano-scaling/hydra/blob/b2dc5a0da4988631bd2c1e94b66ba6217d5db595/hydra-node/json-schemas/api.yaml#L1473)
 * These instances appear in a few places as part of Hydra API:
   * In the [ServerOutput](https://github.com/cardano-scaling/hydra/blob/b2dc5a0da4988631bd2c1e94b66ba6217d5db595/hydra-node/src/Hydra/API/ServerOutput.hs#L51) sent by the node to clients
@@ -22,7 +22,7 @@ Accepted
   * In the [Network.Message](https://github.com/cardano-scaling/hydra/blob/b2dc5a0da4988631bd2c1e94b66ba6217d5db595/hydra-node/src/Hydra/Network/Message.hs#L20) exchanged between the nodes
   * In the [ClientInput](https://github.com/cardano-scaling/hydra/blob/b2dc5a0da4988631bd2c1e94b66ba6217d5db595/hydra-node/src/Hydra/API/ClientInput.hs#L9) from clients submitting `NewTx` commands
   * In the [HTTPServer](https://github.com/cardano-scaling/hydra/blob/b2dc5a0da4988631bd2c1e94b66ba6217d5db595/hydra-node/src/Hydra/API/HTTPServer.hs#L297) API
-* Note that in the latter 2 cases, the hydra-node _accepts_ a hex-CBOR-encoded _JSON string_ to represent a transaction and this particular case is handled directly in the [FromJSON](https://github.com/input-output-hk/hydra/blob/b2dc5a0da4988631bd2c1e94b66ba6217d5db595/hydra-node/src/Hydra/Ledger/Cardano/Json.hs#L388) instance for transactions where 3 different representations are even accepted:
+* Note that in the latter 2 cases, the hydra-node _accepts_ a hex-CBOR-encoded _JSON string_ to represent a transaction and this particular case is handled directly in the [FromJSON](https://github.com/cardano-scaling/hydra/blob/b2dc5a0da4988631bd2c1e94b66ba6217d5db595/hydra-node/src/Hydra/Ledger/Cardano/Json.hs#L388) instance for transactions where 3 different representations are even accepted:
   * JSON object detailing the transaction
   * A JSON string representing CBOR-encoding of a transaction
   * Or a `TextEnvelope` which wraps the CBOR transaction in a simple JSON object