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.
* Fix: Scroll sidebar to current active section (#1067)
* Clean: Some code related to PR #1052
* Change `scrollIntoViewIfNeeded` with `scrollIntoView`
* Don't use onload event for sidebar scroll to reduce flickering.
Co-authored-by: 李鸿章 <poodll@163.com>
I noticed that the CI badge was failing and it seems to be caused by the fact that it reflects the latest build including PRs. This change filters the events to only "push events on the master branch" so the badge stays green even if a PR fails.
* ui: improve menu folding
Fold/unfold the menu bar just by the amount of scroll, not by its
full width
* refactor: use a variable for the menu bar height
* Fix menu scroll jittering, remove hover folding smoothness
Rewrite it to use `position:` `sticky` and `relative` instead
of continuous programmatic position changes
On-hover folding-unfolding transition removal is a side-effect
This prevents recursive copy-loops when the destination directory
is contained in the source directory.
Now it bails out with a descriptive error message.
Html page title for every chapter in the book is created by the following code:
```rust
let title: String;
{
let book_title = ctx
.data
.get("book_title")
.and_then(serde_json::Value::as_str)
.unwrap_or("");
title = ch.name.clone() + " - " + book_title;
}
```
If the `book.toml` file is missing, and `book_title` parameter is empty, there's an awkward ` - ` string hanging at the end of each chapter's title.
This PR adds a `match` case to handle that kind of situation.
* Using .to_lowercase() on the theme matching to avoid needed exact capitolization in the book.toml
* Changed the default-dark-theme from .to_string() to .to_lowercase() to match theme
Doing what it says results in:
```
2019-11-04 16:13:15 [WARN] (mdbook::renderer::html_handlebars::hbs_renderer): Previous versions of mdBook erroneously accepted `./src/theme` as an automatic theme directory
2019-11-04 16:13:15 [WARN] (mdbook::renderer::html_handlebars::hbs_renderer): Please move your theme files to `./theme` for them to continue being used
```
This replaces the only use of px for font-sizes by setting up a base
rem size on the root element in a way that is easy to calculate (1 rem =
10px) and scaling up according to browser settings.
* Option to display copy buttons.
- Added field to playpen data structure
- Communicate through window.playpen_copyable
- Javascript updated to check before displaying copy buttons.
* html -> html_config
Also:
- update description of copyable in source code.
- update description of line_numbers (my last PR to this repository)
* Allow underscores in the link type name
* Add some tests for include anchors
* Include parts of Rust files and hide the rest
Fixes#618.
* Increase min supported Rust version to 1.35
* Add a test for a behavior of rustdoc_include I want to depend on
At first I thought this was a bug, but then I looked at some use cases
we have in TRPL and decided this was a feature that I'd like to use.
* Added support for gitignore files.
The watch command will now ignore files based on gitignore. This can be useful for when your editor creates cache or swap files.
* Ran cargo fmt.
* Made the code a bit tidier based on input from other Rust programmers.
Changed the type of the closure back to use PathBuf, not &PathBuf.
Reduced nesting.
- Added line numbers to config struct
- Added playpen_line_numbers field to hbs renderer.
- Added section to set `window.playpen_line_numbers = true` in page template
- Use line number global variable to show line numbers when required.
Use case: when trying to `mdbook test` a file that has many `include`
directives, and a test fails, the line numbers in the `rustdoc` output
don't match the line numbers in the original markdown file.
Turning on the markdown renderer implemented here lets you see what is
being passed to `rustdoc` by saving the markdown after the preprocessors
have run.
This renderer could be helpful for debugging many preprocessors, but
it's probably not useful in the general case, so it's turned off by
default.
* Extract the concept of a link having a range or anchor specified
So that other kinds of links can use this concept too.
* Extract a function for parsing range or anchor
This eliminates some duplication and will enable different kinds of
LinkTypes to have line number ranges.
Implement `From` for the std `Range` types to enable easier
construction.
The new code reaaalllly makes me wish for a delegation mechanism though
:(
Changing `cargo install` to `cargo install --path .` prevents the following error:
<span style="color: red;">error:</span> Using `cargo install` to install the binaries for the package in current working directory is no longer supported, use `cargo install --path .` instead. Use `cargo build` if you want to simply build the package.
* Rename a variable from playpen to link
Links can now be more than only playpen links
* Rename a field to match the enum type it holds
Also so that link.link.stuff doesn't happen when a variable link holds a
Link instance
* Update to pulldown-cmark 0.4.1.
* Update to pulldown-cmark 0.5.2.
* Remove pulldown-cmark-to-cmark dependency.
Since it is not compatible with the new pulldown-cmark. This example isn't
directly usable, anyways, and I think the no-op example sufficiently shows how
to make a preprocessor.
* cargo fmt
* Fix example link.
Updates to v9.15.8.
My main motivation is to fix a minor issue with TOML highlighting.
This keeps the same language list as before with the addition of a new "common"
language `properties` and added `julia` because someone asked for it and I like
julia. The full list from building:
:common armasm d go handlebars haskell julia rust scala swift x86asm yaml
- apache
- armasm
- bash
- coffeescript
- cpp
- cs
- css
- d
- diff
- go
- xml
- handlebars
- haskell
- http
- ini
- java
- javascript
- json
- julia
- makefile
- markdown
- nginx
- objectivec
- perl
- php
- properties
- python
- ruby
- rust
- scala
- shell
- sql
- swift
- x86asm
- yaml
This should fix deploying release artifacts and gh-pages for the documentation.
Secrets should now be configured in the UI for travis and appveyor.
This also removes some of the appveyor jobs, since they aren't really
necessary, and there are limited jobs on rust-lang-libs.
* Add if around stub summary creation
Check if an existing SUMMARY.md is present to prevent overwriting it
with the stub SUMMARY.md.
[#832]
* Add test for existing SUMMARY.md
Change overflow-x from auto to initial.
This resolves weird rendering behavior in Chrome and Safari on macOS.
With help from @bash
Co-authored-by: Ruben Schmidmeister <ruben.schmidmeister@icloud.com>
This is useful for situations where you'd like to
supplement or replace the existing Summary parsing with
custom filesystem traversal code or other similar changes.
The deploy scripts require TARGET env var to be set, but it wasn't set anywhere, causing it to fail: https://travis-ci.com/rust-lang-nursery/mdBook/builds/97850452.
This also reduces the number of mac builders, since they aren't necessary, and capacity is limited.
The api key will likely need to be updated, too, since the transition to travis.com.
Appveyor also seems to be broken, but I suspect it is also a key issue.
The livereload url was using an unknown property "websocket-address" instead of "websocket-hostname", hence it was always fallback onto the hostname (which can be different).
Previously, additional JavaScript files inside a directory were
correctly copied (with their parent created), but the link to it was
stripped of that parent.
There's no need for that (and it was not done for CSS)
* The preprocessor trait now returns a modified book instead of editing in place
* A preprocessor is told which render it's running for
* Made sure preprocessors get their renderer's name
* Users can now manually specify whether a preprocessor should run for a renderer
* You can normally use default preprocessors by default
* Got my logic around the wrong way
* Fixed the `build.use-default-preprocessors` flag
This class will supress the "play" button in the html backend (which you
can also do with the "ignore" class), but it will still let the code be
tested via `mdbook test` (which is not possible with the "ignore" class).
This is useful for code examples that don't really do much (and so the
user doesn't gain much from running them), but as an author you still
want to test them to guard against syntax errors and typos and the like.
This allows the search index to be loaded asynchronously, and should
use fewer resources as it doesn't have to execute the JS.
JS loading is kept as a fallback for CORS issues with file:// URIs in Chrome.
This adds instructions for building and testing books in CI on every PR and
push, as well as instructions for how to automatically deploy to gh-pages on
successful CI runs on `master`.
Fixes#714
* Add index preprocessor
README.md is a de facto index file in markdown-based documentation.
Hence, we respect to README.md and convert it into index.html.
* Fix warning for unused variables
* Update tests for config
* Match file stem case-insensitively for IndexPreprocessor
* Add tests for IndexPreprocessor
* Update book example to fit index preprocessor
* Update print styles for new sidebar behavior
* Hide copy icons in print output
* Wait for mathjax rendering to complete before printing
* Remove old wrapping css
Browsers this old are already hilariously broken, so we don't need these fallbacks.
* Change mathjax script type
Chrome won't execute this if it's not marked as js
* Ensure page has rendered before printing
In certain situations Chrome willl fire window.onLoad before it's
done rendering. Add a 100ms delay to work around this.
The reader should not be assumed male; I'm a developer and user,
I'm not male. Makes documentation's language gender neutral to
make it more welcoming to people that do not use he/him pronouns.
* Don't hide page content when displaying search
* Decrease sidebar animation time
* Fix search key event handler
which wasn't completely de-jqueryified.
* Avoid reflowing page content on small screens
This reduces jank caused by reflowing the page text while animating the
sidebar, and it looks nicer.
* Don't use HTMLParentNode.prepend()
since edge doesn't support it yet
* Don't animate menu border bottom color
since it's the same color as the background, which isn't animated.
* Small CSS improvments
- Remove invalid `pointer: cursor` style
- Disable transitions for noscript to stop page from spazzing on every load
- Add `cursor: pointer` to mark
- Disable `cursor: pointer` on noscript menu-title
* JS fixes
- Load MathJax async
- Always use local fontawesome and clipboard.js
- Move js class to html element to make theme switching easier
* Give the print button a bit more margin
* Use `git config` to get author name in `mdbook init`
* Return `None` if `git` command fails
* Use `.ok()?` to convert from Result to Option and return early if `None`
* Add search with elasticlunr.js
This commit adds search functionality to mdBook, based on work done by @phaiax. The in-browser search code uses elasticlunr.js to execute the search, using an index generated at book build time by elasticlunr-rs.
* Add generator comment
Someone on Reddit was wondering how the rust book was generated and said they checked the source. Thought I'd put this here. Might be a good idea to have a little footer "made with mdBook", but this'll do for now.
* Remove search/editor file override behavior
* Use for loop for book iterator
* Improve HTML regex
* Fix search CORS in file URIs
* Use ammonia to sanitize HTML
* Filter html5ever log messages
* First version of preprocessor example, with quicli
It seems it's not worth it right now.
* Remove quicli, just to simplify everything
* Finish de-emphasise example
* Finish preprocessor example in book
* Rename preprocessor type
* Apply changes requested in review
* Update preprocessor docs with latest code
[skip CI]
* feat(theme/index): Assume the sidebar is initially visible
In case the inline script does not execute, the fallback is to show the sidebar.
* feat(theme/index): Hide sidebar toggle and theme selector buttons when JavaScript is disabled
Makes no sense to show them in this case since they do not work.
* update documentation
Update README.md and User Guide to reflect addition of `clean`
subcommand. Do minor spelling fixes too.
* fix grammar in `clean` documentation
* fix(theme/book/themes): Check for control keys in event listener
* fix(theme/index): Menu role for theme selector
* fix(theme/book/themes): Handle focus when toggling theme list
* feat(theme/book/themes): Handle ArrowUp, ArrowDown, Home and End
> A position fixed left navigation bar does not want to hand off scrolling to the document because a scroll gesture performed on the navigation bar is almost never meant to scroll the document. In this case, the author can use contain on the sidebar to prevent scrolling from being chained to the parent document element.
https://wicg.github.io/overscroll-behavior/#motivating-examples
* Add docs for mdBook specific include feature.
Also:
* Fix bug in take_lines taking `end`-many lines instead of
`end-start` many.
* Handle special case `include:number` as including a single line.
* Start counting lines at 1 and not 0.
* Merge mdBook and rust specific features into one chapter.
* Handle input path with regards to custom css
Before, when someone like the Reference set their extra css as
"theme/reference.css" in their book.toml, this path would be treated as
relative to the invocation of mdbook, and not respect the input path. This
PR modifies these relative paths to do so.
Fixes the build of https://github.com/rust-lang/rust/pull/47753 which
blocks updating rustc to mdbook 0.1
* don't use file-name
the style name is theme/reference.css, this results in a Err(StripPrefixError(())), which means that we push only the file_name, losing the theme bit
Tested this on macOS with VoiceOver, and it does not pick up the title as the text of the button. Kind of makes sense, since title and aria-label are not the same. This will make sure that the buttons and links are labeled properly.
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:
@@ -41,44 +49,192 @@ 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
### Making changes to the style
We love code quality and Rust has some excellent tools to assist you with contributions.
mdBook doesn't use CSS directly but uses [Stylus](http://stylus-lang.com/), a CSS-preprocessor which compiles to CSS.
### Formattingcode with rustfmt
When you want to change the style, it is important to not change the CSS directly because any manual modification to
the CSS files will be overwritten when compiling the stylus files. Instead, you should make your changes directly in the
[stylus files](https://github.com/rust-lang-nursery/mdBook/tree/master/src/theme/stylus) and regenerate the CSS.
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.
For this to work, you first need [Node and NPM](https://nodejs.org/en/) installed on your machine.
Then run the following command to install both [stylus](http://stylus-lang.com/) and [nib](https://tj.github.io/nib/), you might need `sudo` to install successfully.
[rustfmt](https://github.com/rust-lang/rustfmt) has a lot more information on the project.
The quick guide is
```
npm install -g stylus nib
1. Install it (`rustfmt` is usually installed by default via [rustup](https://rustup.rs/)):
```
rustup component add rustfmt
```
1. You can now run `rustfmt` on a single file simply by...
```
rustfmt src/path/to/your/file.rs
```
... or you can format the entire project with
```
cargo fmt
```
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
[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
```
rustup component add clippy
```
2. Running clippy
```
cargo clippy
```
## Change requirements
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
```
When that finished, you can simply regenerate the CSS files by building mdBook with the following command:
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:
1. `git fetch upstream`
2. `git checkout -B bump-version upstream/master`
3. `cargo xtask bump <BUMP>`
- This will update the version of all the crates.
- `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:
**mdBook** is a command line tool and Rust crate to create books using Markdown files. It's very similar to Gitbook but written in [Rust](http://www.rust-lang.org).
What you are reading serves as an example of the output of mdBook and at the same time as a high-level documentation.
mdBook is free and open source, you can find the source code on [Github](https://github.com/rust-lang-nursery/mdBook). Issues and feature requests can be posted on the [Github Issue tracker](https://github.com/rust-lang-nursery/mdBook/issues).
## API docs
Alongside this book you can also read the [API docs](https://docs.rs/mdbook/*/mdbook/) generated by Rustdoc if you would like to use mdBook as a crate or write a new renderer and need a more low-level overview.
## License
mdBook, all the source code, is released under the [Mozilla Public License v2.0](https://www.mozilla.org/MPL/2.0/)
mdBook can be used either as a command line tool or a [Rust crate](https://crates.io/crates/mdbook).
Let's focus on the command line tool capabilities first.
## Install
### Pre-requisite
mdBook is written in **[Rust](https://www.rust-lang.org/)** and therefore needs to be compiled with **Cargo**, because we don't yet offer ready-to-go binaries. If you haven't already installed Rust, please go ahead and [install it](https://www.rust-lang.org/downloads.html) now.
### Install Crates.io version
Installing mdBook is relatively easy if you already have Rust and Cargo installed. You just have to type this snippet in your terminal:
```bash
cargo install mdbook
```
This will fetch the source code from [Crates.io](https://crates.io/) and compile it. You will have to add Cargo's `bin` directory to your `PATH`.
Run `mdbook help` in your terminal to verify if it works. Congratulations, you have installed mdBook!
### Install Git version
The **[git version](https://github.com/rust-lang-nursery/mdBook)** contains all the latest bug-fixes and features, that will be released in the next version on **Crates.io**, if you can't wait until the next release. You can build the git version yourself. Open your terminal and navigate to the directory of you choice. We need to clone the git repository and then build it with Cargo.
There is some minimal boilerplate that is the same for every new book. It's for this purpose that mdBook includes an `init` command.
The `init` command is used like this:
```bash
mdbook init
```
When using the `init` command for the first time, a couple of files will be set up for you:
```bash
book-test/
├── book
└── src
├── chapter_1.md
└── SUMMARY.md
```
- The `src` directory is were you write your book in markdown. It contains all the source files,
configuration files, etc.
- The `book` directory is where your book is rendered. All the output is ready to be uploaded
to a server to be seen by your audience.
- The `SUMMARY.md` file is the most important file, it's the skeleton of your book and is discussed in more detail in another [chapter](format/summary.html).
#### Tip & Trick: Hidden Feature
When a `SUMMARY.md` file already exists, the `init` command will first parse it and generate the missing files according to the paths used in the `SUMMARY.md`. This allows you to think and create the whole structure of your book and then let mdBook generate it for you.
#### Specify a directory
When using the `init` command, you can also specify a directory, instead of using the current working directory,
by appending a path to the command:
```bash
mdbook init path/to/book
```
## --theme
When you use the `--theme` argument, the default theme will be copied into a directory
called `theme` in your source directory so that you can modify it.
The theme is selectively overwritten, this means that if you don't want to overwrite a
specific file, just delete it and the default file will be used.
The `serve` command is useful when you want to preview your book. It also does hot reloading of the webpage whenever a file changes.
It achieves this by serving the books content over `localhost:3000` (unless otherwise configured, see below) and runs a websocket server on `localhost:3001` which triggers the reloads.
This preferred by many for writing books with mdbook because it allows for you to see the result of your work instantly after every file change.
#### Specify a directory
Like `watch`, `serve` can take a directory as argument to use instead of the
current working directory.
```bash
mdbook serve path/to/book
```
#### Server options
`serve` has four options: the http port, the websocket port, the interface to serve on, and the public address of the server so that the browser may reach the websocket server.
For example: suppose you had an nginx server for SSL termination which has a public address of 192.168.1.100 on port 80 and proxied that to 127.0.0.1 on port 8000. To run use the nginx proxy do:
```bash
mdbook server path/to/book -p 8000 -i 127.0.0.1 -a 192.168.1.100
```
If you were to want live reloading for this you would need to proxy the websocket calls through nginx as well from `192.168.1.100:<WS_PORT>` to `127.0.0.1:<WS_PORT>`. The `-w` flag allows for the websocket port to be configured.
#### --open
When you use the `--open` (`-o`) option, mdbook will open the book in your
your default web browser after starting the server.
#### --dest-dir
The `--dest-dir` (`-d`) option allows you to change the output directory for your book.
-----
***note:*** *the `serve` command has not gotten a lot of testing yet, there could be some rough edges. If you discover a problem, please report it [on Github](https://github.com/rust-lang-nursery/mdBook/issues)*
When writing a book, you sometimes need to automate some tests. For example, [The Rust Programming Book](https://doc.rust-lang.org/stable/book/) uses a lot of code examples that could get outdated.
Therefore it is very important for them to be able to automatically test these code examples.
mdBook supports a `test` command that will run all available tests in mdBook. At the moment, only one test is available:
*"Test Rust code examples using Rustdoc"*, but I hope this will be expanded in the future to include more tests like:
- checking for broken links
- checking for unused files
- ...
In the future I would like the user to be able to enable / disable test from the `book.toml` configuration file and support custom tests.
The `watch` command is useful when you want your book to be rendered on every file change.
You could repeatedly issue `mdbook build` every time a file is changed. But using `mdbook watch` once will watch your files and will trigger a build automatically whenever you modify a file.
#### Specify a directory
Like `init` and `build`, `watch` can take a directory as argument to use instead of the
current working directory.
```bash
mdbook watch path/to/book
```
#### --open
When you use the `--open` (`-o`) option, mdbook will open the rendered book in
your default web browser.
#### --dest-dir
The `--dest-dir` (`-d`) option allows you to change the output directory for your book.
-----
***note:*** *the `watch` command has not gotten a lot of testing yet, there could be some rough edges. If you discover a problem, please report it [on Github](https://github.com/rust-lang-nursery/mdBook/issues)*
mdBook has optional support for math equations through [MathJax](https://www.mathjax.org/).
To enable MathJax, you need to add the `mathjax-support` key to your `book.toml` under the `output.html` section.
```toml
[output.html]
mathjax-support=true
```
>**Note:**
The usual delimiters MathJax uses are not yet supported. You can't currently use `$$ ... $$` as delimiters and the `\[ ... \]` delimiters need an extra backslash to work. Hopefully this limitation will be lifted soon.
### Inline equations
Inline equations are delimited by `\\(` and `\\)`. So for example, to render the following inline equation \\( \int x dx = \frac{x^2}{2} + C \\) you would write the following:
```
\\( \int x dx = \frac{x^2}{2} + C \\)
```
### Block equations
Block equations are delimited by `\\[` and `\\]`. To render the following equation
There is a feature in mdBook that let's you hide code lines by prepending them with a `#`.
```bash
# fn main() {
letx= 5;
lety= 6;
println!("{}", x + y);
# }
```
Will render as
```rust
#fnmain(){
letx=5;
lety=7;
println!("{}",x+y);
#}
```
## Inserting runnable Rust files
With the following syntax, you can insert runnable Rust files into your book:
```hbs
\{{#playpenfile.rs}}
```
The path to the Rust file has to be relative from the current source file.
When play is clicked, the code snippet will be send to the [Rust Playpen] to be compiled and run. The result is send back and displayed directly underneath the code.
The summary file is used by mdBook to know what chapters to include,
in what order they should appear, what their hierarchy is and where the source files are.
Without this file, there is no book.
Even though `SUMMARY.md` is a markdown file, the formatting is very strict to
allow for easy parsing. Let's see how you should format your `SUMMARY.md` file.
#### Allowed elements
1.***Title*** It's common practice to begin with a title, generally
<codeclass="language-markdown"># Summary</code>.
But it is not mandatory, the parser just ignores it. So you can too
if you feel like it.
2.***Prefix Chapter*** Before the main numbered chapters you can add a couple of elements that will not be numbered. This is useful for
forewords, introductions, etc. There are however some constraints. You can not nest prefix chapters, they should all be on the root level. And you can not add prefix chapters once you have added numbered chapters.
```markdown
[Title of prefix element](relative/path/to/markdown.md)
```
3. ***Numbered Chapter*** Numbered chapters are the main content of the book, they will be numbered and can be nested,
resulting in a nice hierarchy (chapters, sub-chapters, etc.)
```markdown
- [Title of the Chapter](relative/path/to/markdown.md)
```
You can either use `-` or `*` to indicate a numbered chapter.
4.***Suffix Chapter*** After the numbered chapters you can add a couple of non-numbered chapters. They are the same as prefix chapters but come after the numbered chapters instead of before.
All other elements are unsupported and will be ignored at best or result in an error.
In addition to providing runnable code playpens, mdBook optionally allows them to be editable. In order to enable editable code blocks, the following needs to be added to the ***book.toml***:
```toml
[output.html.playpen]
editable=true
```
To make a specific block available for editing, the attribute `editable` needs to be added to it:
Note the new `Undo Changes` button in the editable playpens.
## Customizing the Editor
By default, the editor is the [Ace](https://ace.c9.io/) editor, but, if desired, the functionality may be overriden by providing a different folder:
```toml
[output.html.playpen]
editable = true
editor = "/path/to/editor"
```
Note that for the editor changes to function correctly, the `book.js` inside of the `theme` folder will need to be overriden as it has some couplings with the default Ace editor.
For syntax highlighting I use [Highlight.js](https://highlightjs.org) with a custom theme.
Automatic language detection has been turned off, so you will probably want to
specify the programming language you use like this
<pre><codeclass="language-markdown">```rust
fn main() {
// Some code
}
```</code></pre>
## Custom theme
Like the rest of the theme, the files used for syntax highlighting can be overridden with your own.
- ***highlight.js*** normally you shouldn't have to overwrite this file, unless you want to use a more recent version.
- ***highlight.css*** theme used by highlight.js for syntax highlighting.
If you want to use another theme for `highlight.js` download it from their website, or make it yourself,
rename it to `highlight.css` and put it in `src/theme` (or the equivalent if you changed your source folder)
Now your theme will be used instead of the default theme.
## Hiding code lines
There is a feature in mdBook that let's you hide code lines by prepending them with a `#`.
```bash
# fn main() {
let x = 5;
let y = 6;
println!("{}", x + y);
# }
```
Will render as
```rust
# fn main() {
let x = 5;
let y = 7;
println!("{}", x + y);
# }
```
**At the moment, this only works for code examples that are annotated with `rust`. Because it would collide with semantics of some programming languages. In the future, we want to make this configurable through the `book.toml` so that everyone can benefit from it.**
## Improve default theme
If you think the default theme doesn't look quite right for a specific language, or could be improved.
Feel free to [submit a new issue](https://github.com/rust-lang-nursery/mdBook/issues) explaining what you have in mind and I will take a look at it.
You could also create a pull-request with the proposed improvements.
Overall the theme should be light and sober, without to many flashy colors.
The default renderer uses a [handlebars](http://handlebarsjs.com/) template to render your markdown files and comes with a default theme
included in the mdBook binary.
The theme is totally customizable, you can selectively replace every file from the theme by your own by adding a
`theme` directory next to `src` folder in your project root. Create a new file with the name of the file you want to override
and now that file will be used instead of the default file.
Here are the files you can override:
- ***index.hbs*** is the handlebars template.
- ***book.css*** is the style used in the output. If you want to change the design of your book, this is probably the file you want to modify. Sometimes in conjunction with `index.hbs` when you want to radically change the layout.
- ***book.js*** is mostly used to add client side functionality, like hiding / un-hiding the sidebar, changing the theme, ...
- ***highlight.js*** is the JavaScript that is used to highlight code snippets, you should not need to modify this.
- ***highlight.css*** is the theme used for the code highlighting
- ***favicon.png*** the favicon that will be used
Generally, when you want to tweak the theme, you don't need to override all the files. If you only need changes in the stylesheet,
there is no point in overriding all the other files. Because custom files take precedence over built-in ones, they will not get updated with new fixes / features.
**Note:** When you override a file, it is possible that you break some functionality. Therefore I recommend to use the file from the default theme as template and only add / modify what you need. You can copy the default theme into your source directory automatically by using `mdbook init --theme` just remove the files you don't want to override.
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.
