mdbook-template

一个允许模板文件具有动态参数的重用性的mdbook预处理器

[!IMPORTANT] 此包不再积极维护。我最初创建这个包是因为我积极使用mdBook为我的网站，但现在不再这样做，并且觉得很难激发自己为这个项目工作的动力。

目录

• 作者注释
• 安装
• 关于
• 格式
  • 模板
  • 参数
  • 默认值
• 有效配置
  • 模板
  • 参数
• 示例
• GitHub Actions
• 许可证
• 贡献
• 致谢

作者注释

我在Rust技能方面还是个初学者，所以我很确定...可能在这个预处理器中存在边缘情况。

安装

通过Cargo安装

$ cargo install mdbook-template

将以下行添加到您的 book.toml

[preprocessor.template]

一切就绪 :D
继续正常构建您的mdbook！

$ mdbook build

关于

给定以下目录结构

book.toml
src
├── rust.md
├── go.md
├── friends
│   └── hazel.md
├── images
│   ├── ferris.png
│   └── corro.png
└── SUMMARY.md

如果我们想在所有文件中包含图像 ferris.png 和 corro.png，我们不得不在每份文件中复制相同的Markdown/代码片段，并将唯一的路径设置回 images/ 目录。

这就是 mdbook-template 通过引入 {{#template ...} 功能来帮助的地方。

基于mdbook的 {{#include ... }} 功能，mdbook-template 允许您使用熟悉的语法来包含文件，同时传递参数以允许动态生成文本。

请查看提供的 示例 以了解其实际应用。

格式

模板

格式如下

        1             2           3
    {{#template     <file>      <args>}}

1. 标识符，告诉 mdbook-template 该文本应替换为模板
2. 模板文件的 相对路径
3. 需要在模板文件中替换的任何参数。参数应通过空格分隔，并应采用 key=value 格式。

参数

需要在模板文件中替换的参数应包含在 [[# ...]]
格式如下

     1
[[#<name>]]

1. 参数的名称

默认值

可以为需要动态参数而其他文件不需要的文件设置默认值。
格式如下

      1          2
[[#<name> <default-value>]]

1. 参数的名称
2. 该参数应具有的默认值

有效配置

模板配置

{{#template file.txt path=../images author=Goudham}}

{{#template
    file.txt
    path=../images
    author=Goudham
}}

// Not recommended but valid
{{#template     file.txt   path=../images author=Goudham}}

// Not recommended but valid
{{#template
file.txt
        path=../images
    author=Goudham
}}

参数配置

\[[#escaped]]

[[#width]]

[[#width 200px]]

// Not recommended but valid
[[   #width   400px   ]]

示例

给定以下目录

book.toml
src
├── rust.md
├── go.md
├── friends
│   └── hazel.md
├── images
│   ├── ferris.png
│   └── corro.png
├── templates
│   └── footer.md
└── SUMMARY.md

以及以下内容

templates/footer.md

-- Designed By [[#authors]] --
![ferris]([[#path]]/ferris.png)
![corro]([[#path]]/corro.png)

rust.md

# Rust

Some Content...

{{#template templates/footer.md authors=Goudham, Hazel path=images}}

go.md

# Go

Some Content...

{{#template templates/footer.md path=images authors=Goudham, Hazel}}

friends/hazel.md

# Hazel

Some Content...

{{#template ../templates/footer.md path=../images authors=Goudham, Hazel }}

在启用 mdbook-template 预处理器后运行 mdbook build，文件将具有动态图像路径并包含 相同 的内容。

rust.md

# Rust

Some Content...

-- Designed By Goudham, Hazel --
![ferris](images/ferris.png)
![corro](images/corro.png)

go.md

# Go

Some Content...

-- Designed By Goudham, Hazel --
![ferris](images/ferris.png)
![corro](images/corro.png)

friends/hazel.md

# Hazel

Some Content...

-- Designed By Goudham, Hazel --
![ferris](../images/ferris.png)
![corro](../images/corro.png)

更多示例包含在 examples 目录中，展示了各种用法。

GitHub Actions

如果需要将 mdbook-template 作为可执行文件来构建您的书籍，请在您的 .yml 工作流程文件中包含以下内容：

- name: Install mdbook-template
  run: |
    mkdir mdbook-template
    curl -sSL https://github.com/sgoudham/mdbook-template/releases/latest/download/mdbook-template-x86_64-unknown-linux-gnu.tar.gz | tar -xz --directory=./mdbook-template
    echo `pwd`/mdbook-template >> $GITHUB_PATH

上述步骤将确保获取并构建 mdbook-template 的最新版本。

许可证

MIT 许可证

贡献

首先，感谢您对参与此项目的兴趣！请在贡献之前阅读 CONTRIBUTING.md！

致谢

此预处理器主要基于 mdbook 自身的 links.rs 文件。如果没有 mdbook 已经实施的强大基础，我绝对无法构建出这样的东西。