#mdbook #line #hidden #marker #blocks #snip #boring

bin+lib mdbook-snips

Markers for hidden lines in rust blocks within an mdbook

3 releases

0.1.3 Sep 9, 2021
0.1.2 Sep 8, 2021
0.1.0 Sep 4, 2021

#1654 in Text processing

MIT/Apache

23KB
447 lines

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.

Dependencies

~12–24MB
~340K SLoC