Skip to content

Building documentation using recent versions of mdBook is slightly broken #840

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.

Sign up for GitHub

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

Jump to bottom
Open
meator opened this issue May 4, 2025 · 1 comment · May be fixed by #841
Open

Building documentation using recent versions of mdBook is slightly broken #840

meator opened this issue May 4, 2025 · 1 comment · May be fixed by #841

Comments

@meator
Copy link

meator commented May 4, 2025 •
edited
Loading

This has been discussed in #voidlinux. Here is the original screen capture I posted there which showcases some of the problems:

output.mp4

Trying to build void-docs with a recent version of mdBook (including v0.4.43 which is the version currently packaged in void-packages) will lead to the following quirks not present in https://docs.voidlinux.org/:

  1. Sidebar's links become broken (see The toc helper handles relative paths strangely rust-lang/mdBook#2685) (this is probably the most severe problem affecting the usability of the documentation)

  2. The selected chapter is not highlighted like in https://docs.voidlinux.org/:

    sidebar with a selected chapter

  3. There are probably more issues (more minor or specific ones)

Local builds and the void-docs official package are affected.

Cause

This is caused by void-docs' custom theme which completely overrides mdBook's default sidebar logic. Void's substitute code relies on mdBook's toc helper, which endured a breaking change in newer versions of mdBook: rust-lang/mdBook#2685

Relevant mdBook versions

void-docs' theme resides in src/theme/. Most of it was overhauled by 7281ced. The commit description indicates that these files were made by taking mdBook's default theme files and modifying them to Void's needs.

The void-packages packaged version of mdBook was v0.4.14 at the time of making that commit, so mdBook v0.4.14 default theme files were most likely used as base for void-docs theme.

The Void infrastructure generates https://docs.voidlinux.org/ from the ghcr.io/void-linux/infra-mdbook:20231023R1 container (which is created from here using these files). The ghcr.io/void-linux/infra-mdbook:20231023R1 container includes mdBook v0.4.35, which doesn't suffer from the problem described in rust-lang/mdBook#2685

Void's changes to mdBook's default theme

Here is a cleaned up diff (I had to reindent void-docs' theme) between mdBook v0.4.14 default theme files and void-docs' current theme files: void-docs-theme-changes.patch.txt

Possible solutions

The most straight forward solution to the sidebar problem would be to somehow convince the relative links generated in here by {{#toc}}{{/toc}} to be relative to path_to_root or to something similar. I personally do not know how to do that or whether it is possible.

Another solution would be to switch to mdBook's default sidebar logic. This would lead to less custom theme logic in void-docs. This would result in the following behavior changes:

  1. The sidebar would become scrollable, it would no longer be static.

    Most of the other features mentioned here can be relatively easily removed, but preserving the static nature of the sidebar would require heavy modification to mdBook's default sidebar logic (I assume, I haven't tried implementing it). In recent enough versions of mdBook, the sidebar is handled by

    <!DOCTYPE HTML>
<html lang="{{ language }}" class="{{ default_theme }} sidebar-visible" dir="{{ text_direction }}">
    <head>
        <!-- ... -->

        <!-- Start loading toc.js asap -->
        <script src="{{ resource "toc.js" }}"></script>
    </head>
    <body>
    <div id="body-container">
        <!-- ... -->

        <nav id="sidebar" class="sidebar" aria-label="Table of contents">
            <!-- populated by js -->
            <mdbook-sidebar-scrollbox class="sidebar-scrollbox"></mdbook-sidebar-scrollbox>
            <noscript>
                <iframe class="sidebar-iframe-outer" src="{{ path_to_root }}toc.html"></iframe>
            </noscript>
            <div id="sidebar-resize-handle" class="sidebar-resize-handle">
                <div class="sidebar-resize-indicator"></div>
            </div>
        </nav>

        <!-- ... -->
    </div>
    </body>
</html>

    A JS version is managed by toc.js and a non-JS one is built by mdBook and outputted into toc.html.

    The toc.js file would likely have to be modified to preserve the original UI. This file is not one of the files overrideable by mdBook theme, so a custom one would have to be created, modified and shipped alongside the (unused) toc.js.

  2. Collapse/uncollapse animations would be added.

    These are easy to patch out.

  3. The selected chapter would also have to be remodified.

  4. The UI on mobile devices would presumably also be affected (I haven't tested it)

The non-JS toc.html file mentioned above might be usable as a replacement to {{#toc}}{{/toc}} if void-docs wishes to steer away from mdBook's default sidebar logic.

Things to consider after solving this issue

The ghcr.io/void-linux/infra-mdbook container will have to be updated.

Once that's done, this line will have to be updated to point to the new container. I am not closely familiar with Void's infrastructure, more steps may be necessary.

The void-docs package should be revbumped once this issue gets resolved.
@classabbyamp
Copy link
Member

I'm fine with it becoming scrollable as long as we keep the general visual look (green background on active item)

meator added a commit to meator/void-docs that referenced this issue May 4, 2025
@meator
Reapply void-docs theme changes
4a18180 
The contents of this commit should closely follow the patch linked
in the "Void's changes to mdBook's default theme" section of
void-linux#840

Some things had to be adapted to the newer v0.4.43 base. Some changes
include:

- The warning and kbd elements were left intact in general.css
- -webkit-print-color-adjust was set in the pre element to match
  void-docs' old theme even though the new theme's code element no
  longer includes it in print.css
- Default code fonts were left as-is (these weren't present here in the
  void-docs original theme) in variables.css
- Warning border was left as-is (this element wasn't present in older
  versions of mdBook) in variables.css
- copy-button-filter variables were left as-is in variables.css
- variables.css no doesn't include special prefers-color-scheme: dark
  noscript logic (void-docs original theme didn't have it)
@meator meator linked a pull request May 4, 2025 that will close this issue
Draft
meator added a commit to meator/void-docs that referenced this issue May 4, 2025
@meator
Reapply void-docs theme changes
2431bf0 
The contents of this commit should closely follow the patch linked
in the "Void's changes to mdBook's default theme" section of
void-linux#840

Some things had to be adapted to the newer v0.4.43 base. Some changes
include:

- The warning and kbd elements were left intact in general.css
- -webkit-print-color-adjust was set in the pre element to match
  void-docs' old theme even though the new theme's code element no
  longer includes it in print.css
- Default code fonts were left as-is (these weren't present here in the
  void-docs original theme) in variables.css
- Warning border was left as-is (this element wasn't present in older
  versions of mdBook) in variables.css
- copy-button-filter variables were left as-is in variables.css
- variables.css no doesn't include special prefers-color-scheme: dark
  noscript logic (void-docs original theme didn't have it)
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
None yet
Projects
None yet
Milestone
No milestone
Development

Successfully merging a pull request may close this issue.

Update mdbook meator/void-docs
2 participants
@classabbyamp @meator