在终端中运行 README.md

降低开发商的进入门槛

继续驾驶 Runme 吧

让我们知道进展如何

请注意：rdme已重命名runme为https://github.com/stateful/runme

文档一直是入门系统的关键组成部分。因此，早在 20 世纪 70 年代中期，软件包开发者就开始将 README 文件作为其发行版文档的一部分。

如今，readme 仍然存在，但已演变成基于 markdown 的README.md文件，存储在你的仓库版本控制系统中。它已经成为现代开发文化的一部分，随处可见。

Swordfish90的Apple2复古终端查看runme的README.md

降低开发商的进入门槛

在 Stateful，我们希望降低开发入门门槛，并使先决条件、设置和工作流程尽可能简单易用。像 GitHub 这样的源代码托管平台已经将 README.md 提升为代码库在其用户体验中的主要入口点，但它们与代码和文档仍然存在差异，我们希望看到更多改进。

直接从我的终端运行 README 命令？

最初，出于对无休止的 README 复制粘贴的烦恼，我们的队友Adam Babik决定使用Markdown 抽象语法树解析器来生成 README 代码片段的简单摘要，并使其易于运行。这只是一个原型（走快乐之路！），但我们对初步结果很满意。这里以Husky为例进行说明——Husky 是一个流行的 git hooks 管理解决方案：

💡$ runme run npm-install为了简洁起见，我们跳过了

轻松运行Husky 的示例

让我们来看看

解析过程远非完美，但通过尽力将抽象语法树 (AST) 模式匹配到命令片段对的数据结构中，我们通常能够捕获命令及其隐含描述。输出列表会尝试保持 README.md 中最初定义的顺序。您可以随意复制并粘贴以下分步说明。不过，既然您已经复制粘贴了，就不必再这样做了runme😎。

简单列出所有命令

$ runme list

为 git-pre-commit hook 准备 package.json 的脚本

$ runme run npm-pkg

现在安装示例预提交 Husky 钩子

$ runme run npx-husky

触发预提交钩子

$ runme run git-commit

使用一个简单的runme run <name>命令行工具，您可以轻松运行命令块（也可以查看 Tab 键补全），而不会产生太多错误（如上图所示，只需进行一次示例提交即可触发 git-pre-commit 钩子）。对于一个简单的命令行工具，我们惊喜地发现它与任务交互的体验非常自然（如果您喜欢终端的话）。您可以在 runme 的仓库中找到更多示例。

也许将来我们会采用自动化来持续执行 README 的命令并检测过时的文档，但现在让我们通过定期运行它们来发现这些问题runme！

继续驾驶 Runme 吧

如果您使用的是 MacOS 并使用 Homebrew，则安装非常简单，只需runme从我们的 Tap 安装即可：

# please note `rdme` has been renamed to `runme`
$ brew install stateful/tap/runme

您可以使用在 Windows 上scoop安装 版本runme。但请注意，目前仅shell支持环境（尚不支持 PowerShell）。

$ scoop bucket add stateful https://github.com/stateful/scoop-bucket.git && scoop install stateful/runme

对于所有其他平台，请查看runme 的 README.md中的安装部分。

Runme 还能做更多

内部使用runme已经导致了一长串可能的改进，但我们有意决定保持其简单并将runme代码库作为 alpha 版本发布。

以下是一些可能的改进：

• 更强大的解析、可配置性和/或 ML/AI
• 注释 Markdown 以实现确定性片段
• 将交互性和“色彩”引入 CLI 体验
• 在 README markdown 查看器中嵌入运行控件和输出
• 自动化 ENV 解析，注入用户运行时配置
• C/I 可测试性，例如“始终知道何时破坏文档”
• 确定命令顺序，无需在 README 中构建 Makefile
• 还有什么？

查看runme 的 GitHub 问题，以更好地了解议程上的项目。

让我们知道进展如何

如果runme您有同样的感受，或者您有强烈的感受，我们很乐意听取您的意见。使用这个工具，您可能会发现一些特殊情况。请随时在 Discord 上告诉我们，或者在下方评论区留言。