Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[docs,bazel] Create site theme by patching mdBook instead of hard-coding. #25817

Open
AlexJones0 opened this issue Jan 8, 2025 · 0 comments
Open
Labels
Component:Doc Documentation issue Component:Tooling Issues related to tooling, e.g. tools/scripts for doc, code generation (docgen, reggen), CSR

Comments

@AlexJones0
Copy link
Contributor

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. manually git 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 from mdBook. 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 by cargo audit caused by usage of an old mdBook, which introduced potential vulnerabilities (see #25795).

Fixing this might be easier if we run mdBook through Bazel in the future.

@AlexJones0 AlexJones0 added Component:Doc Documentation issue Component:Tooling Issues related to tooling, e.g. tools/scripts for doc, code generation (docgen, reggen), CSR labels Jan 8, 2025
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
Component:Doc Documentation issue Component:Tooling Issues related to tooling, e.g. tools/scripts for doc, code generation (docgen, reggen), CSR
Projects
None yet
Development

No branches or pull requests

1 participant