Skip to content

The toc helper handles relative paths strangely #2685

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 · 0 comments
Open

The toc helper handles relative paths strangely #2685

meator opened this issue May 4, 2025 · 0 comments
Labels
C-bug Category: A bug, incorrect or unintended behavior

Comments

@meator
Copy link

meator commented May 4, 2025 •
edited
Loading

Problem

Note

The issue described here may be considered invalid usage of mdBook. I chose to make an issue about it because:

  1. It is a regression.
  2. I wish to document this problem for other people who happen to stumble upon it.
  3. I wish to notify the maintainers that there is at least one project (void-linux/void-docs) negatively affected by this change.

The {{#toc}}{{/toc}} toc helper uses relative paths to refer to each chapter. Such links do not work when they aren't in the top level directory.

This is a regression, because mdBook v0.4.35<= (I haven't bisected the exact version) used to handle this gracefully.

Steps

The following shell script creates a default mdBook which uses {{#toc}}{{/toc}} to handle the sidebar.

#!/bin/sh

set -e -u -f

if ! type patch > /dev/null; then
  echo "The 'patch' program is required!" >&2
  exit 1
fi

if [ $# -ne 1 ]; then
  echo "Usage: $0 path_to_mdbook_directory_to_be_created" >&2
  exit 1
fi

dir="$1"

if [ -e "$dir" ]; then
  echo "Directory '$dir' already exists!" >&2
  exit 1
fi

#
# Generate the book with the theme/ directory included
#

mdbook init --theme --title Title --ignore none "$dir" || exit 1
# Chdir into it
cd "$dir" || exit 1

[ -f book.toml ] || exit 1

# Make mdBook use the default theme (which is modified below).
cat >> book.toml <<EOF

[output.html]
theme = "theme"
EOF

patch -p1 <<EOF
--- a/theme/index.hbs
+++ b/theme/index.hbs
@@ -59,8 +59,6 @@
             const default_light_theme = "{{ default_theme }}";
             const default_dark_theme = "{{ preferred_dark_theme }}";
         </script>
-        <!-- Start loading toc.js asap -->
-        <script src="{{ resource "toc.js" }}"></script>
     </head>
     <body>
     <div id="body-container">
@@ -110,14 +108,7 @@
         </script>
 
         <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>
+            {{#toc}}{{/toc}}
         </nav>
 
         <div id="page-wrapper" class="page-wrapper">
EOF

touch src/chapter_2.md
touch src/chapter_3.md
mkdir src/subchapter
touch src/subchapter/subchapter.md
touch src/subchapter/subchapter_1.md
touch src/subchapter/subchapter_2.md

cat > src/SUMMARY.md <<EOF
# Summary

- [Chapter 1](./chapter_1.md)
- [Chapter 2](./chapter_2.md)
- [Chapter 3](./chapter_3.md)
- [Subchapter](./subchapter/subchapter.md)
  - [Subchapter 1](./subchapter/subchapter_1.md)
  - [Subchapter 2](./subchapter/subchapter_2.md)
EOF

Image

If you click on any of the "Subchapter" chapters, you will cycle between the correct chapter (which loads because you start the website from the top-level directory from which relative links are valid) and 404 (if you are not in the top-level directory and you try to use any links in {{#toc}}{{/toc}}).

Possible Solution(s)

Revert to the old behavior. If that isn't feasible, at least mark this breaking change in the changelog.

Notes

mdBook version v0.4.14>= used to use {{#toc}}{{/toc}} to generate the sidebar, so it had to handle subdirectories and relative links gracefully.

mdBook version v0.4.35<= switched to toc.js/toc.html mechanism which replaced {{#toc}}{{/toc}}. {{#toc}}{{/toc}} still handled subdirectories and relative links well (like previous versions).

Newer versions (I have tested v0.4.43 and v0.4.48) suffer from the issue described here (they always use relative links relative to top-level directory even in subdirectories).

Version

v0.4.48
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
C-bug Category: A bug, incorrect or unintended behavior
Projects
None yet
Milestone
No milestone
Development

No branches or pull requests
1 participant
@meator