Mdbook-pagetoc Fails: Fixes & Compatibility With 0.5

by Alex Johnson 53 views

It appears there's a compatibility issue between mdbook-pagetoc and the newer mdbook version 0.5. This article delves into the problem, its causes, and potential solutions, drawing from a real-world scenario and community discussions.

The Problem: mdbook-pagetoc and mdbook 0.5 Incompatibility

Users have reported that mdbook-pagetoc fails when used with mdbook version 0.5. This issue stems from internal API changes within mdbook that have rendered older extensions, like mdbook-pagetoc, incompatible. The error manifests during the build process, preventing the table of contents from being generated correctly and halting the book's compilation.

Real-World Reproducer: A Case Study

To illustrate the problem, consider a scenario involving a Containerfile used to build an mdbook project. The following Containerfile setup demonstrates how the issue can be reproduced:

FROM rust:latest

# Copied over from the rust base image, this is not inherited
ENV RUSTUP_HOME=/usr/local/rustup \
    CARGO_HOME=/usr/local/cargo \
    PATH=/usr/local/cargo/bin:$PATH

# Install packages
RUN cargo install mdbook mdbook-pagetoc && \
    mdbook --version

COPY . /srv/mdbook

RUN mdbook build /srv/mdbook

This Containerfile sets up a Rust environment, installs mdbook and mdbook-pagetoc, and then attempts to build a book. The source repository, in this case, is located at https://gitlab.torproject.org/tpo/web/container-images within the mdbook subdirectory. To isolate the issue, other extensions in the configuration file are disabled. The relevant configuration snippet looks like this:

[book]
authors = ["Antoine Beaupré"]
language = "en"
src = "src"
title = "test book"

[preprocessor.pagetoc]

[output.html]
additional-css = ["theme/pagetoc.css"]
additional-js  = ["theme/pagetoc.js"]

During the build process, the following error typically occurs:

STEP 5/5: RUN mdbook build /srv/mdbook
 INFO Book building has started
Unable to parse the input
ERROR The "pagetoc" preprocessor exited unsuccessfully with exit status: 1 status
Error: building at STEP "RUN mdbook build /srv/mdbook": while running runtime: exit status 101

This error confirms that mdbook-pagetoc fails to function correctly with mdbook 0.5, necessitating a temporary disabling of the extension to ensure successful builds.

Root Cause: Internal API Changes in mdbook 0.5

The underlying cause of this failure lies in the internal API changes introduced in mdbook version 0.5. These changes have broken compatibility with extensions like mdbook-pagetoc that were designed for earlier versions. This situation isn't unique to mdbook-pagetoc; other extensions have also reported similar issues. This highlights the challenge of maintaining compatibility when core software undergoes significant updates. This incompatibility issue means that developers and content creators need to be aware of the versions of mdbook and its extensions to ensure their projects build correctly.

Identifying the Issue

Identifying the problem often involves observing the build output and error messages. The key indicators of an mdbook-pagetoc failure include:

  • An error message indicating that the