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: ```rust

fn f();

# fn g();

fn main() {

f();

g();

} ```

After: ```rust // --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:

bash cargo install mdbook-snips

Then in the book.toml of your book:

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

Default configuration: ```toml

book.toml

[preprocessors.mdbook-snips] command = "mdbook-snips" forimports = true forendofblock = 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: ```rust

fn f() {}

fn main() {

let a = f();

let b = 1;

} ```

Instead of this: ```rust

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.