This fixes an issue where `mdbook serve` would repeatedly show an error
message every second if the `output.html` config had a problem. The
issue is that `set_roots` was doing more work than I realized. It is not
necessary to call it every time in the main polling loop, since the
roots only change when the book configuration changes.
The solution is to just reset the roots whenever the book config
changes.
Fixes https://github.com/rust-lang/mdBook/issues/2946
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 checks the entire structure of the heading nav for this test. It
currently is not handling nesting properly.
Having a large inline string like this may not be the easiest to
maintain or be able to see the structure. I don't see a way to format it
in goml.
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 disables the update-dependencies cron job in forks. It's not
uncommon for people to leave GitHub Actions enabled in a fork (which in
my experience seems to be the default?), and this unfortunately means
that this job will run in all those forks which is probably not what
people want.
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.
Comments in code examples often rely on exact column alignment,
e.g. for ASCII-art. This alignment often relies on both code and
comment characters having exactly the same width.
Setting `font-style: italic` seems to break these invariants with
common monospace fonts used by browsers. This may be due to font
synthesis when the monospace font does not have a native italic
variant.
E.g., see these code examples when using the `ayu` theme:
- https://doc.rust-lang.org/1.90.0/reference/types/closure.html#r-type.closure.drop-order
- https://doc.rust-lang.org/1.90.0/reference/types/impl-trait.html#r-type.impl-trait.generic-capture.precise.use
It seems more important to have correct alignment than to style these
elements in italics, so let's drop the italic styling.
One alternative would be to set `font-synthesis: none` instead. This
would prevent font synthesis-related misalignment while still
rendering italics when a font supports italics natively. This might
correct the alignment issue, but ASCII-art in comments often wants
vertical bars to actually be vertical, so it still seems better to
just turn off italics entirely.
A more minimal change might be to only drop this from comments and not
from `hljs-quote`, but it seems the styling for these classes are
usually kept in sync, so we preserve that here.
This makes sure that the sidebar headings don't have the `<mark>` tag.
When these are created, the Marker is unable to remove them from the
sidebar (and we don't want them there in the first place).
I suspect we'll want more filtering in the future, but I'm not sure
exactly what to filter. Alternatively, it could have an allow list of
tags, and filter all others out.
This updates the header navigation so that:
- Added a colored bar to break it apart from the chapter navigation.
- Removed the colored circle and just use link color to make it
look cleaner.
This particular value can go to zero when the document height and the
window height are exactly the same value. This causes a NaN which causes
the "current" heading nav bug to not update properly. This clamps the
value to 1 to avoid that.
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 updates the heading nav debug code with a few changes:
- Now enabled with the `mdbookEnableThresholdDebug` function.
- Adds a table with the relevant internal variables.
This is no longer used, as individual books have been added to support
different GUI tests. If there is anything here that we later decide we
need to keep for whatever reason, the needed content can be brought back
as new GUI test books. Otherwise, the guide and other books should cover
most things here.
This adds the all-summary GUI test book which can be used for general
purpose tests that need a few pages to exercise all the different kinds
of items.
This adds the ability to use multiple books for the GUI tests. This is
helpful since some tests need special configuration, and sharing the
same book can make it difficult or impossible to test different
configurations. It also makes it difficult to make changes to the
test_book since it can affect other tests.
This works by placing the books in the tests/gui/books directory. The
test runner will automatically build all the books. The gui tests can
then just access the DOC_PATH with the name of the book.
Books are now saved in a temp directory to make it easier to use the
DOC_PATH variable, instead of being tests/gui/books/book_name/book which
is a little awkward.
Following commits will restructure the existing book. This is just a
mechanical move.
These docs were slightly drifting from the user guide docs. Instead of
trying to maintain multiple copies of this, I have changed it so that
it just links out to the guide.
(The guide docs could be cleaned up a little, but that's a separate
issue.)
During development I often need to run a bunch of tests. Instead of
having some unwieldy shell command, I have added this xtask to help with
running the testing commands.
This adds a job to automatically update cargo dependencies once a month.
I've added this script instead of using Renovate because I couldn't get
Renovate to update versions in `Cargo.toml`. I also wanted to batch
transitive dependency updates all in one PR.
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.
These functions are only used by the links preprocessor. I'm moving
these functions to put them closer to the code that they are associated
with, and to reduce the public API surface.
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 adds a bunch of tests to better exercise the HTML rendering and to
be able to track any changes in its behavior.
This includes a new `check_all_main_files` to more conveniently check
the HTML content of every chapter in a book.
This is a very simplistic utility to compare the output of different
versions of mdbook. This is useful when making changes to compare
real-world books to see what changes actually happen.
This is a variation of scripts that I have been using for a few years.
This could definitely use some improvements, but this seems like it
could be useful as-is.
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 removes the macro_use for clap just because I'm not a big fan of
glob-style imports like this. I think being a little more explicit here
makes it a little clearer where these macros come from.
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 changes the publishing process so that when publishing the guide
and the current version is a pre-release, it will be pushed to a
directory called `/pre-release/`.
This also switches from using simpleinfra's SSH-based script to a simple
push using normal git commands.
This uses the new guide-helper preprocessor to insert the version string
on the continuous integration guide page. This should make it easier to
bump new versions.
This adds a test to ensure that the interface for preprocessors and
renderers does not change unexpectedly, particularly in a semver
compatible release.
Closes https://github.com/rust-lang/mdBook/issues/1574
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 test is failing on CI. I don't know why, as I cannot reproduce
locally. Perhaps it is due to the update to browser-ui-test? Or perhaps
some events from the new nav bar are delaying something?
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 adds the ability to pass options to browser-ui-test, which can help
with debugging or doing things like snapshot work. It's maybe not the
cleanest since it doesn't support space-separated args, but should be
good enough.
This enables the hash-files setting by default. We have been running it
for a while, and it seems most of the issues have been resolved. This
should help with more reliably loading content like the toc contents.
This is helpful for matching patterns within a larger file. The error
message isn't quite as good, since it doesn't explicitly say "pattern
not found", but I think you can figure it out from the context.
This sprinkles track_caller on some more test functions to give more
useful line numbers on errors when a test fails.
read_to_string was changed since it couldn't track caller on a closure.
This updates eslint to lint on the toc.js.hbs file. This file uses a
small amount of hbs templating which eslint can't handle. This adds a
hacky preprocessor which will strips out the handlebars tags so that the
file can be linted.
This requires a switch to the configuration file format described at
https://eslint.org/docs/latest/use/configure/configuration-files. I used
the automatic tool to generate the new file, with some simplifications
around defaults.
- Removed no-cond-assign override, it is no longer needed.
- Fixed `catch (e)` where `e` is not used. This seems a little pedantic
to me, but seems like a relatively easy fix to just remove it, and I
believe the syntax without the variable has been supported for quite
some time. Alternatively it could also be `_e`, or explicitly allowed.
- Added `--no-warn-ignored` to the script since it was very noisy.
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 enables the smart-punctuation setting by default. The long term
plan is to continue to enable more markdown extensions by default across
semver breaking releases.
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 changes all HTML IDs so that they have the `mdbook-` prefix. This
should help avoid ID conflicts between internal IDs and IDs from user
content such as section headers.
This is a relatively disruptive change and has a high risk of breaking
something. However, I think I have covered everything, and if anything
is missed, hopefully it will get detected.
I did not change class names since the chance of a collision is much
smaller than with IDs. However, that is something that could be
considered in the future.
Closes https://github.com/rust-lang/mdBook/issues/880
This changes the `--dest-dir` flag so that it is relative to the current
directory, not the book root. This has been a source of confusion for
several people.
Fixes https://github.com/rust-lang/mdBook/issues/698
This removes the `--dest-dir` flag from the `mdbook test` subcommand
because it is unused. The test command does not generate output, so it
doesn't need an output directory.
These tests have been flaky, and in general it was probably unwise to
try to rely on an external site like this. I was unable to determine
exactly why the test is failing. The page loads, and then puppeteer
throws an error.
I don't know if it is really feasible to bring these back in some form.
It's probably more effort than it is worth.
Closes https://github.com/rust-lang/mdBook/issues/2765
There's a regression caused by recent refactor work, as it used to execute preprocessors/backends in a deterministic way, but now this is not the case, which causes trouble when some backends implicitly depend on the result from another backend and happen to work (e.g. mdbook-pdf). The root cause is that a HashMap has no order, so this PR switches this into `BTreeMap` instead.
Signed-off-by: Hollow Man <hollowman@opensuse.org>
This changes `with_renderer` and `with_preprocessor` to replace any
extensions of the same name instead of just appending to the list. This
is necessary for rust-lang's build process, because we replace the
preprocessors with local ones. Previously, mdbook would just print an
error, but continue working. With the change that preprocessors are no
longer optional by default, it is now required that we have a way to
replace the existing entries.
This changes the serialization so that `book.src` is not serialized if
it is the default. This removes the somewhat pointless `src = "src"`
which shows up in the default `mdbook init` output. Deserialization
should still default to `"src"`.
This adds the `optional` field to the preprocessor configuration to
mirror the same option for the `output` table. Missing preprocessors are
now an error unless the `optional` field is set. This should help with
inadvertently building a book when a missing preprocessor that you
expect to be installed.
This changes preprocessors so that:
- Relative paths in the `command` value are relative to the book root.
- The process current directory is the book root.
This makes it so that it isn't dependent on the directory where `mdbook`
is executed.
Fixes https://github.com/rust-lang/mdBook/issues/1424
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 support for renderer paths that are relative
to the destination. Relative renderer command paths now must always be
relative to the book root.
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 changes it so that it is an error if there is ever an unknown
configuration field. This is intended to help avoid things like typos,
or using an outdated version of mdbook. Although it is possible that new
fields could potentially safely be ignored, setting up a warning system
is a bit more of a hassle. I don't think mdbook needs to have the same
kind of multi-version support as something like cargo does. However, if
this ends up being too much of a pain point, we can try to add a warning
system instead.
There are a variety of changes here:
- The top-level config namespace is now closed so that it only accepts
the keys defined in `Config`.
- All config tables now reject unknown fields.
- Added `Config::outputs` and `Config::preprocessors` for convenience
to access the entire `output` and `preprocessor` tables.
- Moved the unit-tests that were setting environment variables to the
testsuite where it launches a process instead.
Closes https://github.com/rust-lang/mdBook/issues/1595
This fixes an issue where the `check` methods would inadvertently
rebuild the books if the `mdbook build` command is run. Normally this
isn't too much of an issue unless the `build` command is run with
options that affect the output.
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
This removes the `pub` status of the SectionNumber field. The intent is
to make this potentially extensible in the future if we decide to add
more fields, or change its internal representation. With the existence
of the deref impls, generally this change shouldn't be visible except
for the constructor, which hopefully shouldn't be too cumbersome to use
`SectionNumber::new` instead.
A recent nightly changed the format of the panic message. This updates
the test that was matching against this so it doesn't match the text
that has changed.
This removes toml as a public dependency. This reduces the exposure of
the public API, reduces exposure of internal implementation, and makes
it easier to make semver-incompatible changes to toml.
This is accomplished through a variety of changes:
- `get` and `get_mut` are removed.
- `get_deserialized_opt` is renamed to `get`.
- Dropped the AsRef for `get_deserialized_opt` for ergonomics, since
using an `&` for a String is not too much to ask, and the other
generic arg needs to be specified in a fair number of situations.
- Removed deprecated `get_deserialized`.
- Dropped `TomlExt` from the public API.
- Removed `get_renderer` and `get_preprocessor` since they were trivial
wrappers over `get`.
This is a pure git rename in order to make sure that git can follow
history. The next commit will integrate these into mdbook-html.
Additional commits will refactor/move/remove items.
This is a pure git rename in order to make sure that git can follow
history. The next commit will integrate these into mdbook-html.
Additional commits will refactor/move/remove items.
This is a pure git rename in order to make sure that git can follow
history. The next commit will integrate these into mdbook-summary.
Additional commits will refactor/move/remove items.
This updates everything for the move of config to mdbook-core. There
will be followup commits that will be moving and refactoring the config.
This simply moves it over unchanged.
This is a pure git rename in order to make sure that git can follow
history. The next commit will integrate these into mdbook-core.
Additional commits will refactor/move/remove items.
This updates everything for the move of utils to mdbook-core. There will
be followup commits that will be moving and refactoring these utils.
This simply moves them over unchanged (except visibility).
This is a pure git rename in order to make sure that git can follow
history. The next commit will integrate these into mdbook-core.
Additional commits will refactor/move/remove items.
This moves Result and Error to mdbook-core with the anticipation of
using them in user crates. For now, the internal APIs will be using
anyhow directly, but the intent is to transition more of these to
mdbook-core where it makes sense.
These are two new crates intended to support implementing preprocessors
and renderers. Currently these stubs just have MDBOOK_VERSION, but
future commits will migrate more code to these crates.
This is intended as a shared, internal library that will be used by
other mdbook crates. The intention is that those crates will either
directly use, or reexport items from this crate.
Initially this includes MDBOOK_VERSION, which will get reexported from
the preprocessor and renderer crates.
This moves common settings that can be shared across crates to the
shared workspace table. This will make it easier to maintain these
settings when adding more crates.
rel=edit lets a page indicate that the linked resource can be used to
edit the page. It is defined at https://microformats.org/wiki/rel-edit.
This can then be parsed by tools like the Universal Edit Button and
custom bookmarklets to open the edit page corresponding with a website.
This fixes several issues with how the sidebar was behaving:
- Manually resizing the sidebar was incorrectly applying transition
animations to the page-wrapper causing awkward movement.
- Clicking the sidebar toggle caused the menu bar to behave differently
compared to loading a page with the sidebar visible or hidden.
- page-wrapper animation wasn't working when JS was disabled.
- RTL sidebar animation was broken.
Most of these issues stem from
https://github.com/rust-lang/mdBook/pull/2454 which moved `js` and
`sidebar-visible` classes from `<body>` to `<html>`, but failed to
update some of the JS and CSS code that was still assuming it was on the
body.
https://github.com/rust-lang/mdBook/pull/1641 previously moved `js` from
`<html>` to `<body>` with the reasoning
"This will be necessary for using CSS selectors on root attributes.".
However, I don't see how that is absolutely necessary, since selectors
like `[dir=rtl].js` should work to select the root element.
This adds the ability to redirect URLs with `#` fragments. This is
useful when section headers get renamed or moved to other pages.
This works both for deleted pages and existing pages.
The implementation requires the use of JavaScript in order to manipulate
the location. (Ideally this would be handled on the server side.)
This also makes it so that deleted page redirects preserve the fragment
ID. Previously if you had a deleted page redirect, and the user went to
something like `page.html#foo`, it would redirect to `bar.html` without
the fragment. I think preserving the fragment is probably a better
behavior. If the new page doesn't have the fragment ID, then no harm is
really done. This is technically an open redirect, but I don't think
that there is too much danger with preserving a fragment ID?
When showing the sidebar, Safari was causing the sidebar to snap into
place without animating. This is apparently some well-known issue where
it doesn't like adding new elements (or changing display) and toggling
an animated transition in the same event loop.
Because `{{resource}}` references don't affect the hash[^1], we need
to avoid referencing dynamic content from within static content.
Otherwise, you get a cached searcher.js referencing a searchindex
that no longer exists.
[^1]: if we made it affect the hash, we'd have to do full dependency
tracking, and we'd no longer be able to support circular refs
The reason the ACE editor was failing to load the rust syntax
highlighting is because the syntax highlighting was being created
*after* the editor was created. If the editor is created first, then ACE
tries to load `ace/mode/rust`. Since it isn't already defined, it tried
to compute the URL and load it manually. However, since the URLs now
have a hash in it (via https://github.com/rust-lang/mdBook/pull/1368),
it was unable to load.
The solution here is to make sure `ace/mode/rust` is defined before
creating the editors. Then ACE knows that it can just load the module
directly instead of trying to fetch it from the server.
Fixes https://github.com/rust-lang/mdBook/issues/2700
This makes a few changes to the help popup:
- Move css to chrome.css, since this is a UI element.
- Move HTML code to index.hbs instead of generated in JavaScript.
In general I prefer to keep HTML out of JavaScript when possible,
and I didn't see a particular reason to avoid it.
- Added a click handler to dismiss the popup.
- Make sure handlers get removed when dismissed.
- Use `mdbook-` prefixes for IDs to avoid collisions with headers.
- Don't show search if it isn't enabled.
- Add the new `/` shortcut.
- Use flex layout for better positioning.
- Dim out the surrounding text using an overlay.
- Various other styling tweaks.
- Add a GUI test.
When describing, in the guide, the keyboard shortcuts that we accept,
let's use the `<kbd>` element. This causes the key to render in a box
that people will recognize as conventional.
The way that this is displayed helps to make it clear that, though we
present the key in uppercase, we actually mean for the lowercase
letter to be entered. Therefore, we present the key in uppercase
since 1) that's how it appears on most keyboards and 2) for some
characters such as `l`, presenting the character in lowercase might be
ambiguous.
We'll spell out "Escape" rather than saying "Esc" (even though many
keyboards spell it that way) since the `KeyboardEvent.keycode`[^1] is
called "Escape", and that's how it would appear in an
`aria-keyshortcuts` attribute[^2].
[^1]: https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/keyCode
[^2]: https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-keyshortcuts
It's common for search boxes like ours to automatically navigate to
the first search result when the `enter` / `select` key is pressed, as
that can allow for rapid navigation. E.g., the MDN documentation does
this.
Let's similarly navigate to the first result when, in the search box,
the user presses the `enter` key and there is a first result to which
to navigate.
If, when searching, one pressed the down arrow key when there were no
results, this caused an uncaught exception and defocused the search
box.
Let's prevent this and keep the search box focused when pressing down
in this state by checking first whether there is a result for us to
focus instead.
We allow for using `s` to open the search box, but it's more common to
use `/` (forward slash) for this. E.g., MDN's documentation uses `/`
for search. Rustdoc and GitHub accept either.
Let's allow either key to be used, and let's switch to "advertising"
`/` rather than `s` in the hover text for the search button.
In making that switch, let's also simplify that hover text a bit.
Previously it had said "Search. (Shortkey: s)". This was the only top
button on which we had included a period in the hover text. Let's
remove that, and let's remove the "shortkey" bit of jargon. It's
enough to just put `/` in a parenthetical, i.e. "Search (`/`)".
People will gleam from that what we mean.
We've also updated the guide accordingly.
This skips serializing of the multilingual field since it is unused, and
we plan to remove it in the future. This helps avoid it showing up in
`mdbook init`.
Although there isn't a direct equivalent in the new testsuite, I felt
like these weren't adding any specific coverage that the existing tests
don't already exercise. If it does turn up that there is specific
coverage missing, then I would prefer to have tests which exercise the
specific thing of interest rather than have these kinds of non-specific
tests.
This helps if you are creating new tests, or debugging existing tests by
allowing you to run `mdbook` directly in the test directory to try
things out. But we don't want to ever check these files in.
I don't think these exercise anything in particular that aren't
necessarily covered by other things. If this ends up exposing a lack
of coverage somewhere, I would prefer to add more focused test for
specific things.
After some testing I notice that this test is failing randomly because
the `true` program is exiting before mdbook is able to transmit the
JSON, and it fails with a broken pipe.
This will be replaced with backends_receive_render_context_via_stdin,
which does essentially the same thing, but does suffer from the same
problem.
This removes the `allow(missing_docs)` and fixes any issues.
There's probably more work to be done to improve the API docs. This was
just a minor thing I wanted to clean up.
This sets up CI to check clippy with a restricted set of clippy groups.
Some of the default groups have some excessive sets of lints that are
either wrong or style choices that I would prefer to not mess over at
this time. The lint groups can be adjusted later if it looks like
something that would be helpful.
This makes several changes to how footnotes are rendered:
- Backlinks are now included, which links back to the reference so you
can continue reading where you left off.
- Footnotes are moved to the bottom of the page. This helps with the
implementation of numbering, and is a style some have requested. I
waffled a lot on this change, but supporting the in-place style was
just adding too much complexity.
- Footnotes are now highlighted when you click on a reference.
- Some of the spacing for elements within a footnote has now been fixed
(such as supporting multiple paragraphs).
- Footnote navigation now scrolls to the middle of the page.
This is an alternative to https://github.com/rust-lang/mdBook/pull/2475
Closes https://github.com/rust-lang/mdBook/issues/1927
Closes https://github.com/rust-lang/mdBook/issues/2169
Closes https://github.com/rust-lang/mdBook/issues/2595
This fixes a problem where the search was not displaying in
sub-directories. The problem was that `searcher.js` only exists in one
place, and was loading `searchindex.json` with a relative path. However,
when loading from a subdirectory, it needs the appropriate `..` to reach
the root of the book.
Alternatively we could change the error message to
only include take the status code from the os by
using
output.status.code().unwrap() in preprocess/cmd.rs
where this error message is generated.
In that case we could have the exact same error
message on all the OS-es.
This fixes an issue where mdbook would panic if a non-draft chapter has
a None source_path when generating the search index. The code was
assuming that only draft chapters would have that behavior. However, API
users can inject synthetic chapters that have no path on disk.
This updates it to fall back to the path, or skip if neither is set.
This config setting provides the ability to disable search indexing on a
per-chapter (or sub-path) basis.
This is structured to possibly add additional settings, such as perhaps
a score multiplier or other settings.
previous implementation used `:not(.fd) + .fd` and `.fd + :not(.fd)`.
the latter selector caused many problems:
- it doesn't select footnote defs which are last children
(this can be easily triggered in a blockquote)
- it changes the margin of the next sibling, rather than the footnote def
itself, which can also *shrink* margin for elements with big margins
(this happens to headings)
- because it applies to the next sibling it is also quite hard to
override in user styles, since it may apply to any element
this commit replaces the latter selector with `:not(:has(+ .fd))`,
which fixes all of the mentioned problems.
Uses an iframe instead. The downside of iframes comes from them
not necessarily being same-origin as the main page (particularly
with `file:///` URLs), which can cause themes to fall out of sync,
but that's not a problem here since themes don't work without JS
anyway.
Before this change, the Rust `unstable-book` is 88MiB.
With this change, it becomes 15MiB. Other pages might not be
as extreme, but it's expected to help any book like this.
This change is so drastic because, if every chapter has a link to
every other chapter, the result is *O*(n<sup>2</sup>) text output.
Above mentioned function copies files (recursively) from a source to a
destination directory. For that, file/directory paths have to be created
repeatedly. This allocates as directory and file names are concatenated
into an owning path structure.
The number of allocations can be reduced by creating file/directory
paths only once and borrowing them instead of cloning/recreating them.
In bigger projects, this reduces execution time noticeably. Please note
that file system operations are dominant from performance POV.
on rust reference book this reduces total allocs from 490mb to 474mb:
==23272== Total: 490,538,699 bytes in 1,760,117 blocks
==23272== At t-gmax: 13,872,954 bytes in 4,655 blocks
==23272== At t-end: 488,516 bytes in 884 blocks
==23272== Reads: 830,509,060 bytes
==23272== Writes: 522,290,614 bytes
to
==40876== Total: 474,156,323 bytes in 1,521,025 blocks
==40876== At t-gmax: 13,872,954 bytes in 4,655 blocks
==40876== At t-end: 488,516 bytes in 884 blocks
==40876== Reads: 820,933,434 bytes
==40876== Writes: 514,838,350 bytes
Currently, the output from `rustdoc --test` is not colored because
`rustdoc`'s stdout is not a tty. The output of a failed `rustdoc` run is
sent to `mdbook`'s stderr via the `error!()` macro. This commit checks
if stderr is a tty using the standard `.is_terminal()` and if so, passes
`--color always` to `rustdoc`.
The test output from `rustdoc` includes the full path that `rustdoc` was
called with. This obscures the path of the file with the error. E.g.,
```
---- /var/folders/9v/90bm7kb10fx3_bprxltb3t1r0000gn/T/mdbook-tnGJxp/lab0/index.md - Lab_0__Getting_Started (line 3) stdout ----
error: expected one of `!`, `.`, `::`, `;`, `?`, `{`, `}`, or an operator, found `code`
--> /var/folders/9v/90bm7kb10fx3_bprxltb3t1r0000gn/T/mdbook-tnGJxp/lab0/index.md:4:6
|
3 | this code has a bug
| ^^^^ expected one of 8 possible tokens
error: aborting due to previous error
```
This commit runs `rustdoc` in the temp directory and replaces any
relative library paths with absolute library paths. This leads to
simpler error messages. The one above becomes
```
---- lab0/index.md - Lab_0__Getting_Started (line 3) stdout ----
error: expected one of `!`, `.`, `::`, `;`, `?`, `{`, `}`, or an operator, found `code`
--> lab0/index.md:4:6
|
3 | this code has a bug
| ^^^^ expected one of 8 possible tokens
error: aborting due to previous error
```
(with colors, of course).
Nim is a systems programming language (included in the highlight.js
`system` group), and we're quite happily using `mdBook` in several of
our documentation projects starting with our [style
guide](https://status-im.github.io/nim-style-guide/).
While we can maintain our own highlight.js, including `Nim` in the
default distribution would allow us to promote more mdBook usage in the
Nim community at the cost of a ~2kb increase in the `highlight.js` size.
Replace phyiscal properties (top/bottom/left/right) with logical
properties (start/end) that can be used in non-LTR contexts (e.g.,
content in Arabic or Hebrew).
Based on the CSS Logical Properties and Values Level 1 specification,
currently an Editor's Draft [1].
Referencing MDN, all major browsers except Internet Explorer support the
margin, padding, and border properties.
[1]: https://drafts.csswg.org/css-logical/
Signed-off-by: Tim Crawford <crawfxrd@gmail.com>
The `.hljs` class added by highlight.js adds a `display: block` rule
which makes `padding` apply correctly (left padding on all lines,
not just the first one).
Make sure that rule is applied even if highlight.js isn't run.
Fix paths specified in extra-watch-dirs being relative to the current working directory rather than the book root
If there is an error canonicalising paths in extra-watch-dirs, log the error and exit rather than panicking
This switches to `gh` which is the more modern CLI, and also
available by default which removes the old installer script.
This also tightens the scope where GITHUB_TOKEN is exposed to just
the step where `gh` is executed.
Finally, it tightens the permissions on the GITHUB_TOKEN (though
`contents: write` is extremely permissive, since that allows writing to
almost anything in the repo).
Previously, sidebar scroll was set in an external script which caused a
flicker as the sidebar is initially rendered without any scroll before
being scrolled to the desired location.
Switching to an inline script right after the HTML tags for the sidebar
seems to avoid the flicker in most cases. In addition, logic is added to
avoid scrolling jumps when navigating via links within the sidebar.
The code here leads me to believe that the intention is for the sidebar
to be default visible on large screens (where `clientWidth` > 1080) and
hidden otherwise.
However, as previously written, if the `localStorage.getItem` call fails
(for example, if the user agent is not accepting cookies), then we fall
back to `sidebar = sidebar || 'visible';` — but `sidebar` is already set
to `hidden`, so the `|| 'visible'` never happens.
This results in the sidebar hiding itself on every navigation through an
mdBook, meaning if you're just switching between sections trying to find
something that you keep needing to re-open the sidebar.
It is preferable to remove WebKit-specific styling and use the browser
and OS default scrollbars.
Thanks to comments from @julianfortune, @arniu, and @ehuss.
Closes#1483.
While adding support for translations[1] to Comprehensive Rust 🦀, I
noticed that `mdbook test` doesn’t execute preprocessors the same way
as `mdbook build`.
This PR makes the two commands use the same code to find and execute
preprocessors.
[1]: https://github.com/google/comprehensive-rust/pull/130
Currently, the documentation link is specified in Cargo.toml as:
documentation = "http://rust-lang.github.io/mdBook/index.html"
which propagates to crates.io and if users click on the docs link there they get the non-TLS version. Not likely to cause major issues, but still best practice to use the HTTPS version since it's there
Quoting from the HTML specification[1]:
A document must not contain both a meta element with an http-equiv attribute
in the Encoding declaration state and a meta element with the charset
attribute present.
So we remove the <meta> with the http-equiv attribute from our template.
[1]: https://html.spec.whatwg.org/multipage/semantics.html#attr-meta-http-equiv-content-type
Allows for special styles to call them out since they're different than
normal text and different than code. They can make use of styles they
inherit for font style and weight.
Notes on changes:
- Added new CSS variables for reused elements
- The font-* rules are separate for each aspect so that they can inherit
bold/italic/etc
Closes https://github.com/rust-lang/mdBook/issues/1813
Before, a code block would always end with a final newline. The
newline was added unconditionally by `hide_lines`.
When the code block is syntax highlighted by highlight.js, this is not
a problem, no empty line is added for a final trailing `\n` character.
However, when the code block is editable and thus handled by the ACE
editor, a trailing newline _is_ significant. I believe this issue is
most closely described by https://github.com/ajaxorg/ace/issues/2083
in the upstream repository.
The effect of the way ACE handles newlines is that a code block like
<pre>
Some code
</pre>
will create an editor with _two_ lines, not just one.
By trimming trailing whitespace, we ensure that we don’t accidentally
create more lines in the ACE editor than necessary.
Surprisingly, this fixes the error filed at #1860!
This seems suspicious, perhaps indicative of a bug in Rust's non-lexical
lifetime handling?
The lifetimes in the `handlebars::Renderable::render` method signature
are quite complicated, and its unclear to me whether or not Rust is
catching some new safety edge-case that wasn't previously handled
correctly...
Possibly related to `drop` order, which I *think* is related to the
order of binding statements?
nixpkgs build system sets `RUST_LOG=` (empty value) by default.
This switches `mdBook` into warnings+ mode (instead of info+).
This causes the following tests to fail:
$ RUST_LOG= cargo test --test cli_tests
...
cli::test::mdbook_cli_can_correctly_test_a_passing_book
cli::test::mdbook_cli_detects_book_with_failing_tests
cli::build::mdbook_cli_dummy_book_generates_index_html
The change drops RUST_LOG= entry.
By default, `opener` launches the subprocess without waiting for its
completion, compared to `open` which waits for its completion.
This is helpful in case the `watch` feature is enabled and one of the
following commands `watch | serve --open` is used. If this command would
open the browser, listening for changes would be blocked by the browser.
Inputting paths are not necessary and will break ci, we can just leave paths out. We also changed 'master' to main since anyone reading this is probably going to be making mains
restructure guide configuration section
restructure guide configuration section
redirect to new config top level
fix broken links
use a relative path for redirect
Co-authored-by: Eric Huss <eric@huss.org>
remove extra heading
The `IndexPreprocessor` rewrites the path for files
named `README.md` to be `index.md`. This breaks the edit link
in some circumstances.
To address this issues, the `Chapter` struct has now a new attribute
called `source_path`. This is initialized with the same value as
`path`, but is never ever changed.
Finally, the edit link is built by using the `source_path` rather
than the `path`.
The existing light theme has relatively low contrast between the text
(and other UI elements) and background (especially within code blocks).
This presents difficulties for people with reduced visual contrast
perception (common in older adults).
This patch makes changes to the default `light` theme to meet the
minimum contrast requirement of the v2.1 W3C WCAG (Web Content
Accessibility Guidelines)
https://www.w3.org/WAI/WCAG21/quickref/#contrast-minimum
The small size, and slender font used for the title text makes it hard
to read, even with the increased contrast colour scheme, so this patch
also increases the size of the title text font by 20%.
Closes#1442
Provides better feedback if user executes in a different folder than what is expected by mdbook
After the changes `mdbook build`
```
2020-12-19 14:27:35 [ERROR] (mdbook::utils): Error: Couldn't open SUMMARY.md in "/Users/vicky/rust/source_codes/mdbook_testing/src/src" directory
2020-12-19 14:27:35 [ERROR] (mdbook::utils): Caused By: No such file or directory (os error 2)
```
Previously: `mdbook build`
```
2020-12-19 14:28:46 [ERROR] (mdbook::utils): Error: Couldn't open SUMMARY.md
2020-12-19 14:28:46 [ERROR] (mdbook::utils): Caused By: No such file or directory (os error 2)
```
With the current description of the command, I was expecting to get a directory named with the project name, but the files were created in the current directory.
I Think a more precise description would help first-time users.
Currently, the `copy_files` function doesn't support symlink files due to
its use of `DirEntry::metadata` - To avoid this issue, this patch
resolves the file path first before checking for metadata.
Fixes#1157
It's unlikely that the bundled version wouldn't load, and it's
especially unlikely that the page would load but the bundled version
would not.
Also, if it doesn't load, it should fall back to another monospace font,
which is fine.
Before:
/path/to$ cat book/.nojekyll
This file makes sure that Github Pages doesn't process mdBook's output./path/to$ ▎
After:
/path/to$ cat book/.nojekyll
This file makes sure that Github Pages doesn't process mdBook's output.
/path/to$ ▎
Summary items that had their name split into two lines ended up with the
last word of one line and the first word of the next line glued
together, since a space wasn't added.
Added test case for it.
Fixes#1218
In a recent discussion in the amethyst docs discord channel,
it was suggested that using an "eye" icon might make the show hidden
lines feature of mdbook's code sample rendering more discoverable.
I myself overlooked the arrows that are in use now.
Fixes#663 at least in part.
Updates to 10.1.1, with support for new languages added to the common set.
Built with:
common languages + D, handlebars, haskell, julia, scala, x86asm, armasm, yaml
Size difference:
New highlight.js: 132KiB
Old highlight.js: 84KiB
--
New highlight.js compressed: 48KiB
Old highlight.js compressed: 36KiB
- removed config output_404
- ensure serve overrides the site url, and hosts the correct 404 file
- refactor 404 rendering into separate fn
- formatting
* Removed the itertools dependency
* Removed an unused feature flag
* Stubbed out a toml_query replacement
* Update dependencies.
* Bump env_logger.
* Use warp instead of iron for http server.
Iron does not appear to be maintained anymore. warp/hyper seems to be
reasonably maintained. Unfortunately this takes a few seconds more
to compile, but shouldn't be too bad.
One benefit is that there is no longer a need for a separate websocket
port, which makes it easier to run multiple servers at once.
* Update pulldown-cmark to 0.7
* Switch from error-chain to anyhow.
* Bump MSRV to 1.39.
* Update elasticlunr-rs.
Co-authored-by: Michael Bryan <michaelfbryan@gmail.com>
At present, code listings without a main function will be wrapped in one and
annotated with an allow lint check attribute provided by the following [code][]:
```
format!(
"\n# #![allow(unused_variables)]\n{}#fn main() {{\n{}#}}",
attrs, code
)
```
A broader lint check attribute such as `#![allow(unused)]` seems like it might
better fit the apparent intent of this code.
Addresses: https://github.com/rust-lang/mdBook/issues/1192
[code]: 769cc0a7c1/src/renderer/html_handlebars/hbs_renderer.rs (L635-L638)
The serve and watch commands use .gitignore file in book root directory
to read exclude patterns used when watching for changed files. A
.gitignore from parent directory or user home is not used though.
Add documentation of this behaviour to both commands.
@@ -6,15 +6,23 @@ If you have come here to learn how to contribute to mdBook, we have some tips fo
First of all, don't hesitate to ask questions!
Use the [issue tracker](https://github.com/rust-lang/mdBook/issues), no question is too simple.
If we don't respond in a couple of days, ping us @Michael-F-Bryan, @budziq, @steveklabnik, @frewsxcv it might just be that we forgot. :wink:
### Issues to work on
## Issue assignment
Any issue is up for the grabbing, but if you are starting out, you might be interested in the
**:warning: Important :warning:**
Before working on pull request, please ping us on the corresponding issue.
The current PR backlog is beyond what we can process at this time.
Only issues that have an [`E-Help-wanted`](https://github.com/rust-lang/mdBook/labels/E-Help-wanted) or [`Feature accepted`](https://github.com/rust-lang/mdBook/labels/Feature%20accepted) label will likely receive reviews.
If there isn't already an open issue for what you want to work on, please open one first to see if it is something we would be available to review.
## Issues to work on
If you are starting out, you might be interested in the
When you decide you want to work on a specific issue, ping us on that issue so that we can assign it to you.
When you decide you want to work on a specific issue, and it isn't already assigned to someone else, assign the issue to yourself by leaving a comment with the text `@rustbot claim`.
Again, do not hesitate to ask questions. We will gladly mentor anyone that want to tackle an issue.
Issues on the issue tracker are categorized with the following labels:
- **A**-prefixed labels state which area of the project an issue relates to.
- **E**-prefixed labels show an estimate of the experience necessary to fix the issue.
- **M**-prefixed labels are meta-issues used for questions, discussions, or tracking issues
- **M**-prefixed labels are meta-issues regarding the management of the mdBook project itself
- **S**-prefixed labels show the status of the issue
- **T**-prefixed labels show the type of issue
- **C**-prefixed labels show the category of issue
### Building mdBook
## Building mdBook
mdBook builds on stable Rust, if you want to build mdBook from source, here are the steps to follow:
@@ -46,13 +54,13 @@ mdBook builds on stable Rust, if you want to build mdBook from source, here are
0. Navigate into the newly created `mdBook` directory
0. Run `cargo build`
The resulting binary can be found in `mdBook/target/debug/` under the name `mdBook` or `mdBook.exe`.
The resulting binary can be found in `mdBook/target/debug/` under the name `mdbook` or `mdbook.exe`.
### Code Quality
## Code quality
We love code quality and Rust has some excellent tools to assist you with contributions.
#### Formatting Code with rustfmt
### Formatting code with rustfmt
Before you make your Pull Request to the project, please run it through the `rustfmt` utility.
This will ensure we have good quality source code that is better for us all to maintain.
@@ -60,7 +68,7 @@ This will ensure we have good quality source code that is better for us all to m
[rustfmt](https://github.com/rust-lang/rustfmt) has a lot more information on the project.
The quick guide is
1. Install it
1. Install it (`rustfmt` is usually installed by default via [rustup](https://rustup.rs/)):
```
rustup component add rustfmt
```
@@ -72,18 +80,14 @@ The quick guide is
```
cargo fmt
```
When run through `cargo` it will format all bin and lib files in the current crate.
When run through `cargo` it will format all bin and lib files in the current package.
For more information, such as running it from your favourite editor, please see the `rustfmt` project. [rustfmt](https://github.com/rust-lang/rustfmt)
### Finding issues with clippy
#### Finding Issues with Clippy
Clippy is a code analyser/linter detecting mistakes, and therfore helps to improve your code.
Like formatting your code with `rustfmt`, running clippy regularly and before your Pull Request will
help us maintain awesome code.
The best documentation can be found over at [rust-clippy](https://github.com/rust-lang/rust-clippy)
[Clippy](https://doc.rust-lang.org/clippy/) is a code analyser/linter detecting mistakes, and therefore helps to improve your code.
Like formatting your code with `rustfmt`, running clippy regularly and before your Pull Request will help us maintain awesome code.
1. To install
```
@@ -94,15 +98,143 @@ The best documentation can be found over at [rust-clippy](https://github.com/rus
cargo clippy
```
Clippy has an ever growing list of checks, that are managed in [lint files](https://rust-lang.github.io/rust-clippy/master/index.html).
## Change requirements
### Making a pull-request
Please consider the following when making a change:
* Almost all changes that modify the Rust code must be accompanied with a test.
* Almost all features and changes must update the documentation.
mdBook has the [mdBook Guide](https://rust-lang.github.io/mdBook/) whose source is at <https://github.com/rust-lang/mdBook/tree/master/guide>.
* Almost all Rust items should be documented with doc comments.
See the [Rustdoc Book](https://doc.rust-lang.org/rustdoc/) for more information on writing doc comments.
* Breaking the API can only be done in major SemVer releases.
These are done very infrequently, so it is preferred to avoid these when possible.
See [SemVer Compatibility](https://doc.rust-lang.org/cargo/reference/semver.html) for more information on what a SemVer breaking change is.
(Note: At this time, some SemVer breaking changes are inevitable due to the current code structure.
An example is adding new fields to the config structures.
These are intended to be fixed in the next major release.)
* Similarly, the CLI interface is considered to be stable.
Care should be taken to avoid breaking existing workflows.
* Check out the [Rust API Guidelines](https://rust-lang.github.io/api-guidelines/) for guidelines on designing the API.
## Tests
The main test harness is described in the [testsuite documentation](tests/testsuite/README.md). There are several different commands to run different kinds of tests:
- `cargo test --workspace` — This runs all of the unit and integration tests, except for the GUI tests.
- `cargo test --test gui` — This runs the [GUI test harness](#browser-compatibility-and-testing). This does not get run automatically due to its extra requirements.
- `npm run lint` — [Checks the `.js` files](#checking-changes-in-js-files)
- `cargo test --workspace --no-default-features` — Testing without default features helps check that all feature checks are implemented correctly.
- `cargo clippy --workspace --all-targets --no-deps -- -D warnings` — This makes sure that there are no clippy warnings.
- `RUSTDOCFLAGS="-D warnings" cargo doc --workspace --document-private-items --no-deps` — This verifies that there aren't any rustdoc warnings.
- `cargo fmt --check` — Verifies that everything is formatted correctly.
- `cargo +stable semver-checks` — Verifies that no SemVer breaking changes have been made. You must install [`cargo-semver-checks`](https://crates.io/crates/cargo-semver-checks) first.
To help simplify running all these commands, you can run the following cargo command:
```sh
cargo xtask test-all
```
It is useful to run all tests before submitting a PR. While developing I recommend to run some subset of that command based on what you are working on. There are individual arguments for each one. For example:
Currently we don't have a strict browser compatibility matrix due to our limited resources.
We generally strive to keep mdBook compatible with a relatively recent browser on all of the most major platforms.
That is, supporting Chrome, Safari, Firefox, Edge on Windows, macOS, Linux, iOS, and Android.
If possible, do your best to avoid breaking older browser releases.
GUI tests are checked with the GUI testsuite. To run it, you need to install `npm` first. Then run:
```
cargo test --test gui
```
If you want to only run some tests, you can filter them by passing (part of) their name:
```
cargo test --test gui -- search
```
The first time, it'll fail and ask you to install the `browser-ui-test` package. Install it with the provided
command then re-run the tests.
If you want to disable the headless mode, use the `--disable-headless-test` option:
```
cargo test --test gui -- --disable-headless-test
```
The GUI tests are in the directory `tests/gui` in text files with the `.goml` extension. The books that the tests use are located in the `tests/gui/books` directory. These tests are run using a `node.js` framework called `browser-ui-test`. You can find documentation for this language on its [repository](https://github.com/GuillaumeGomez/browser-UI-test/blob/master/goml-script.md).
### Checking changes in `.js` files
The `.js` files source code is checked using [`eslint`](https://eslint.org/). This is a linter (just like `clippy` in Rust)
for the Javascript language. You can install it with `npm` by running the following command:
```
npm install
```
Then you can run it using:
```
npm run lint
```
## Updating highlight.js
The following are instructions for updating [highlight.js](https://highlightjs.org/).
1. Clone the repository at <https://github.com/highlightjs/highlight.js>
1. Check out a tagged release (like `10.1.1`).
1. Run `npm install`
1. Run `node tools/build.js :common apache armasm coffeescript d handlebars haskell http julia nginx nim nix properties r scala x86asm yaml`
1. Compare the language list that it spits out to the one in [`syntax-highlighting.md`](https://github.com/camelid/mdBook/blob/master/guide/src/format/theme/syntax-highlighting.md). If any are missing, add them to the list and rebuild (and update these docs). If any are added to the common set, add them to `syntax-highlighting.md`.
1. Copy `build/highlight.min.js` to mdbook's directory [`highlight.js`](https://github.com/rust-lang/mdBook/blob/master/src/theme/highlight.js).
1. Be sure to check the highlight.js [CHANGES](https://github.com/highlightjs/highlight.js/blob/main/CHANGES.md) for any breaking changes. Breaking changes that would affect users will need to wait until the next major release.
1. Build mdbook with the new file and build some books with the new version and compare the output with a variety of languages to see if anything changes. The [syntax GUI test](https://github.com/rust-lang/mdBook/tree/master/tests/gui/books/highlighting) contains a chapter with many languages to examine. Update the test (`highlighting.goml`) to add any new languages.
## Publishing new releases
Instructions for mdBook maintainers to publish a new release:
1. Create a PR that bumps the version and updates the changelog:
- `cargo set-version` must first be installed with `cargo install cargo-edit`.
- Replace `<BUMP>` with the kind of bump (patch, alpha, etc.)
4. `cargo xtask changelog`
- This will update `CHANGELOG.md` to add a list of all changes at the top. You will need to move those into the appropriate categories. Most changes that are generally not relevant to a user should be removed. Rewrite the descriptions so that a user can reasonably figure out what it means.
5. `git add --update .`
6. `git commit`
7. `git push`
2. After the PR has been merged, create a release in GitHub. This can either be done in the GitHub web UI, or on the command-line:
It takes two separate paths for the book to use for "before" and "after" in case you need to customize the book to run on older versions. If you don't need that, then you can use the same directory for both the before and after.
`mdbook-compare` will do the following:
1. Clean up any book directories.
2. Build the book with the first mdbook.
3. Build the book with the second mdbook.
4. The output of those two commands are stored in directories called `compare1` and `compare2`.
5. The HTML in those directories is normalized using `tidy`.
This is the base support library for [mdBook](https://rust-lang.github.io/mdBook/). It is intended for internal use only. Other mdBook crates depend on this for any types that are shared across the crates.
> This crate is maintained by the mdBook team, primarily for use by mdBook and not intended for external use (except as a transitive dependency). This crate may make major changes to its APIs or be deprecated without warning.
## License
[Mozilla Public License, version 2.0](https://github.com/rust-lang/mdBook/blob/master/LICENSE)
This is the high-level Rust library for running [mdBook](https://rust-lang.github.io/mdBook/). New books can be created using [`BookBuilder`](https://docs.rs/mdbook-driver/latest/mdbook_driver/init/struct.BookBuilder.html). The primary type [`MDBook`](https://docs.rs/mdbook-driver/latest/mdbook_driver/struct.MDBook.html) can be used to manage and render books.
> This crate is maintained by the mdBook team for use by the wider ecosystem. This crate follows [semver compatibility](https://doc.rust-lang.org/cargo/reference/semver.html) for its APIs.
## License
[Mozilla Public License, version 2.0](https://github.com/rust-lang/mdBook/blob/master/LICENSE)
This is the HTML renderer for [mdBook](https://rust-lang.github.io/mdBook/). This is intended for internal use only. It is automatically included by [`mdbook-driver`](https://crates.io/crates/mdbook-driver) to render books to HTML.
> This crate is maintained by the mdBook team, primarily for use by mdBook and not intended for external use (except as a transitive dependency). This crate may make major changes to its APIs or be deprecated without warning.
## License
[Mozilla Public License, version 2.0](https://github.com/rust-lang/mdBook/blob/master/LICENSE)
Copyright 2010, 2012 Adobe Systems Incorporated (http://www.adobe.com/), with Reserved Font Name 'Source'. All Rights Reserved. Source is a trademark of Adobe Systems Incorporated in the United States and/or other countries.
This Font Software is licensed under the SIL Open Font License, Version 1.1.
This license is copied below, and is also available with a FAQ at:
Some files were not shown because too many files have changed in this diff
Show More
Reference in New Issue
Block a user
Blocking a user prevents them from interacting with repositories, such as opening or commenting on pull requests or issues. Learn more about blocking a user.
