Skip to content

Upgrade gb-asm-tutorial to use mdbook 0.5#172

Open
mtthgn wants to merge 2 commits into
gbdev:masterfrom
mtthgn:mdbook-upgrade
Open

Upgrade gb-asm-tutorial to use mdbook 0.5#172
mtthgn wants to merge 2 commits into
gbdev:masterfrom
mtthgn:mdbook-upgrade

Conversation

@mtthgn
Copy link
Copy Markdown

@mtthgn mtthgn commented Mar 27, 2026

This PR makes a number of changes, all necessary to address breaking changes introduced in mdBook 0.5:

  1. It makes the preproc and i18n-helpers crates now depend on mdbook-preprocessor. As part of 0.5 the mdbook crate was broken down into components.
  2. It makes the renderer crate now depend on mdbook-renderer and mdbook-html. This one is mostly just updating use names.
  3. It switches the {{#previous}} and {{#next}} handlebars statements to the new syntax: Replace navigation helpers with objects rust-lang/mdBook#2794
  4. It updates github workflows to install the appropriate versions of mdbook related crates.

As part of this update, the theme/index.hbs had to be updated to work with some syntax changes made for mdbook 0.5. The style looked pretty off in my browser (no header nav, sidebar doesn't adjust width, content alignment at certain breakpoints is off), so I would appreciate someone double checking on this front. I'm not sure if this is akin to how pandocs need to be served differently than mdbook serve, or if something actually broke. Looking at the currently deployed docs, the reason for a custom theme is not immediately apparent to me.

Edit by @avivace:
Note: The PR is still in draft pending restoration of the custom theme's localization-related customizations, which appear to have broken as part of the theme/index.hbs update.

Closes #134

@avivace avivace marked this pull request as draft March 30, 2026 12:37
@avivace avivace self-requested a review March 30, 2026 12:37
@avivace avivace requested a review from a team April 16, 2026 17:30
@mtthgn mtthgn marked this pull request as ready for review June 6, 2026 02:51
This commit updates the various unpublished crates in the repo to be set
up according to the new requirements imposed by mdbook 0.5. In addition,
it updates the build and deploy workflow to account for these changes as
well.

As part of this update, the theme/index.hbs had to be updated to work
with some syntax changes made for mdbook 0.5. The biggest change was the
update to "font-awesome", which required changes to where were having
the font awesome icons show up on web pages as well.
@mtthgn
Copy link
Copy Markdown
Author

mtthgn commented Jun 6, 2026

@avivace the additional-css config for ouput.html.print doesn't seem to be an option as of mdbook 0.5. I added the print css to the output.html section, but printing looked very off. I might need some assistance understanding what the goals were for the print css, and from there we can figure out how to achieve that on the current version of mdbook

@mtthgn
Copy link
Copy Markdown
Author

mtthgn commented Jun 6, 2026

I read a bit more through #193, and I think it'd be helpful if @OnStarPrograms / @avivace could further confirm the intention the CSS in that PR.

Is the goal to display the contents of all the "answers" throughout the tutorial, while also hiding the "Answer (click me)" text? If so, the current implementation only does that for <detail> tags that were opened before clicking the print button. You can confirm this on the currently deployed site. Is that the desired behavior, or is the intention to have all of the answers opened and present in the printed version?

@avivace
Copy link
Copy Markdown
Member

avivace commented Jun 6, 2026

@mtthgn On the print version everything should be 'expanded', I believe that was the idea of that PR (and the correct rationale, imo). So displaying all questions and all answers

There was a previous attempt at ensuring that answers were present on
the page when printing. This commit brings that functionality back, and
ensure that details are open by taking advantage of the `beforeprint`
event.
@mtthgn
Copy link
Copy Markdown
Author

mtthgn commented Jun 6, 2026

@avivace thanks for the clarification! I've simplified the CSS and added a bit of javascript to ensure that always occurs. Unfortunately there's no way to guarantee they're in an open state for printing without javascript at the moment.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Upgrade to mdbook 0.5.x

2 participants