mdrun

Markdown笔记本运行器

进行中

此工具尚未准备好使用，因为到目前为止尚未为其编写任何代码。

目录

一旦 mdrun 能够生成目录，将添加目录。

简介

mdrun 是一个读取 Markdown 和 CommonMark 文档的工具，并

• 从您文档的一个或多个指定部分运行 shell 命令。
• 捕获这些 shell 命令的输出。
• 将 shell 命令的输出插入到文档中。
• 更新文档中 shell 命令的输出。

此外，它还执行以下任务

• 为您的文档生成目录。
• 更新您的文档中的目录。

自用

我们编写此工具是为了解决一个痒点，并且我们自己使用它。在其他项目中，以及在你现在正在阅读的非常README中。

（此外，当我说“我们”时，实际上是指“我”，因为到目前为止只有我一个人在开发此项目。欢迎贡献，只要它们坚持项目的本质。所以也许有一天它真的会是“我们”。）

用例

mdrun 的主要用例在于通过捕获和更新文档中包含的 shell 命令的输出，以保持文档的最新状态。

除此之外，许多其他可能的用例之一包括使用 mdrun 与 Markdown 或 CommonMark 文档，类似于 IPython 在选择在 IPython 笔记本上“运行所有单元”时提供的方式。当然，与 IPython 相比，它更简单，交互性更少。至少目前是这样。

用法

由于可能不需要在任何给定的文档中执行所有命令，因此工具需要您指定要从中运行 shell 命令的文档部分。默认情况下，除非指定部分，否则不会执行任何命令，并且此外，只有属于该部分本身的命令，而不仅仅是任何子部分中的命令，才会执行。

此外，为了安全和方便，mdrun 将仅执行满足以下条件的带有边框的命令

1. 包含命令的代码块带有边框，并具有指示要运行命令的 shell 的信息字符串。
2. 上述信息字符串的值对应以下之一：zsh、fish、bash、sh、ksh、tcsh或csh。
3. 包含命令的代码块紧接着是一个代码块，该代码块包含一个值是text的信息字符串。

假设mdrun已安装到您的$PATH中的一个目录，并且您要在该目录中运行以下命令，指定在README的“用法”部分运行mdrun

mdrun -s Usage README.md

进一步假设您已经在您的系统上安装了zsh，那么您会发现以下命令将被执行，并且输出将相应地更新。

date +%s

uname -a

而以下命令将不会执行，因为它没有紧跟一个包含信息字符串text的围栏代码块。

echo This command is not executed.

同样，以下命令也不会执行，因为命令代码块的信息字符串值与命令代码块信息字符串的接受值集合不同

print("Hello from Python 3.")

尽管... Python可能被认为是范围内的。所以在那种情况下，我们将不得不提出另一个例子。

这可能是一个更安全的赌注，因为可能仍然被认为是范围之外的

select current_date;

因为为了使该命令真正有意义，我们至少需要知道要使用哪个SQL客户端（这里使用PostgreSQL），通常我们还需要知道要在哪个数据库上运行SQL命令等。

无论如何，在Python 3和任何具有命令行能力的SQL客户端的情况下，如果您想运行命令并捕获输出，您可以指定一个调用相关工具的shell命令。

例如Python 3

python3 -c "print('Hello from Python 3.')"

以及一个多行Python 3示例

python3 <<EOF
for i in range(2):
  print(i)
EOF

以及SQLite

sqlite3 <<EOF
select date('now');
EOF

等等。

话虽如此，鉴于我们提到了PostgreSQL，我可能还要指出，在运行mdrun的文档部分时，您通常不想连接到一个持久数据库。但有时这也是合适的。这完全取决于您使用mdrun以及您的Markdown或CommonMark文档要做什么。

一些其他示例

同样，当您运行

mdrun -s Usage README.md

您会发现以下内容不会更新，因为它们属于“用法”部分的子部分，而不是直接属于“用法”部分本身

如果您愿意，我们可以递归地这样做（只要您小心）

待办事项：描述

处理具有相同名称的多个部分

以下有两个部分，它们的名称都是“如果你尝试在具有非唯一名称的节上运行mdrun会发生什么？”

然后我们尝试运行mdrun，指定我们想要在具有该名称的节上运行。

mdrun -s "What happens if you try to run `mdrun` on a section that does not have a unique name?" README.md

在这种情况下，mdrun将报告节名称是模糊的，因为多个节具有相同的名称。因此，命令将不会执行，输出将保持不变，并且mdrun将以非零退出码退出。

如果你尝试在具有非唯一名称的节上运行mdrun会发生什么？

这是一个没有唯一名称的节的例子。此节之后的节具有相同的名称。

echo hello

如果你尝试在具有非唯一名称的节上运行mdrun会发生什么？

这是一个没有唯一名称的节段的例子。位于此节段之前的节段具有相同的名称。

echo world

用于项目的配置文件？

我正在考虑使mdrun在当前工作目录中查找名为.mdrunconf或类似的文件，但我倾向于留给每个项目创建一个简短的shell脚本来调用mdrun，并运行它应该运行的节段，而不是这样做。

处理具有相同名称的多个节段（续）

即使所讨论的节段不是直接兄弟，上述内容也适用。mdrun被设计成这样是为了安全起见，以确保不会意外运行错误节段的命令。

出于同样的原因，mdrun不提供数字索引作为消除歧义的方法，因为可能还有其他具有相同名称的节段被插入到文档中。

（当然，节段也可能被重命名，但我们认为这不太可能发生，所以我们将它作为使用此工具的前提条件，假设指定的节段名称与用户所期望的一致，只要我们拒绝在节段名称不唯一的指定节段上运行命令。）

处理具有相同名称的多个节段的主要和推荐方法是给文档中的每个节段赋予唯一的名称。

处理具有相同名称的多个节段的次要和非推荐方法是递归地在共同祖先或每个所讨论节段最近的非歧义祖先上运行mdrun。

安装

选项1：通过操作系统包管理器

此选项目前不可用，但我们希望最终能在以下包管理器中看到此工具

• macOS的Homebrew
• Ubuntu、KDE Neon和Debian的官方apt仓库
• Arch Linux AUR
• FreeBSD ports
• 等等...

选项2：通过GitHub发布页面下载预编译的二进制文件

目前不可用，但很快就会提供。

选项3：通过crates.io使用Rust开发环境工具cargo

1. 安装Rust开发环境，如果您还没有安装

   curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
   

2. 安装mdrun

   cargo install mdrun
   

致谢

没有这个出色的CommonMark Markdown解析器comrak，这个工具是不可能实现的。

贡献

如果您想实现某个功能或修复某个错误，请提交一个问题，以便我们可以讨论它。如果您想到的功能与项目的目标和范围一致，那么我会给您一个绿灯信号，然后您可以编写代码并提交一个pull-request供我们进一步讨论。

⭐ Star, share, like, subscribe ;)

如果您喜欢这个项目，请记住在GitHub上给它加星。

并且请随意告诉一些朋友、同事或家人。