Description
Problem
Note
The issue described here may be considered invalid usage of mdBook. I chose to make an issue about it because:
- It is a regression.
- I wish to document this problem for other people who happen to stumble upon it.
- 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
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