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:
# ;
#
;
After:
// --snip--
# ;
#
;
To get a feeling of what it looks like, the robespierre book uses this.
Usage:
Then in the book.toml
of your book:
[]
= "mdbook-snips"
Default configuration:
# book.toml
[]
= "mdbook-snips"
= true
= false
= "// --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:
#
Instead of this:
#
-
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. Rememberfor_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.