在 VS Code 中像运行笔记本一样运行你的 README.md 文件。

逃出终端

从 README 到 RUNME

介入

由 Mux 主办的 DEV 全球展示挑战赛：展示你的项目！

💡 简而言之；Runme 项目网站上有简要说明：https://runme.dev/

为了持续提升文档的可靠性，减少数据老化问题，我们在八月份发布了 CLI（原名）。CLI 让您可以轻松地在终端中执行文档内的 shell 代码块。runme我们惊喜地发现它受到了大家的热烈欢迎。感谢大家的评论和反馈！rdmeREADME.md

无需任何更改即可将 README.md 文件转换为可运行的 notebook

今天，我们想让 Runme 更进一步，突破终端的限制。据传（但并非唯一原因），针对runmeCLI（已更名rdme）的一条比较引人注目的评论是这样的：

💡 从VS Code 应用商店安装 Runme ，或runme在扩展面板中搜索安装。

这一点非常重要！我们完全同意，在运行命令之前仔细阅读配置文件至关重要。随着今天 Runme 版本的发布，这一点变得容易多了：README.md

只需点击播放按钮即可执行您的 README.md 文件。

逃出终端

我们希望在 Runme 的 CLI 实现之外，扩展到：

1. 允许贡献者学习文档并以交互方式运行文档
2. 赋予维护者控制和管理开发者执行体验的权力
3. 鼓励贡献者对自述文件体验提出建议

我们仔细考察了一番，从数据科学社区中汲取了灵感：数据科学界非常喜欢 Jupyter Notebook！Notebook 巧妙地将代码、计算、数字和叙述交织在一起，充分利用了科学家们创建的动态特性，使任何人都能轻松使用。

更长的视频片段请访问https://www.codecademy.com/article/introducing-jupyter-notebook

笔记本固有的低代码执行能力，即能够重新评估（实际运行）每个段落（输入和输出单元格），自然有助于读者理解呈现在眼前的信息。由于笔记本存储在版本跟踪的代码库中，因此可以通过 Pull Request 轻松地将改进提交到上游。

答对了💡！事实证明，在技术文档方面，代码库维护者和贡献者与数据科学社区有着类似的关系。

从 README 到 RUNME

经过大量的实验，我们决定基于 Runme 解析器构建一个 VS Code 扩展用户体验。该扩展程序现在可以将您的 README.md（入门指南和操作手册文档）集成到 VS Code 的笔记本体验中，而无需对底层 Markdown 进行任何更改。为了展示一个完整的示例，我们使用 Deno 的 Fresh Web 框架、内容管理系统 (CMS)、测试和部署功能，搭建了一个代码仓库https://github.com/stateful/runme.dev（基于https://runme.dev ）。以下是详细介绍：

💡 从VS Code 应用商店安装 Runme ，或runme在扩展面板中搜索安装。

执行控制及其他

Runme 可以透明地将 README.md 文件解析成描述您的应用程序和服务的组成序列（任意 markdown）和可执行块（例如 shell）。

Runme 利用 VS Code 的 Notebook API（笔记本渲染的基础），将您的 README.md（或任何其他 markdown 文件）显示为笔记本中的输入和输出单元格。

GIF

使用笔记本式运行控件，告别繁琐的复制粘贴。

这些笔记本条目可以实现：

1. 每个区块的执行控制
2. Shell 支持和终端集成
3. 笔记本单元中的基本 ENV 支持

打造您的笔记本体验

属性允许维护者通过在 README 代码块内添加简单的注解（完整列表请点击此处）来控制开发者体验的各个方面。普通的 Markdown 查看器会忽略这些注解。只需执行 `git clone`、`git push` 或 `git pull request` 即可轻松共享和合并 notebook 中的更改。

对你的代码块进行注释，以优化你的 shell 执行。

超越壳牌和码头

为了与现有 README 文件及其对 CLI 工具的潜在使用实现广泛兼容，我们首先选择在 Runme Notebook 中启用 shell 执行功能。然而，正如 Jupyter 与绘图库和其他丰富的可视化渲染器实现了一流的集成一样，我们看到了一个机会，可以通过超越文本表示，引入丰富的 Web 体验来提升用户体验。

为了展示其运作方式，我们首先与我们在 Deno 🦕 的朋友们进行了交流：

轻松部署到 Deno 的预览和生产环境

我们设想这样一个世界：无需登录分散的云端 Web 控制台（由服务提供商提供），只需将 Web 组件拖放到 Runme Notebook 的单元格中，即可为不同 API 部分提供可编程的 UX。我们相信，这种方法极具潜力，能够以更简洁、更易于维护的方式记录全栈应用程序和服务。

你怎么认为？

与 CLI 的互操作性

我们相信 Runme Notebooks 能为新贡献者提供更好的入门体验，但我们也理解维护者和资深贡献者可能希望跳过这一步。在 CI/CD 环境中执行代码也是如此，因此我们将 Runme 设计为通过 CLI 以无头模式运行runme。

GIF

与 CLI 的互操作性

我们仍在探索用户体验，确定runme架构边界，并努力实现更广泛的互操作性（例如在命令行界面中处理环境变量）。我们的目标之一是保持命令行界面和 Notebook 实现之间的协同作用，从而为开发者提供最佳体验，并确保文档的可靠运行。

💡 从VS Code 应用商店安装 Runme ，或runme在扩展面板中搜索安装。

介入

我们选择提前发布 Runme，旨在邀请开发者社区参与其持续开发。扩展程序和命令行界面 (CLI) 都仍在紧锣密鼓地开发中，尚未经过全面的实战测试。如果您在使用过程中遇到任何问题，请随时向我们提交错误报告和功能请求。

以下是此 alpha 版本中您应该注意的一些已知限制：

• 目前笔记本仅支持只读模式，如需修改笔记本，请直接编辑底层 Markdown/README.md 文件。我们非常希望未来能够支持双向编辑。
• 请谨慎处理代码块中穿插的环境变量。笔记本的执行是有状态的（仅限 shell/bash；Windows 上尚不支持 PowerShell），它采用了一种较为简单的实现方式，即 VS Code 扩展会提示输入环境变量值并尝试展开它们。本质上，它目前还无法与交互式 bash/shell 会话相媲美。
• 我们继续尝试改善用户/开发者体验的各个方面，包括单元格之间信息/变量的传递、更接近 shell 会话的环境变量处理以及更强大的 Markdown 处理。

快来加入我们，一起聊聊 Runme（这是我的邮箱或者加入我们的 Discord），我们很期待听到你的想法！

谢谢。