`$ mdsh` - 一个 Markdown 预处理 shell

The mdsh 项目描述了一种 Markdown 语言扩展，可用于自动化 README.md 文件中的一些常见任务。我经常发现自己需要从其他文件中嵌入一段代码或 Markdown 片段。或者我想要展示某个命令的输出。在这两种情况下，都可以手动完成，但你只需要运行 mdsh 并让文件自动更新不就行了吗？

因此，该工具的目标首先是以一种自然的方式扩展 Markdown 的语法。即你可能输入的内容。如果运行了 mdsh 工具，相关的代码块就会就地更新。大多数其他工具会生成一个新文件，但我们真正想要的是一种幂等操作。

最终，这提供了一个类似于文学编程或 jupyer 笔记本的工具，但针对的是 shell 命令。它给文件增加了一些冗余，作为交换，它允许自动化刷新这些输出。

请参阅 ./spec.clear.md 和 ./spec.processed.md 的源代码，了解 mdsh 的所有功能。

用法

运行 mdsh --help

Markdown shell pre-processor. Never let your READMEs and tutorials get out of sync again.

Exits non-zero if a sub-command failed.

Usage: mdsh [OPTIONS]

Options:
  -i, --inputs <INPUTS>
          Path to the markdown files. `-` for stdin

          [default: ./README.md]

  -o, --output <OUTPUT>
          Path to the output file, `-` for stdout [defaults to updating the input file in-place]

  -w, --work-dir <WORK_DIR>
          Directory to execute the scripts under [defaults to the input file’s directory]

      --frozen
          Fail if the output is different from the input. Useful for CI.

          Using `--frozen`, you can guarantee that developers update documentation when they make a change. Just add `mdsh --frozen` as a check to your continuous integration setup.

      --clean
          Remove all generated blocks

  -h, --help
          Print help (see a summary with '-h')

  -V, --version
          Print version

`mdsh` command

mdsh 的 "Command" 由以下部分组成：

[langname] <out_cmd> <in_cmd> [data_line]
[data]

in_cmd 定义了如何以及从哪里获取数据，它可以是以下三种之一：

< — 按原样读取文件。文件路径来源于 data_line，如果 data 可用，则按行读取文件名，并将每个文件与上一个文件拼接。
$ — 命令执行。如果 data_line 可用，则作为 shell 命令执行。如果 data 可用，则通过 stdin 传递给命令（关闭 https://github.com/zimbatm/mdsh/issues/57）。如果只有 data 可用而 data_line 不可用，则 data 作为 shell 脚本执行。
"空命令" 即 "按原样使用数据"，拼接 data_line 和 data。实际上，这仅对设置环境变量有用

out_cmd 定义了如何处理来自 in_cmd 的数据，它可以是以下三种之一：

> lang — 生成带有 lang 的代码块（类似于当前的 as lang 语句）。
> — 生成由注释标签包围的原始 markdown 输出
! — 将数据展开为 shell 变量

使用这 3 * 3 个命令，你可以得到 9 种组合，例如：

> < include.md — 读取文件并生成原始 markdown
> py < script.py — 读取 script.py 并生成语言为 py 的代码块
> yml $ ./script.py foo $bar — 在 shell 中执行 script.py foo $bar 并生成 yml 代码块
>$ ./gen-md.py — 执行 gen-md.py 并生成原始 markdown
! foo=$bar — 将 foo=$bar 用作 "原始数据" 并展开环境变量，这些变量可用于后续的 shell 执行
!< .env — 读取 .env 并评估 shell 变量
!$ ./gen-vars.py — 执行 gen-vars 并将输出视为 shell 变量赋值列表

因此它可以完成很多事情，且底层模型相当简单，甚至允许做一些无用的事情，例如 > hello —— 会生成一个带有 hello 语言的空代码块。

容器

命令可以放入容器中，以下是所有容器：

行内代码块

必须从新行开始并以换行符结束。 langname 会被跳过，解析直接从 out_cmd 开始，不存在 data。

`>$ echo hi`

代码块

```[langname] <out_cmd> <in_cmd> [data_line]
[data]
```

源环境变量：

```env !
foo=$bar
```

执行脚本并生成 yaml 块（你甚至可以在顶部添加 shebang 并使用 bash 以外的脚本语言。

```sh > yaml $
echo 'foo: true'
```

将 data_line 作为单行命令运行，并通过 stdin 向其传递代码块，生成原始 markdown。

```> $ sed 's/.*/Hi, \0/'
Bobby
```

单行注释

类似于内联代码块，但处于隐藏状态：

`<!-- >< LICENSE.md -->` — includes LICENSE.md

多行注释块

行为与代码块类似，但不需要 langname

<!-- > yml $
echo 'hi: true'
-->

链接

这些与其余容器略有不同：

[<out_cmd> <in_cmd> whatever here is ignored](<data_line>)

安装

安装 mdsh 的最佳方式是使用 rust 工具 cargo。

cargo install mdsh

如果你足够幸运，是一名 nix 用户：

nix-env -f https://github.com/NixOS/nixpkgs/archive/master.tar.gz -iA mdsh

如果你是 nix + flakes 用户：

nix profile install github:zimbatm/mdsh

无需安装即可运行

如果你是 nix + flakes 用户：

nix run github:zimbatm/mdsh -- --help

Pre-commit hook

本项目也可以安装为 pre-commit hook。

添加到您项目的 .pre-commit-config.yaml：

-   repo: https://github.com/zimbatm/mdsh.git
    rev: main
    hooks:
    -   id: mdsh

请确保您的环境中已安装 rust。

然后运行 pre-commit install-hooks

已知问题

该工具目前精度不足，因为它不解析 Markdown 文件，而是通过正则表达式查找所需的代码块。这意味着在某些情况下，它可能会错误地解释某些命令。大多数现有的 Markdown 解析器最终用于生成 HTML，因此不保留位置信息。例如： pulldown-cmark

代码块移除算法不支持包含三重反引号或  的输出。

用户反馈

问题

如果您对本项目有任何问题或疑问，请通过 GitHub issue 与我们联系。

贡献

我们邀请您贡献新功能、修复或更新，无论大小；我们总是很高兴收到拉取请求，并会尽最大努力尽快处理它们。

许可证

>< LICENSE

MIT 许可证

特此免费授予任何获得本软件及相关文档文件（“软件”）副本的人无限制地处理该软件的权利，包括但不限于使用、复制、修改、合并、发布、分发、再许可和/或出售软件副本的权利，并允许获得该软件的人这样做，但须遵守以下条件：

软件按“原样”提供，不提供任何形式的明示或暗示的保证，包括但不限于对适销性、特定用途适用性和非侵权的保证。在任何情况下，作者或版权持有人均不对任何索赔、损害或其他责任负责，无论是基于合同、侵权或其他原因，均因或与软件或软件的使用或其他交易有关。

$ mdsh - 一个 Markdown 预处理 shell

用法

mdsh command

容器