3 个版本
| 0.1.0 | 2022年11月29日 |
|---|---|
| 0.1.0-rc.2 | 2022年11月28日 |
#63 in #executor
2.5MB
1.5K SLoC
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 [email protected]: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 代码。
属性和过滤器
代码块的属性为执行器提供了如何运行代码的信息，而过滤器定义了何时不运行它。
可用的属性
| 属性 | 类型 | 可选/默认 | 描述 |
|---|---|---|---|
| cmd | 字符串 | no* | 命令名称或路径，例如 sh、node 等。 |
| args | 参数数组 | yes | 命令参数 |
| path | 字符串 | yes | PATH 环境变量用于命令 |
| as_file | 布尔值 | yes/true | 确定 markdown-gem 是否应将代码块作为文件执行，默认 true |
| stdout | 布尔值 | yes/true | 确定 markdown-gem 是否应显示代码块的 stdout，默认 true |
| allow_warnings | 布尔值 | yes/true | 确定 markdown-gem 是否应允许警告，默认 true |
| allow_errors** | 布尔值 | yes/false | 确定markdown-gem是否应该允许错误，默认值为 true |
| with_sudo*** | 布尔值 | yes/false | 指示markdown-gem以sudo运行代码块 |
- * 通过代码块语言属性实现的默认命令将使此属性可选
- **
allow_errors的功能尚未实现- *** sudo支持尚未提供，您仍然可以在sudo下执行
gem，但请注意，所有代码块都将继承sudo权限
可用过滤器
| 过滤器 | 类型 | 可选/默认 | 包含/排除 | 描述 |
|---|---|---|---|---|
| sys | 字符串数组 | 是/[] | 包含 | os系统过滤器，可能的值：linux、macos、ios、freebsd、dragonfly、netbsd、openbsd、solaris、android、windows |
| arch | 字符串数组 | 是/[] | 包含 | 系统架构过滤器，可能的值：x86、x86_64、arm、aarch64、m68k、mips、mips64、powerpc、powerpc64、riscv64、s390x、sparc64 |
| linux_distro | 字符串数组 | 是/[] | 包含 | Linux发行版过滤器，例如arch、debian等，从Linux发布ID_LIKE派生 |
安全
代码块在主机机器上执行，无需任何预检查，形式如markdown文档中提供。执行通过tokio::process::Command，详细文档可以在这里找到：[tokio::process::Command](https://docs.rs/tokio/latest/tokio/process/struct.Command.html)。
您应将运行代码块视为运行任何其他shell脚本，并注意所有固有的风险。
许可和致谢
实现基于termimad和其他几个项目。我要感谢Denys Séguret和crossterm-rs的工作，以及我作为灵感使用的现有开源代码。
依赖项
~13–27MB
~335K SLoC