Update mdBook - #306
Update mdBook#306
Conversation
This replaces the pagetoc sidebar hack that I put together with the native `sidebar-header-nav` feature in mdBook 0.5. See: https://rust-lang.github.io/mdBook/format/configuration/renderers.html#html-renderer-options The `mdbook-tera` templates were giving me grief in algorithms.md. Using a `*` or `-` bullet inside a raw template block causes `tera` to discard everything after the block. Indentation works around the problem. I don't know why! `mdbook-bib` changed their renderer and CSS, which looks nicer. I made some minor patches to the new CSS that desaturates the links slightly, matching the custom CSS for all other links. Removed a couple of things from book.toml that are no longer needed. Added an admonition to the index page, replacing our naive attempt at a warning with one that properly stands out. `mdbook-mermaid` and `mdbook-tera` are pinned to git because they have some unreleased patches that we need.
This flag builds the preprocessors with an older version of the `mdbook-preprocessor` crate, which causes mdBook to print a warning. It's harmless (no changes to that crate between the versions - they stay in lock-step with the main `mdbook` crate). But removing this flag also means picking up vulnerability fixes. It also means exposing ourselves to supply-chain attacks. Can't win all the time!
|
Looks nice! Only thing I noticed so far--clicking on a chapter name in the sidebar twice does not close the expanded sublist. For instance, click on "3. Terminology" twice. Not sure if that's possible or not. |
I didn't notice this at all! The `mdbook` directory no longer exists. 😂
|
I don't see a way to collapse the Didn't find an upstream feature request for it, so I created one: rust-lang/mdBook#3054 |
|
@parasyte , any ideas if we can move forward with these changes? I'd hate to lose the improvements you made. |
|
It needs the plugins patched with the commit IDs shown in the GitHub actions YAML. Neither of them are merged upstream. You can move forward with this in its present state. It might just be permanently on third party forks for the dependencies. And there is no guarantee those forks will stay around. Forking them into the dcdpr account would be wise, if you want to go that route. It would ensure the builds are always reproducible. |
|
I created issues on both upstream issue trackers to hopefully kickstart them into unblocking this PR. There's a good chance that |
mdbook-mermaid 0.17.1 contains the patch from the git pin, so the workflow installs that release. mdbook-tera has no release for mdBook 0.5, so the workflow installs the patched commit from a fork in the jintekc account. The patched commit is on the master branch of that fork, so it stays available if the owner deletes the stevecheckoway fork. The README install commands use the same sources.
|
@parasyte I'm completing this PR per your above guidance. I merged |
danpape
left a comment
danpape
left a comment
There was a problem hiding this comment.
Looks nice on my machine!
|
I wonder if anything needs to be edited in this repo's Actions? (I don't know much about that was put together) |
|
yeah, I was relying on a review from @parasyte on the Actions portion since I'm also less familiar. Since he originated the PR, I can't list him as a reviewer. |
|
Yeah, CI looks good: https://github.com/dcdpr/did-btcr2/actions/runs/35890343547/job/107280922770?pr=306 I also did a spot check over all rendered pages on the latest commit. The print preview looks good, too. |
3 participants
This is a Work-In-Progress. Depends on installing some preprocessors from git for unpublished fixes. Looks nice, though!
This replaces the pagetoc sidebar hack that I put together with the native
sidebar-header-navfeature in mdBook 0.5.See: https://rust-lang.github.io/mdBook/format/configuration/renderers.html#html-renderer-options
The
mdbook-teratemplates were giving me grief in algorithms.md. Using a*or-bullet inside a raw template block causesterato discard everything after the block. Indentation works around the problem. I don't know why!mdbook-bibchanged their renderer and CSS, which looks nicer. I made some minor patches to the new CSS that desaturates the links slightly, matching the custom CSS for all other links.Removed a couple of things from book.toml that are no longer needed.
Added an admonition to the index page, replacing our naive attempt at a warning with one that properly stands out.
mdbook-mermaidandmdbook-teraare pinned to git because they have some unreleased patches that we need.