Module book 

The book check: hygiene book [DIR] builds the book and fails when it has a missing include or anchor, or when the build changes a tracked file.

Design

mdbook does not fail on a bad include. For a missing file it prints an ERROR line, leaves the include line in the text, and exits 0. For a missing anchor it prints nothing and renders an empty code block. So hygiene book runs mdbook build, then checks the log and each page (01M3T5MG7VVYG4A8YBM75FGSMB):

Rule	Finds
mdbook	An ERROR line in the log of mdbook.
include	An include line, {{#...}}, that mdbook left in the text of a page, outside a code block.
empty-code	A code block with no text. A missing anchor gives one.
tracked	A tracked file that the build changed.

An example of an include in a code block of the book is escaped, as \{{#include file.rs:name}}. mdbook shows it as text in the code block. The include rule skips each code block, so it skips the example. mdbook also leaves a missing file of a code block as text in the block, so only the ERROR line shows that one.

let page = "<p>See {{#include gone.rs}}.</p>\n<pre><code></code></pre>";
let rules: Vec<_> = hygiene::book::check_page("a.html", page)
    .into_iter()
    .map(|e| e.rule)
    .collect();
assert_eq!(rules, ["include", "empty-code"]);

let example = "<pre><code class=\"language-text\">{{#include a.rs:x}}\n</code></pre>";
assert!(hygiene::book::check_page("a.html", example).is_empty());

The theme and the tracked files

The theme of the book, DIR/gruvbox, is not in git. hygiene book installs it with mdbook-gruvbox install DIR when book.toml names it (uses_theme) and the directory is missing. A new version of that tool also writes book.toml. book.toml is the decision of the repository, so hygiene book puts its bytes back after the install (01M3W5YW0172EVF2JA8T7WW392).

The build must not change a tracked file: a session can commit the change with its item by mistake. hygiene book reads the tracked files that differ from HEAD before the install and after the build (Tracked), and check_tracked compares the two. So a file that a person changed before the build passes, and a file that the build changed fails. A directory outside a git repository has no tracked file.

use hygiene::book::{check_tracked, Tracked};

let before = Tracked::from([("src/a.rs".to_owned(), "1".to_owned())]);
let mut after = before.clone();
assert!(check_tracked(&before, &after).is_empty());

after.insert("docs/book.toml".to_owned(), "2".to_owned());
let errors = check_tracked(&before, &after);
assert_eq!(errors.len(), 1);
assert_eq!(errors[0].rule, "tracked");
assert!(errors[0].text.starts_with("docs/book.toml: "));

Functions

check_log

An mdbook error for each ERROR line of the log of mdbook.

check_page

The include and empty-code errors of one page of the book. name names the page in each error, with the line.

check_tracked

A tracked error for each tracked file that differs between before and after: a file that only one of them has, or a file with two different marks.

uses_theme

True when book_toml, the text of a book.toml, names a file of the theme directory gruvbox.

Type Aliases

Tracked

The tracked files that differ from HEAD: the path of each file from the top of the repository, and a mark of its content. Two marks are equal when the content is the same.