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
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
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 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 fixes an issue when folding is enabled. The folding was not
properly hiding the sub-chapters because it was assuming it could hide
the next list element. However, the heading nav was the next list
element, so the remaining chapters remained visible.
The solution required some deeper changes to how the chapters were
organized in the sidebar. Instead of nested chapters being a list
element *sibling*, the nested chapter's `ol` is now a *child* of its
parent chapter. This makes it much easier to just hide everything
without regard of the exact sibling order.
This required wrapping the chapter title and the toggle chevron inside a
span so that the flex layout could be localized to just those elements,
and allow the following `ol` elements to lay out regularly.
Closes https://github.com/rust-lang/mdBook/issues/2880
This moves the code for copying the theme to the theme directory to the
Theme type so that the code lives closer to the data definition. This
also then reduces the public API surface of the Theme to give a little
more flexibility for updating it in the future.
This does a little cleanup around the usage of filesystem functions:
- Add `mdbook_core::utils::fs::read_to_string` as a wrapper around
`std::fs::read_to_string` to provide better error messages. Use
this wherever a file is read.
- Add `mdbook_core::utils::fs::create_dir_all` as a wrapper around
`std::fs::create_dir_all` to provide better error messages. Use
this wherever a file is read.
- Replace `mdbook_core::utils::fs::write_file` with `write` to mirror
the `std::fs::write` API.
- Remove `mdbook_core::utils::fs::create_file`. It was generally not
used anymore.
- Scrub the usage of `std::fs` to use the new wrappers. This doesn't
remove it 100%, but it is now significantly reduced.
This function was essentially only operating on data from HtmlConfig. It
wasn't really a "filesystem" function. So this moves it to be more
logically associated with the data it works on.
This enables the admonitions support from pulldown-cmark. This includes
a config option in case it causes problems with existing books.
I would like to make this extensible in the future, though I'm not sure
what that would look like. There's also some concerns with how this will
affect translations like mdbook-i18n-helpers, which we may need to work
out in a different way.
Closes https://github.com/rust-lang/mdBook/issues/2771
This enables the definition lists support from pulldown-cmark.
This includes a config option in case it causes problems with existing
books.
Closes https://github.com/rust-lang/mdBook/issues/2770
This fixes a collision with the ID generation where it a previous entry
could generate a unique ID like "foo-1", but then a header with the text
"Foo 1" would collide with it. This fixes it so that when generating the
ID for "Foo 1", it will loop unit it finds an ID that doesn't collide
(in this case, `foo-1-1`).
This fixes a small mistake where the "raw" status wasn't being reset
once exiting the script or style tags. That means any text nodes that
followed would be misinterpreted as being raw.
This rewrites the HTML rendering pipeline to use a tree data structure,
and implements a custom HTML serializer. The intent is to make it easier
to make changes and to manipulate the output. This should make some
future changes much easier.
This is a large change, but I'll try to briefly summarize what's
changing:
- All of the HTML rendering support has been moved out of
mdbook-markdown into mdbook-html. For now, all of the API surface is
private, though we may consider ways to safely expose it in the
future.
- Instead of using pulldown-cmark's html serializer, this takes the
pulldown-cmark events and translates them into a tree data structure
(using the ego-tree crate to define the tree). See `tree.rs`.
- HTML in the markdown document is parsed using html5ever, and then
lives inside the same tree data structure. See `tokenizer.rs`.
- Transformations are then applied to the tree data structure. For
example, adding header links or hiding code lines.
- Serialization is a simple process of writing out the nodes to a
string. See `serialize.rs`.
- The search indexer works on the tree structure instead of re-rendering
every chapter twice. See `html_handlebars/search.rs`.
- The print page now takes a very different approach of taking the
same tree structure built for rendering the chapters, and applies
transformations to it. This avoid re-parsing everything again. See
`print.rs`.
- I changed the linking behavior so that links on the print page
link to items on the print page instead of outside the print page.
- There are a variety of small changes to how it serializes as can be
seen in the changes to the tests. Some highlights:
- Code blocks no longer have a second layer of `<pre>` tags wrapping
it.
- Fixed a minor issue where a rust code block with a specific
edition was having the wrong classes when there was a default
edition.
- Drops the ammonia dependency, which significantly reduces the number
of dependencies. It was only being used for a very minor task, and
we can handle it much more easily now.
- Drops `pretty_assertions`, they are no longer used (mostly being
migrated to the testsuite).
There's obviously a lot of risk trying to parse everything to such a low
level, but I think the benefits are worth it. Also, the API isn't super
ergonomic compared to say javascript (there are no selectors), but it
works well enough so far.
I have not run this through rigorous benchmarking, but it does have a
very noticeable performance improvement, especially in a debug build.
I expect in the future that we'll want to expose some kind of
integration with extensions so they have access to this tree structure
(or some kind of tree structure).
Closes https://github.com/rust-lang/mdBook/issues/1736
This changes partition_source so that instead of allocating new strings,
it just returns slices into the original string. It probably doesn't
make a big difference perf-wise, but I felt more comfortable with this,
and also felt it was a little easier to understand exactly what it was
doing.
This is generally equivalent except for the possibility of not having a
newline at the end. In practice that doesn't matter because markdown
code blocks always have a newline. However, to be defensive, the caller
will check for this.
This adds the `ToUrlPath` helper trait to convert a Path to a path
suitable for use in HTML (replacing `normalize_path`).
This also fixes a minor bug where on Windows the next/prev links were
using a double forward slash. I don't think this is possible, since
chapter links are derived from the summary, but I'm noting just in case.
It's also not too much of an issue since double slashes are normally
just treated as a single.
This adds the `Book::chapters` iterator (and `for_each_chapter_mut`) to
iterate over non-draft chapters. This is a common pattern I keep
encountering, and I figure it might simplify things. It runs a little
risk that callers may not be properly handling every item type, but I
think it should be ok.
This switches to using the tracing crate instead of log. Tracing
provides a lot of nice features which we can take advantage of moving
forward.
This also adjusts the output fairly significantly. This includes:
- Switched the environment variable from RUST_LOG to MDBOOK_LOG.
- Dropped the timestamp. I experimented with various different time
displays, but ultimately decided to omit it for now. I don't think
I've ever found it to be useful, and it takes up a very significant
amount of space. It could potentially be useful for basic profiling,
but I think there are other, better mechanisms for that. We could
consider leveraging tracing itself for doing some basic profiling
(like using something like tracing-chrome).
- Dropped the target unless MDBOOK_LOG is set. The target tends to be
pretty noisy, and doesn't really convey much information unless you
are debugging or otherwise trying to adjust the log output.
- Added color.
- Slightly reworked the way the error cause trace is displayed.
- Slightly changed the way html5ever filtering is done, as well as add
handlebars to the list since they both are very noisy. You can
override this now by explicitly listing them as targets.
I still expect that mdbook will eventually change how it displays things
to the console, possibly switching away from tracing and printing things
itself. However, that is a larger project for the future.
This removes the `non_exhaustive` attribute from the `Book` and its
inner types `BookItem` and `Chapter`. These were added in
https://github.com/rust-lang/mdBook/pull/2779. After thinking about it
more, I realized that these types cannot be extended in a
semver-compatible way, so I am fine with allowing them be exhaustive.
The problem is that with CmdPreprocessor, the `Book` will be
re-serialized by a preprocessor, which could potentially be on an older
version. Attempting to add any new fields/variants means that either the
deserialization will fail, or the new fields will be stripped by the
preprocessor.
These could potentially be structured such that they have a
`serde(flatten)` or Other/Unknown variant so that a preprocessor would
at least see the extra fields/variants and pass them along back to the
output. However, a preprocessor or renderer wouldn't know what to do
with those new fields/variants (particularly `BookItem`) which would
itself be a problem. It's still possible to do something like this in
the future, but for now I think it's fine to restrict these to
semver-major changes.
This adds dynamic navigation of headers of the current page in the
sidebar. This is intended to help the user see what is on the current
page, and to be able to more easily navigate it. The "current" header is
tracked based on the scrolling behavior of the user, and is marked with
a small circle. This includes automatic folding to help keep it from
being too unwieldy on a page with a lot of nested headers.
This includes the `output.html.sidebar-header-nav` option to disable it.
I'm sure there are tweaks, fixes, and improvements that can be made. I'd
like to get this out now, and iterate on it over time to make
improvements.
This renames the "sections" list to "items". In practice, this list has
contained more than just "sections" since parts were added. Also, the
rest of the code consistently uses the term "items", since the values it
contains are called `BookItem`s. Finally, the naming has always been a
little confusing to me.
This is a very disruptive change, and I'm not doing it lightly. However,
since there are a number of other API changes going into 0.5, I think
now is an ok time to change this.
This adds `MarkdownOptions` for creating the pulldown-cmark parser, and
`HtmlRenderOptions` for converting markdown to HTML. These types should
help make it easier to extend the rendering options while remaining
semver compatible. It should also help with just general ergonomics of
using these functions.
This replaces the `{{#previous}}` and `{{#next}}` handelbars helpers
with simple objects that contain the previous and next values. These
helpers have been a bit fussy to work with and have caused issues in the
past. This drops a large amount of somewhat fragile code with something
that is a bit simpler.
Additionally, this switches the previous/next arrows to use an `{{#if}}`
instead CSS trickery which may help with upcoming changes to
font-awesome.
This removes the deprecated `output.html.copy-fonts` option. This was
deprecated in https://github.com/rust-lang/mdBook/pull/1987. The
behavior now is that the default fonts are copied over unless there is a
custom `theme/fonts/fonts.css` file.
This switches all public types to use non_exhaustive to make it easier
to make additions without a semver-breaking change.
Some of the ergonomics are hampered due to the lack of exhaustiveness
checking. Hopefully some day in the future,
non_exhaustive_omitted_patterns_lint or something like it will get
stabilized.
Closes https://github.com/rust-lang/mdBook/issues/1835
