mdbook-snips

mdbook 预处理器，在 mdbook 中 Rust 块的所有“块”之前添加 // --snip--（或类似内容），使其非常清楚地表明存在一些隐藏代码。

（mdbook 称其为无聊行）。

示例

之前

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

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

之后

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

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

为了了解其外观，robespierre 书使用了这个。

用法

cargo install mdbook-snips

然后在您的书的 book.toml 中

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

默认配置

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

• for_imports 如果无聊“块”的第一行是导入（例如，以字符串 "use " 开头），则发出 // --snip--

• for_end_of_block 如果无聊“块”的最后一行在语法高亮块的最后一行结束，则发出 // --snip--，例如

\```rust
fn main() {

}

# fn f() {}
\```

使用 for_end_of_block=true，它将变为

\```rust
fn main() {

}

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

但是，如果使用 for_end_of_block=false，则不会改变

\```rust
fn main() {

}

# fn f() {}
\```

• snip_text 如果您想将 // --snip-- 文本更改为其他内容，则可以。

例如，您可以使用块注释：snip_text="/* --snip-- */"

这将

# fn f() {}

fn main() {}

给您

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

fn main() {}

经验法则

• 最好让隐藏代码块至少有 1 行始终可见的代码与之隔开，除非是导入，或块的第一行或最后一行。

例如，首选此

# fn f() {}

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

    let b = 1;
}

而不是此

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

• 我还建议设置 for_imports=false

• 在块中使用和所有其他项目之间保留一个空行。使用 for_imports=false，其他项目可能会被隐藏。记住 for_imports 只会检查第一行是否以 "use " 开头。

许可证

mdbook-snips 以 MIT 许可证和 Apache 许可证（版本 2.0）的条款进行分发。

有关更多信息，请参阅此存储库中的 LICENSE-APACHE 和 LICENSE-MIT 文件。