Check links on CI (#902)

# Description
Markdown files contain a plenty of links which tend to get outdated
occasionally. It's hard to notice when a certain link (local or global)
becomes broken.

In the past, the [`xrefcheck`](https://github.com/serokell/xrefcheck)
tool was used to find broken links:
* #3
* #454

This PR automates `xrefcheck` running by adding it as a new GitHub
Action job. It uses
[xrefcheck-action](https://github.com/serokell/xrefcheck-action) under
the hood.

Resolves #4

In the second commit I tried to fix/ignore broken links detected by
`xrefcheck` using my best judgement. AFAIU `docs/website` contains
sources for https://ouroboros-consensus.cardano.intersectmbo.org/, so I
used that site to check some links.
1. Links in `References.md`, `index.md` and `TechnicalReports.md` don't
work on GitHub because they are invalid in the sense of Markdown, but
they work fine on the website, so I didn't touch them and added a
comment to make `xrefcheck` ignore them.
2. `Glossary.md` contains many links to anchors in the same file. These
anchors work differently in Markdown and Docusarus as can be seen
[here](https://ouroboros-consensus.cardano.intersectmbo.org/docs/for-developers/Glossary/).
Ideally, they should be fixed to work on the resulting website, in which
case all of them would be broken in the sense of Markdown. Fixing them
for Docusaurus is out of scope of this PR, but since they will probably
become broken in the sense of Markdown, I've instructed `xrefcheck` to
ignore all links in that file.
3. There is also an anchor link in `VersioningSchemeDecision.md`, but
this file is not used in the resulting website, so I've fixed it
according to Markdown rules.

There are also some global/absolute links that return 404 and I couldn't
find how to fix them.

```

  ➥  In file docs/website/contents/for-developers/AbstractProtocol.md
     bad reference (external) at src:7:3-178:
       - text: "Ouroboros.Consensus.Tutorial.Simple"
       - link: https://github.com/IntersectMBO/ouroboros-consensus/blob/master/ouroboros-consensus/src/tutorials/Ouroboros/Consensus/Tutorial/Simple.lhs
       - anchor: -

     ⛂  Resource unavailable (404 Not Found)

  ➥  In file docs/website/contents/for-developers/AbstractProtocol.md
     bad reference (external) at src:9:3-184:
       - text: "Ouroboros.Consensus.Tutorial.WithEpoch"
       - link: https://github.com/IntersectMBO/ouroboros-consensus/blob/master/ouroboros-consensus/src/tutorials/Ouroboros/Consensus/Tutorial/WithEpoch.lhs
       - anchor: -

     ⛂  Resource unavailable (404 Not Found)
```

Author: jasagredo

.github/workflows/checks.yml

@@ -108,3 +108,14 @@ jobs:
 
     - name: Diff plans
       run: GH=1 ./scripts/release/cabal-plan-diff.sh
+
+  xrefcheck:
+
+    name: Check references
+    runs-on: ubuntu-latest
+
+    steps:
+    - uses: actions/checkout@v4
+    - uses: serokell/xrefcheck-action@v1
+      with:
+        xrefcheck-version: 0.3.1

CONTRIBUTING.md

@@ -28,8 +28,8 @@ We have two types of documentation:
 When starting to work on Consensus, we recommend to take a look at the following
 resources:
 
- - [Preflight guide](https://ouroboros-consensus.cardano.intersectmbo.org/docs/for-developers/PreflightGuide)
- - [Glossary](https://ouroboros-consensus.cardano.intersectmbo.org/docs/for-developers/Glossary)
+ - [Preflight guide](https://ouroboros-consensus.cardano.intersectmbo.org/docs/for-developers/PreflightGuide/)
+ - [Glossary](https://ouroboros-consensus.cardano.intersectmbo.org/docs/for-developers/Glossary/)
 
 When adding or improving documentation about the implementation, it is
 preferable to add haddock comments since they are closer to the code. However
@@ -53,7 +53,7 @@ live in this repository.
 
 ## Using Nix
 
-Consensus can be built using [Nix](https://nixos.org/download.html). The
+Consensus can be built using [Nix](https://nixos.org/download/). The
 installation and configuration instructions are taken from
 [cardano-node](https://github.com/input-output-hk/cardano-node-wiki/blob/main/docs/getting-started/building-the-node-using-nix.md),
 and detailed below. To install `nix` run:
@@ -378,5 +378,5 @@ See [Cardano engineering
 handbook](https://github.com/input-output-hk/cardano-engineering-handbook/blob/main/CODE-OF-CONDUCT.md)'s
 code of conduct.
 
-[haddock-site]: https://haskell-haddock.readthedocs.io/en/latest/
+[haddock-site]: https://haskell-haddock.readthedocs.io/latest/
 [chap]: https://github.com/IntersectMBO/cardano-haskell-packages

docs/website/contents/about-ouroboros/References.md

@@ -2,13 +2,18 @@
 
 The following artifacts influence and/or describe the Consensus implementation.
 
+<!-- xrefcheck: ignore link -->
 * [Technical reports](../for-developers/TechnicalReports)
 * From the IOG researchers:
     * [Ouroboros BFT][ouroboros-bft]
     * [Ouroboros Praos][ouroboros-praos]
     * [Ouroboros Genesis][ouroboros-genesis]
 * [Ledger specifications][cardano-ledger].
-* Consensus (Praos) specification: [Agda style](/pdfs/consensus-spec-agda.pdf), [LaTeX style](/pdfs/consensus-spec.pdf)
+* Consensus (Praos) specification:
+    <!-- xrefcheck: ignore link -->
+    [Agda style](/pdfs/consensus-spec-agda.pdf),
+    <!-- xrefcheck: ignore link -->
+    [LaTeX style](/pdfs/consensus-spec.pdf)
 * [Quick reference table for all Cardano features](https://github.com/cardano-foundation/CIPs/blob/master/CIP-0059/feature-table.md).
   This includes the dates and first slot numbers of all eras and hard forks.
 * IOG media:

docs/website/contents/about-ouroboros/index.md

@@ -40,6 +40,7 @@ The Ouroboros research papers that formalize the different protocols (such as Pr
 - the honest nodes will all continually and eventually agree on what the best chain is (unless an adversary controls more than half of the network's stake).
 - the best chain grows over time.
 
+<!-- xrefcheck: ignore link -->
 The Consensus Layer defines the core Consensus components and logic, notably the
 Ouroboros protocol. See [References](References).
 

docs/website/contents/for-developers/ChainSync.md

@@ -158,4 +158,4 @@ trim their fragment so that it is anchored at our anchor point.
   sufficient number of headers to determine if their chain is preferred over
   ours (this needs careful consideration when adopting genesis).
 
-[^glossary]: See the [Glossary](https://ouroboros-consensus.cardano.intersectmbo.org/docs/for-developers/Glossary)
+[^glossary]: See the [Glossary](https://ouroboros-consensus.cardano.intersectmbo.org/docs/for-developers/Glossary/)

docs/website/contents/for-developers/GitProcess.md

@@ -66,7 +66,7 @@ If you'd like to opt-in to that or similar, add a `cabal.project.local` file.
     #NNNN`. See the [GitHub documentation][gh-auto-link-issue] for similar
     keywords and syntax that will trigger useful automatic behaviors.
 
-    [gh-auto-link-issue]: https://docs.github.com/en/issues/tracking-your-work-with-issues/linking-a-pull-request-to-an-issue#linking-a-pull-request-to-an-issue-using-a-keyword
+    [gh-auto-link-issue]: https://docs.github.com/en/issues/tracking-your-work-with-issues/using-issues/linking-a-pull-request-to-an-issue#linking-a-pull-request-to-an-issue-using-a-keyword
 
   * Your PR should be a [Draft PR][github-draft-pr] until you think it is ready
     for final review and merging. I often open my PR as Draft PR in order to get
@@ -76,7 +76,7 @@ If you'd like to opt-in to that or similar, add a `cabal.project.local` file.
     This is far superior to including "WIP" or "DO NOT MERGE" in the PR title,
     or a WIP label, etc.
 
-    [github-draft-pr]: https://github.blog/2019-02-14-introducing-draft-pull-requests/
+    [github-draft-pr]: https://github.blog/news-insights/product-news/introducing-draft-pull-requests/
 
   * Your branch name is impermanent, so it's less important than the above.
     However, we prefer the format `username/issue-NNNN-short-description` or

docs/website/contents/for-developers/Glossary.md

@@ -1,3 +1,4 @@
+<!-- xrefcheck: ignore all -->
 # Glossary
 
 Notes on the use and maintenance of this glossary:

docs/website/contents/for-developers/HandlingBlocksFromTheFuture.md

@@ -41,4 +41,4 @@ In the future we might delete blocks from the future from the `VolatileDB` to im
 # References
 
 - [Original issue that prompted the fix](https://github.com/IntersectMBO/ouroboros-network/issues/4251)
-- [Blocks from the future (Incident report)](https://updates.cardano.intersectmbo.org/2024-09-07-incident)
+- [Blocks from the future (Incident report)](https://updates.cardano.intersectmbo.org/2024-09-07-incident/)

docs/website/contents/for-developers/NodeTasks.md

@@ -1,5 +1,6 @@
 # Overview of the tasks of a caught-up node
 
+<!-- xrefcheck: ignore link -->
 This document gives an overview of the tasks of a [caught-up](./Glossary.md#honest-caught-up-parties) node, both as a relay and as a block producer.
 
 ## In a single node
@@ -22,7 +23,8 @@ The selection is made up of an immutable and a volatile part:
  - The volatile part of the selection are the newest $k$ blocks.
    They are stored in the VolatileDB, together with other blocks that could be on a fork we might switch to in the future.
 
-Additionally, the LedgerDB contains the ledger state corresponding to all [points](./Glossary/#point) on the volatile part of the chain as well as the tip of the immutable chain, in order to validate new blocks and potential forks.
+<!-- xrefcheck: ignore link -->
+Additionally, the LedgerDB contains the ledger state corresponding to all [points](./Glossary.md#point) on the volatile part of the chain as well as the tip of the immutable chain, in order to validate new blocks and potential forks.
 
 The flow of information is depicted in the following diagram.
 Rectangular boxes stand for logical components, and hexagons correspond to Haskell RTS threads.

docs/website/contents/for-developers/PreflightGuide.md

@@ -259,7 +259,7 @@ Finally, we shall note that there are various ideas of how to eliminate grinding
 [^utxo-hd]: The main reason for this is that the ledger state, ie the aggregated information necessary to validate blocks, is currently fully stored in memory.
 The Consensus team is currently working on *UTxO HD*, a solution to move the ledger state to disk.
 
-[^resource-relative]: Cardano is not a huge outlier in either direction, there are many examples for blockchains that are either much less resource-intensive (due to very low activity or new age, or due to very fancy cryptography, like Mina) or much more resource-intensive (due to very old age and large accumulated history, like Bitcoin, or a hyperfocus on performance, like [Solana](https://docs.solana.com/running-validator/validator-reqs#hardware-recommendations)).
+[^resource-relative]: Cardano is not a huge outlier in either direction, there are many examples for blockchains that are either much less resource-intensive (due to very low activity or new age, or due to very fancy cryptography, like Mina) or much more resource-intensive (due to very old age and large accumulated history, like Bitcoin, or a hyperfocus on performance, like [Solana](https://docs.anza.xyz/operations/requirements#hardware-recommendations)).
 
 [^genesis-syncing]: As of early 2024, syncing is a fully trusted process; if any node you are syncing from is adversarial, you might end up on an adversarial chain.
 There is an ongoing effort to implement *Ouroboros Genesis* in order to reduce this strong trust assumption; in particular, it will involve reaching out to lots of nodes while syncing.
@@ -293,17 +293,17 @@ for Ungrindable Blockchains" by Kiayias et al](https://eprint.iacr.org/2021/1698
 [cardano-cli]: https://github.com/IntersectMBO/cardano-cli
 [cardano-db-sync]: https://github.com/IntersectMBO/cardano-db-sync
 [kupo]: https://github.com/cardanosolutions/kupo
-[hydra]: https://github.com/input-output-hk/hydra
+[hydra]: https://github.com/cardano-scaling/hydra
 [ogmios]: https://github.com/CardanoSolutions/ogmios
 [node release page]: https://github.com/IntersectMBO/cardano-node/releases
 [cardano mainnet conf]: https://github.com/IntersectMBO/cardano-node/blob/master/configuration/cardano/mainnet-config.yaml
 [cardano mainnet topo]: https://github.com/IntersectMBO/cardano-node/blob/master/configuration/cardano/mainnet-topology.json
-[Mithril client]: https://mithril.network/doc
-[Mithril instructions]: https://mithril.network/doc/manual/getting-started/bootstrap-cardano-node
+[Mithril client]: https://mithril.network/doc/
+[Mithril instructions]: https://mithril.network/doc/manual/getting-started/bootstrap-cardano-node/
 [Magic Wormhole]: https://github.com/magic-wormhole/magic-wormhole
 [db-analyser]: https://github.com/IntersectMBO/ouroboros-consensus/blob/main/ouroboros-consensus-cardano/README.md#db-analyser
 [Cardano ledger]: https://github.com/IntersectMBO/cardano-ledger
-[Glossary]: https://ouroboros-consensus.cardano.intersectmbo.org/docs/for-developers/Glossary
+[Glossary]: https://ouroboros-consensus.cardano.intersectmbo.org/docs/for-developers/Glossary/
 [db-analyser snapshot]: https://github.com/IntersectMBO/ouroboros-consensus/blob/main/ouroboros-consensus-cardano/README.md#saving-a-snapshot
 [preflight epic]: https://github.com/IntersectMBO/ouroboros-consensus/issues/887
 [Ouroboros Praos paper]: https://iohk.io/en/research/library/papers/ouroboros-praos-an-adaptively-secure-semi-synchronous-proof-of-stake-protocol/