[docs,bazel] Create site theme by patching mdBook instead of hard-coding. #25817
Labels
Component:Doc
Documentation issue
Component:Tooling
Issues related to tooling, e.g. tools/scripts for doc, code generation (docgen, reggen), CSR
Description
Currently, we pin a specific version of mdBook (and patch it) using
rules_rust
: https://github.com/lowRISC/opentitan/blob/7780c6bf8aed527c1284c74e22d101b8bf256292/third_party/rust/Cargo.toml#L111C23-L111C29.We also override the handlebar rendering template and CSS, and add some additional custom JS. However, this is done by directly including modified theming files within our repository, rather than patching the existing mdBook files, despite the majority of the changes being minimal and more suited to several small patches.
This makes updating
mdBook
more difficult, as it means that we have to e.g. manuallygit diff
all of the files to find out which changes have been made, and then manually apply those changes to a copy of the latest theme files frommdBook
. This process is also more prone to manual error. Converting our existing changes to patches would make maintenance of documentation much easier - allowing us to update mdBook to pull in the latest fixes/features and identify our diffs easier. We previously had several outdated dependencies reported bycargo audit
caused by usage of an oldmdBook
, which introduced potential vulnerabilities (see #25795).Fixing this might be easier if we run mdBook through Bazel in the future.
The text was updated successfully, but these errors were encountered: