$ mdsh - 一个 markdown shell 预处理器

mdsh 项目描述了一种 Markdown 语言扩展，可用于自动化 README.md 文件中的某些常见任务。我常常需要从不同的文件中嵌入代码或 markdown 片段。或者我想显示命令的输出。在这两种情况下，都可以手动完成，但如果你只需运行 mdsh，文件就会自动更新，岂不是更方便？

因此，这个工具的目标首先是以一种自然的方式扩展 Markdown 的语法。你可以输入的内容。如果运行 mdsh 工具，相关的块将被就地更新。其他大多数工具会生成一个新的文件，但我们确实希望这里有一种幂等操作。

最终，这提供了一种类似 literate programming 或 jupyter notebooks 的工具，但用于 shell 命令。它在文件中添加了一些冗余，但允许自动化输出刷新。

用法

$mdsh --help

mdsh 0.6.0
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 [FLAGS] [OPTIONS]

FLAGS:
        --clean      
            Remove all generated blocks

        --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.
    -h, --help       
            Prints help information

    -V, --version    
            Prints version information


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]

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

语法扩展

内联 Shell 代码

语法正则表达式

^`[$>] ([^`]+)`\s*$

内联 Shell 代码是正常的 inline code，

• 从行的开头开始
• 在内容开头包含 $ 或 >
• 包含一个 shell 命令

当遇到这些代码时，命令将由 mdsh 执行，并以带边框的代码块（$）或 markdown 代码（>）的形式输出。

• $ 执行命令并输出代码块
• > 执行命令并输出 markdown

示例

`$ seq 4 | sort -r`
```
4
3
2
1
```

`> echo 'I *can* include markdown. <code>Hehe</code>.'`
<!-- BEGIN mdsh -->
I *can* include markdown. <code>Hehe</code>.
<!-- END mdsh -->

变量

语法正则表达式

^`! ([\w_]+)=([^`]+)`\s*$

变量允许你在环境中设置新的变量，这些变量可以通过正在执行的下一个块访问。

值部分由 bash 评估，因此可以启动子 shell。

示例

!user=bob

现在用户环境变量已可用

$echo hello$user

hello bob

现在将用户名大写

! USER=$(echo$user |tr'[[:lower:]]' '[[:upper:]]')

$echo hello$USER

hello BOB

链接包含

语法正则表达式

^\[[$>] ([^\]]+)]\([^\)]+\)\s*$

链接包含与代码块类似，但使用链接语法。

• $ 加载文件并将其嵌入为代码块
• > 加载文件并将其嵌入为Markdown

示例

[$ code.rb](samples/code.rb) as ruby
```ruby
require "pp"

pp ({ foo: 3 })
```

[> example.md](samples/example.md)
<!-- BEGIN mdsh -->
*this is part of the example.md file*
<!-- END mdsh -->

ANSI转义

从命令输出中过滤ANSI转义序列

$echo$'\e[33m'黄色

yellow

注释掉的命令

有时不渲染显示的命令很有用。所有命令都支持像这样隐藏在HTML注释中

<!-- `$ echo example` -->
```
example
```

围栏代码类型

如果您希望GitHub突出显示输出的代码围栏，可以在行后后缀 as <type>。例如

`$ echo '{ key: "value" }'` as json
```json
{ key: "value" }
```

安装

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

cargo install mdsh

如果您足够幸运是nix用户

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

预提交钩子

此项目也可以作为 pre-commit 钩子安装。

将以下内容添加到项目的 .pre-commit-config.yaml

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

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

然后运行 pre-commit install-hooks

已知问题

当前工具缺乏精确性，因为它不解析Markdown文件，而是通过正则表达式查找所需的块。这意味着在某些情况下，它可能误解一些命令。大多数现有的Markdown解析器最终用于生成HTML，因此不是位置保留的。例如：pulldown-cmark

块移除算法不支持包含三重反引号或 <!-- END mdsh --> 的输出。

相关项目

• http://chriswarbo.net/essays/activecode/ 是与此项目最相似的项目。它有一些有趣的Pandoc过滤器，可以将代码块捕获到输出中。转换不是就地进行的，就像 mdsh 一样。
• Literate Programming 是将可执行代码插入文档的实践。有许多特定于语言的实施。 mdsh 有点像bash literate programming语言。
• Jupyter Notebooks 是一个完全不同的文档和代码领域。它很棒，但将笔记本存储为JSON文件。需要特殊的查看程序才能将它们渲染为HTML或文本。

用户反馈

问题

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

贡献

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

许可证

> LICENSE

MIT许可证

版权所有（c）2019 zimbatm 和贡献者

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

上述版权声明和本许可声明应包含在软件的所有副本或主要部分中。

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