markdown-gem，又称 gem - Markdown 代码块执行器

灵感来自 R Markdown 代码块，但适用于任何代码。

我们的目标是使 MD 文件中的 Markdown 文档、示例、说明或与代码相关的任何内容可验证、易于维护，并将其集成到您的 CI 流水线中。

安装

来自 crates.io

您需要安装并更新 Rust 开发环境。

安装完成后，使用 cargo 安装 lfs

cargo install markdown-gem

从源代码安装

您需要安装 Rust 开发环境。

获取 murabi-io/markdown-gem 仓库，移动到 markdown-gem 目录，然后运行

git clone git@github.com:murabi-io/markdown-gem.git
cd markdown-gem
cargo install --path .

为什么使用 markdown-gem

• 自动化 和 文档化 同时进行
• 维护 您的文档并确保示例是可工作的
• 提升 您的用户体验

代码块

代码块是您 Markdown 文档的一部分，您希望它被执行，例如。

```sh {sys=[linux], linux_distro=[debian]}
apt install ...
```

上面的代码块定义了一个使用 apt 安装某个内容的 Shell 脚本，它只会在 Debian 家族的 Linux 系统上运行。代码块元数据通常会被大多数渲染器和用户忽略，用户将只看到包含 apt... 部分的 Shell 代码。

属性和过滤器

代码块的属性为执行器提供了如何运行代码的信息，而过滤器定义了何时不运行它。

可用的属性

• * 通过代码块语言属性实现的默认命令将使此属性可选
• ** allow_errors 的功能尚未实现
• *** sudo支持尚未提供，您仍然可以在sudo下执行gem，但请注意，所有代码块都将继承sudo权限

可用过滤器

安全

代码块在主机机器上执行，无需任何预检查，形式如markdown文档中提供。执行通过tokio::process::Command，详细文档可以在这里找到：[tokio::process::Command](https://docs.rs/tokio/latest/tokio/process/struct.Command.html)。

您应将运行代码块视为运行任何其他shell脚本，并注意所有固有的风险。

许可和致谢

实现基于termimad和其他几个项目。我要感谢Denys Séguret和crossterm-rs的工作，以及我作为灵感使用的现有开源代码。