Port of the 0.4.x site-url absolute-links patch to the 0.5 crates/ layout,
toward upstreaming as PR #1802. When output.html.site-url is set, internal
links and assets are emitted as absolute URLs anchored at site-url, so the
book works under a sub-path (e.g. /cdcidao/) regardless of page depth.
- html/tree.rs: fix_link/fix_html_link rewrite ./ content, image and raw-HTML
links to {site_url}...; schemes and fragments untouched
- html_handlebars/hbs_renderer.rs: path_to_root = site_url for normal and index
pages; base_url = site_url only for the toc.html iframe (removed before the
per-chapter clone so it cannot leak)
- html_handlebars/helpers/resources.rs: {{resource}} honors an explicit
path_to_root from data (absolute assets) with stock fallback
- html/print.rs: print page honors site-url; internal cross-refs still fold to
#anchors, non-chapter links keep absolute form
- cmd/serve.rs: --preserve-site-url flag; serve still forces site-url to / for
local preview but logs the override
- tests/testsuite/rendering*: site_url fixture + tests (content, assets, print,
no <base> leak, no-regression without site-url)
- guide: document the serve flag and the renderer behavior
This tries to improve the spacing between section headings in the
sidebar so that they don't blend together. This is particularly a
problem with long headings that word wrap. This just tightens up the
spacing when it wraps, and increases the spacing between the sections.
I still don't 100% like how the distinction between sections can be
difficult to see. My original prototype had other indicators like
bullets, but those ended up not working too well. This might still need
some work in the future.
Fixes https://github.com/rust-lang/mdBook/issues/3085
This fixes an issue where global keypresses were being caught when they
shouldn't when there is a shadow DOM element with focus. This can happen
if the user has included their own extensions. Arguably the extension
should do a stopPropagation, but they don't always do that. I think this
is relatively safe way to approach this.
Fixes https://github.com/rust-lang/mdBook/issues/2507
This fixes an issue where pressing `?` inside the ACE editor was opening
the help popup. The solution here is to ensure that the global keypress
handler works the same as the one used in the search handler.
Fortunately other keypresses like left and right were working OK because
ACE was doing something like stopPropagation (I'm not sure exactly).
Fixes https://github.com/rust-lang/mdBook/issues/3064
When an invalid Font Awesome icon name is used (e.g. in git-repository-icon),
the error message now includes the icon name, the type that was searched,
valid prefix options (fas/fab/far), and a link to the FontAwesome icon gallery.
Before: Missing font github
After: Unknown Font Awesome icon `github` for type `regular`. Hint: check
the icon name and prefix (fas (solid), fab (brands), or far (regular))
at https://fontawesome.com/v6/search?m=freeFixes#3023
Use child combinator (>) instead of descendant selector for
blockquote-tag-title color rules. Without this, a nested admonition
inherits the title color of its parent admonition instead of using
its own type's color.
Added nested admonition test case (important > note) to the existing
admonition test suite.
Fixes#3032
This fixes an issue where the sidebar was scrolling incorrectly when
clicking on chapters when a heading nav is currently in view. The
problem was that it was storing the scrollTop of the sidebar, but it was
not considering that when navigating to another chapter that the heading
nav of the previous chapter would disappear.
The solution is to keep of an offset instead so that it can make sure
that the vertical position of the clicked chapter stays in the same
relative position when the new page loads.
Fixes https://github.com/rust-lang/mdBook/issues/2967
Due to a change in tracing-subscriber where it escapes ANSI codes, the
output from rustdoc was changed to be escaped instead of colored. This
fixes the issue by just printing to the console directly.
This does not have a test because it is difficult to emulate a terminal
in the testsuite, and I don't feel like adding color overrides at the
moment.
Ref:
- https://github.com/rust-lang/mdBook/pull/2829 -- Switched to tracing
- https://github.com/advisories/GHSA-xwfj-jgwm-7wp5 -- CVE-2025-58160
- https://github.com/tokio-rs/tracing/issues/3378 -- Discussion of
supporting color codes.
Eventually mdbook's primary output should migrate away from using log
messages, and instead use a structured console system. However, that's a
ways off.
This fixes a problem where custom preprocessors were not being
registered when running tests. This was caused by the test function
rebuilding the preprocessor map.
This removes the code that was rebuilding the preprocessors and removing
the IndexPreprocessor when running tests. Skipping IndexPreprocessor was
added back in https://github.com/rust-lang/mdBook/pull/741 to fix
https://github.com/rust-lang/mdBook/issues/724 which was caused by
https://github.com/rust-lang/mdBook/pull/685 which added the
IndexPreprocessor.
Additionally, https://github.com/rust-lang/mdBook/pull/1986 added
running *all* preprocessors.
The IndexPreprocessor was removed because in the past the code was
testing against the source directly, and the path from `chapter.path` is
the converted `index.md` file, and that filename does not exist in the
source. This isn't a problem anymore because due to
https://github.com/rust-lang/mdBook/pull/891 it is not reading from the
`src` directory.
Note that this results in a minor change where the chapter path changes
from `README.md` to `index.md` in the output and the `--chapter` option.
I think I'm ok with that change, though it would be easy to switch it
back if that's an issue.
This fixes an issue where when a heading goes from a larger to a smaller
level, it was going back too far so that subsequent headings would be at
a lower level than they should have been.
Fixes https://github.com/rust-lang/mdBook/issues/2944
This changes it so that top-level environment variable config keys like
`MDBOOK_FOO` are ignored instead of generating an error. It's just too
inconvenient since it is common for users to set environment variables
like `MDBOOK_VERSION` or whatever for their own scripts.
In version 6, Font Awesome changed so that the class names look like
`fa-solid fa-cat` instead of `fas fa-cat`. This updates so that it
handles this new style.
This adds several changes to how environment variables are handled to
more closely align with how configs are handled, and to fix an issue
with replacing entire tables. The changes are:
- Top-level tables like `MDBOOK_BOOK` now *replace* the contents of the
`book` table instead of merging it. This adds consistency with how all
the other environment objects work.
- Fixed allowing top-level replacement of `MDBOOK_BOOK` and
`MDBOOK_OUTPUT`. This was inadvertently recently broken.
- Added ability to replace top-level `MDBOOK_RUST`. I don't recall why
that wasn't included.
- Reject invalid keys like `MDBOOK_FOO`.
- Reject unknown keys, like `MDBOOK_BOOK='{"xyz": 123}'`
- Reject invalid types, like `MDBOOK_BOOK='{"title": 123}'`
This fixes an issue where it was panicking due to an unbalanced HTML tag
when exiting a markdown element. The problem was that the tag stack was
left non-empty when processing was finished due to `end_tag` being out
of sync with the pulldown-cmark event tags.
There really should be better validation that the stack is in sync and
balanced, but this should address the main culprit of the interplay of
raw HTML tags and pulldown-cmark events.
This changes the internal error message to a warning to let the user
know that the HTML tags are unbalanced. In the future this will be a
denyable lint.
This is a very primitive approach of just ignoring the end tag. Ideally
it should recover using the standard HTML parsing algorithm, since there
is a chance that there will be a cascade of errors under certain
unbalanced situations.
This checks for any unclosed elements when processing is finished. This
is intended to detect invalid HTML in the source, or bugs in the tree
builder. Raw HTML elements generate a warning (which in the future will
be a configurable lint). All other sync errors are internal errors as
they are not expected, and it would be helpful to know if they ever
happen.
This switches from ASCII lowercase to Unicode lowercase when generating
heading IDs. This brings mdbook more in line with other tools and sites
when they generate heading IDs. The generation still isn't 100% the same
as other tools and sites, but it is usually the same in most cases.
Closes https://github.com/rust-lang/mdBook/issues/1059
With the migration to Font Awesome 6, I'm running into books where the
icon names are missing or have changed. This adds a warning to help
identify those situations.
This fixes links on the print page that go to an internal destination
that is not a chapter. The path would have the wrong relative
destination, and would be broken. The logic for detecting this was
incorrectly only checking if a link went outside the book, or didn't
have an html extension. This doesn't work for links to HTML files that
are inside the book, but not one of the chapters.
This changes it so that header and `<dt>` tags manually written as HTML
are not modified (no anchor, no id, etc.). This is to avoid mangling any
HTML that the user explicitly crafted.
I'm not sure what the fallout from the headers might be, since I'm not
100% sure there aren't uses where the user wanted mdbook to modify
manual HTML. However, I don't see any in rust-lang's use.
This adds the method `contains_key` to assist with detecting if a key is
set in the config. There have been a few scenarios where I have needed
this when upgrading to 0.5. For now this only supports the `output` and
`preprocessor`. Checking the presence in the other tables isn't easy,
but could potentially be added if needed.
