mdbook-snips

A mdbook preprocessor to add // --snip-- (or similar) before all "blocks" of hidden lines in rust blocks in a mdbook, making it very clear that there is some hidden code there.

(mdbook calls them boring lines).

Example:

Before:

# fn f();
#
fn g();

fn main() {
#     f();
    g();
}

After:

// --snip--
# fn f();
# 
fn g();

fn main() {
    // --snip--
#     f();
    g();
}

To get a feeling of what it looks like, the robespierre book uses this.

Usage:

cargo install mdbook-snips

Then in the book.toml of your book:

[preprocessors.mdbook-snips]
command = "mdbook-snips"

Default configuration:

# book.toml
[preprocessors.mdbook-snips]
command = "mdbook-snips"
for_imports = true
for_end_of_block = false
snip_text = "// --snip--"

• for_imports Emits a // --snip-- if the first line of the boring "block" is an import (e.g. starts with the exact string "use ")

• for_end_of_block Emits a // --snip-- if the last line of the boring "block" ends on the last line of syntax highlighting block, e.g. for:

\```rust
fn main() {

}

# fn f() {}
\```

With for_end_of_block=true, it ends up as:

\```rust
fn main() {

}

// --snip--
# fn f() {}
\```

But with for_end_of_block=false, it doesn't change:

\```rust
fn main() {

}

# fn f() {}
\```

• snip_text If you want to change the // --snip-- text to something else, you can.

For example, you can use a block comment: snip_text="/* --snip-- */"

Which, for:

# fn f() {}

fn main() {}

Will give you:

/* --snip-- */
# fn f() {}

fn main() {}

Rules of thumb

• Prefer having hidden blocks of code at least 1 always-visible line away from any other visible code, unless imports, or first or last lines of blocks.

E.g. prefer this:

# fn f() {}

fn main() {
#     let a = f();

    let b = 1;
}

Instead of this:

# fn f() {}
fn main () {
#     let a = f();
    let b = 1;
}

• I would also recommend setting for_imports=false

• Have an empty line between uses and all the other items in a block. With for_imports=false, the other items might get hiddden. Remember for_imports only looks if the first line starts with "use ".

License

mdbook-snips is distributed under the terms of both the MIT license and the Apache License (Version 2.0).

See the LICENSE-APACHE and LICENSE-MIT files in this repository for more information.