feat: MDBook linkcheck (#192)

* Update broken link ghash.rs

* Update broken link  gcm.rs

* fix formatting in aes/README.md

* Update broken links README.md

* Create checklinks.yml

* Update deploy.yml

* Update checklinks.yml

* Update README.md

* Delete lychee

* Update book.toml

* Create mdbook-test.yaml

* fix: two tests in `poseidon/README.md`

* cleanup mdbook

* Update mdbook-test.yaml

* Update book.toml

* fix: update workflows

---------

Co-authored-by: Colin Roberts <colin@primitive.xyz>

Author: youyyytrok

.github/workflows/deploy.yml

@@ -27,6 +27,7 @@ jobs:
     env:
       MDBOOK_VERSION: 0.4.43
       MDBOOK_KATEX_VERSION: 0.9.2
+      MDBOOK_LINKCHECK_VERSION: 0.7.7
     steps:
       - uses: actions/checkout@v4
 
@@ -42,16 +43,14 @@ jobs:
         run: |
           cargo binstall --no-confirm --version ${MDBOOK_VERSION} mdbook
           cargo binstall --no-confirm --version ${MDBOOK_KATEX_VERSION} mdbook-katex
+          cargo binstall --no-confirm --version ${MDBOOK_LINKCHECK_VERSION} mdbook-linkcheck
 
       - name: Setup Pages
         id: pages
         uses: actions/configure-pages@v5
 
       - name: Build with mdBook
-        run: |
-          cargo run --bin create_mdbook
-          cp -r assets book/
-          mdbook build
+        run: mdbook build
 
       - name: Upload artifact
         uses: actions/upload-pages-artifact@v3
@@ -64,7 +63,7 @@ jobs:
       name: github-pages
       url: ${{ steps.deployment.outputs.page_url }}
     runs-on: ubuntu-latest
-    needs: build
+    needs: [build]
     steps:
       - name: Deploy to GitHub Pages
         id: deployment

.github/workflows/mdbook-build.yaml

@@ -0,0 +1,32 @@
+name: MDBook Build
+
+on:
+  pull_request:
+    branches: ["main"]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    env:
+      MDBOOK_VERSION: 0.4.43
+      MDBOOK_KATEX_VERSION: 0.9.2
+      MDBOOK_LINKCHECK_VERSION: 0.7.7
+    steps:
+      - uses: actions/checkout@v4
+      
+      - name: Install cargo-binstall
+        uses: cargo-bins/cargo-binstall@main
+        
+      - name: Install rust
+        run: |
+          curl --proto '=https' --tlsv1.2 https://sh.rustup.rs -sSf -y | sh
+          rustup update
+          
+      - name: Install mdbook and plugins
+        run: |
+          cargo binstall --no-confirm --version ${MDBOOK_VERSION} mdbook
+          cargo binstall --no-confirm --version ${MDBOOK_KATEX_VERSION} mdbook-katex
+          cargo binstall --no-confirm --version ${MDBOOK_LINKCHECK_VERSION} mdbook-linkcheck
+          
+      - name: Build mdBook
+        run: mdbook build

Cargo.toml

@@ -9,12 +9,12 @@ version    ="0.1.1"
 exclude    =["CHANGELOG.md", "assets/"]
 
 [dependencies]
-rand          ="0.8"
-itertools     ="0.14"
-hex           ="0.4"
-crypto-bigint ="0.6.0-rc.6"
-regex         ="1.11.1"
-num-traits    ="0.2.19"
+rand         ="0.8"
+itertools    ="0.14"
+hex          ="0.4"
+crypto-bigint="0.6.0-rc.6"
+regex        ="1.11.1"
+num-traits   ="0.2.19"
 
 [dev-dependencies]
 rstest               ="0.24"

README.md

@@ -22,7 +22,7 @@ Ronkathon is a collection of cryptographic primitives implemented in Rust. It is
 - **Fundamental Algebraic Structures**
     - [Group](src/algebra/group/README.md)
     - [Fields and Their Extensions](src/algebra/field/README.md)
-        - [Binary Fields](src/field/binary_towers/README.md)
+        - [Binary Fields](src/algebra/field/binary_towers/README.md)
 - [Curves and Their Pairings](src/curve/README.md)
 - [Polynomials](src/polynomial/mod.rs)
 - [KZG Commitments](src/kzg/README.md)
@@ -82,13 +82,13 @@ In particular, the `math/field.sage` computes roots of unity in the `PlutoField`
 ## Building mdBook
 
 To locally build/serve the [mdBook](https://github.com/rust-lang/mdBook) site, install mdBook and [mdbook-katex](https://github.com/lzanini/mdbook-katex):
-```
+```ignore
 cargo install mdbook
 cargo install mdbook-katex
 ```
 
 To build, run:
-```
+```ignore
 cargo run --bin create_mdbook
 cp -r assets book/
 mdbook build
@@ -98,7 +98,7 @@ If you want to serve locally, run `mdbook serve`.
 
 ## License
 
-Licensed under the Apache License, Version 2.0 ([LICENSE-APACHE](LICENSE-APACHE) or http://www.apache.org/licenses/LICENSE-2.0)
+Licensed under the Apache License, Version 2.0 ([LICENSE-APACHE](./LICENSE) or http://www.apache.org/licenses/LICENSE-2.0)
 
 ## Contributing
 

book.toml

@@ -1,20 +1,41 @@
 [book]
-authors = ["Contributors to Ronkathon"]
-language = "en"
-multilingual = false
-src = "book"
-title = "Ronkathon: Cryptography Educational Foundations"
-description = "Cryptography Educational Foundations"
+authors     =["Contributors to Ronkathon"]
+language    ="en"
+multilingual=false
+src         ="."
+title       ="Ronkathon: Cryptography Educational Foundations"
+description ="Cryptography Educational Foundations"
 
 [build]
-build-dir = "docs"
-use-default-preprocessors = true
-create-missing = true
+build-dir                ="docs"
+use-default-preprocessors=true
+create-missing           =true
 
 [preprocessor.katex]
-after = ["links"]
+after=["links"]
+
+[preprocessor.linkcheck]
+follow-web-links           =true
+traverse-parent-directories=true
+
+# TODO (autoparallel): there's a bunch to fix with this
+# [preprocessor.keeper]
+# command     ="mdbook-keeper"
+# manifest_dir="."
+# externs     =["ronkathon", "rand"]
 
 [output.html]
-default-theme = "dark"
-preferred-dark-theme = "ayu"
-git-repository-url = "https://github.com/pluto/ronkathon"
+default-theme       ="dark"
+preferred-dark-theme="ayu"
+git-repository-url  ="https://github.com/pluto/ronkathon"
+
+[output.html.playground]
+editable=true
+runnable=true
+
+[rust]
+edition="2021"
+
+[[output.html.playground.pre-installed-crates]]
+name   ="rand"
+version="0.8"

src/algebra/field/README.md

@@ -46,7 +46,7 @@ The structs that implement these traits are
 
 ### `PrimeField`
 The `PrimeField` struct is a wrapper around a `usize` by:
-```rust
+```rust,ignore
 pub struct PrimeField<const P: usize> {
     value: usize,
 }
@@ -62,7 +62,7 @@ All of the relevant arithmetic operations for `PrimeField<P>` are implemented in
 
 ### `GaloisField`
 The `GaloisField` struct is a wrapper around a `PrimeField<P>` by:
-```rust
+```rust,ignore
 use ronkathon::algebra::field::prime::PrimeField;
 pub struct GaloisField<const N: usize, const P: usize> {
     value: [PrimeField<P>; N],

src/algebra/group/README.md

@@ -19,7 +19,7 @@ The structs that implement these traits are
 
 ### `MultiplicativePrimeGroup`
 The `MultiplicativePrimeGroup` struct is a wrapper around a `usize` that defines $(Z/nZ)^{*}$ for a prime power $n=p^k$ with binary operation as $\times$:
-```rust
+```rust,ignore
 pub struct MultiplicativePrimeGroup<const P: usize, const K: usize>(usize);
 ```
 

src/bin/create_mdbook.rs

@@ -24,7 +24,7 @@ Outputs parsed output in form of `WireCoeffs` values and coefficients.
 - `coefficients`: coefficient corresponding to each variable.
 
 
-```rust
+```rust,ignore
 use std::collections::HashMap;
 /// Values of wires with coefficients of each wire name
 #[derive(Debug, PartialEq)]
@@ -68,7 +68,7 @@ r2[right input]-->b
 b-->o2[output=l+r]
 ```
 
-```rust
+```rust,ignore
 use ronkathon::algebra::field::prime::PlutoScalarField;
 /// Fan-in 2 Gate representing a constraint in the computation.
 /// Each constraint satisfies PLONK's arithmetic equation: `a(X)QL(X) + b(X)QR(X) + a(X)b(X)QM(X) +
@@ -107,7 +107,7 @@ Converts `WireValues` to required polynomials in PLONK, i.e.
 
 To get selector polynomials from constraints, each constraint is parsed into fan-in 2 arithmetic gates as explained above and wire values are assigned to respective wires in lagrange form.
 
-```rust
+```rust,ignore
 /// `CommonPreprocessedInput` represents circuit related input which is apriori known to `Prover`
 /// and `Verifier` involved in the process.
  use ronkathon::{
@@ -154,8 +154,8 @@ permutation helper creates $\sigma_i$ polynomials for $i = \{1,2,3\}$.
   - for example: x's usage gets shifted 1 to right, new one becomes: `{'x': [(3, RIGHT), (1, LEFT), (2, LEFT), (2, RIGHT)]}`.
   - This ensures that variables `x` is copied from $x_i$ to $x_{i+1}$
 
-```rust
- use ronkathon::compiler::parser::WireCoeffs;
+```rust,ignore
+use ronkathon::compiler::parser::WireCoeffs;
 
 /// `Program` represents constraints used while defining the arithmetic on the inputs
 /// and group order of primitive roots of unity in the field.

src/compiler/README.md

@@ -45,7 +45,7 @@ To generate more round keys out of the original key, we do a series of word rota
 
 For round **i**, if i is a multiple of the length of the key (in words):
 
-```rust
+```rust,ignore
     Self::rotate_word(&mut last);
     word = (u32::from_le_bytes(Self::sub_word(last))
       ^ u32::from_le_bytes(ROUND_CONSTANTS[(i / key_len) - 1]))
@@ -54,13 +54,13 @@ For round **i**, if i is a multiple of the length of the key (in words):
 
 if i + 4 is a multiple of 8:
 
-```rust
+```rust,ignore
     word = Self::sub_word(last)
 ```
 
 The final step is always to XOR previous round's round key with the *(i - key_len)*-th round key:
 
-```rust
+```rust,ignore
       let round_key = expanded_key[i - key_len]
         .iter()
         .zip(last.iter())
@@ -132,8 +132,8 @@ In production-level AES code, fast AES software uses special techniques called t
 
 ## References 
 
-- [FIPS197](fips197)
-- [Serious Cryptography - A Practical Introduction to Modern Cryptography](seriouscrypto)
+- [FIPS197][fips197]
+- [Serious Cryptography - A Practical Introduction to Modern Cryptography][seriouscrypto]
 
 [aes]: https://en.wikipedia.org/wiki/Advanced_Encryption_Standard
 [des]: ../des/README.md