展示HN：SmallDocs - 一款用于私密Markdown阅读和分享的命令行工具和网页应用
大家好，我想向你们介绍 SmallDocs（[https://sdocs.dev](https://sdocs.dev)）。这是一个开源的命令行工具和网页应用，可以即时且100%私密地预览、分享并可选地美化Markdown文件。（代码：[https://github.com/espressoplease/SDocs](https://github.com/espressoplease/SDocs)）
随着我们越来越多地使用基于命令行的工具，`.md` 文件已成为我们日常生活的一部分。它们的输出对于工具来说非常出色，但对于人类来说却有些令人沮丧：Markdown文件的阅读和预览略显麻烦，分享和接收也有些繁琐。SDocs是我为了解决这些痛点而开发的工具。
如果你在安装了 `npm i -g sdocs-dev` 后使用 `sdoc path/to/file.md`，它会立即在浏览器中打开，供你预览（带有我们希望看起来不错的默认样式），你可以立即分享这个网址。
我们的代理生成的 `.md` 文件包含了一些我们最敏感的信息（关于代码库、未解决的bug、生产日志等）。因此，100% 的隐私是 SDocs 的一个重要组成部分。
为了实现这一点，SDoc 的网址片段中包含了你的 Markdown 文档内容的压缩 base64（在 `#` 后面的部分）：
[https://sdocs.dev/#md=GzcFAMT...(this](https://sdocs.dev/#md=GzcFAMT...(this) 是你文档的内容。
网址片段的一个好处是它从未发送到服务器（请参见 [MDN 文档](https://developer.mozilla.org/en-US/docs/Web/URI/Reference/Fragment)： “当请求 URI 时，片段不会发送到服务器；它由客户端处理”）。
sdocs.dev 网页应用纯粹是一个客户端解码和渲染存储在网址片段中的内容的引擎。这意味着你的文档内容始终保留在你和你选择分享的人之间，SDocs 服务器无法访问它。（欢迎你检查或让你的代理检查我们的代码以确认这一点！）
由于 `.md` 文件可能在未来的工作中扮演重要角色，SDocs 希望推动在 Markdown 文件中样式和渲染有趣内容的边界。还有很多工作要做，但首先你可以添加复杂的样式并可视化渲染图表。SDocs 的根目录（使用我们的默认样式渲染 `sdoc.md`）包含图片和一些有趣示例的链接。`sdoc schema` 和 `sdoc charts` 提供了详细的信息，帮助你或你的代理充分利用 SDocs 的格式。
如果你分享一个 SDocs URL，你的样式会随之而来，因为它们作为 YAML 前置信息 - [https://jekyllrb.com/docs/front-matter/](https://jekyllrb.com/docs/front-matter/) - 被添加到 Markdown 文件中。例如：
```
styles:
fontFamily: Lora
baseFontSize: 17
```
在工作中，我们一直在测试这个项目。我和我的团队发现 SDocs 对于分享代理调试报告和轻松提取 Claude 的可复制内容（例如，一系列需要执行的 bash 命令）特别有用。
为了鼓励我们的代理使用 SDocs，我们在我们的根“代理文件”（例如 `~/.claude/CLAUDE.md` 或 `~/.codex/AGENTS.md`）中添加了几行关于它们的内容。当你第一次使用命令行工具时，会有一个可选的设置阶段来为你完成这项工作。
当然，我非常期待反馈，并欢迎任何想为 SDocs 添加功能的拉取请求。
谢谢你的关注！
查看原文
Hi HN, I’d like to introduce you to SmallDocs (<a href="https://sdocs.dev" rel="nofollow">https://sdocs.dev</a>). It's an open-source CLI + webapp to instantly and 100% privately preview, share and optionally style markdown files. (Code: <a href="https://github.com/espressoplease/SDocs" rel="nofollow">https://github.com/espressoplease/SDocs</a>)<p>The more we work with command line based agents the more `.md` files are part of our daily lives. Their output is great for agents to produce, but a little bit frustrating for humans: Markdown files are slightly annoying to read/preview and fiddly to share/receive. SDocs is a tool I built to resolve these pain points.<p>If you `sdoc path/to/file.md` (after `npm i -g sdocs-dev`) it instantly opens in the browser for you to preview (with our hopefully-nice-to-look-at default styling) and you can immediately share the url.<p>The `.md` files our agents produce contain some of the most sensitive information we have (about codebases, unresolved bugs, production logs, etc.). For this reason 100% privacy is an essential component of SDocs.<p>To achieve this SDoc urls contain your markdown document's content in compressed base64 in the url fragment (the bit after the `#`):<p><a href="https://sdocs.dev/#md=GzcFAMT...(this" rel="nofollow">https://sdocs.dev/#md=GzcFAMT...(this</a> is the contents of your document)...<p>The cool thing about the url fragment is that it is never sent to the server (see <a href="https://developer.mozilla.org/en-US/docs/Web/URI/Reference/Fragment" rel="nofollow">https://developer.mozilla.org/en-US/docs/Web/URI/Reference/F...</a>: "The fragment is not sent to the server when the URI is requested; it is processed by the client").<p>The sdocs.dev webapp is purely a client side decoding and rendering engine for the content stored in the url fragment. This means the contents of your document stays with you and those you choose to share it with, the SDocs server doesn't access it. (Feel free to inspect/get your agent to inspect our code to confirm this!)<p>Because `.md` files might play a big role in the future of work, SDocs wants to push the boundaries of styling and rendering interesting content in markdown files. There is much more to do, but to start with you can add complex styling and render charts visually. The SDocs root (which renders `sdoc.md` with our default styles) has pictures and links to some adventurous examples. `sdoc schema` and `sdoc charts` provides detailed information for you or your agent about how how make the most of SDocs formatting.<p>If you share a SDocs URL, your styles travel with it because they are added as YAML Front Matter - <a href="https://jekyllrb.com/docs/front-matter/" rel="nofollow">https://jekyllrb.com/docs/front-matter/</a> - to the markdown file. E.g.:<p><pre><code> styles:
fontFamily: Lora
baseFontSize: 17
</code></pre>
At work, we've been putting this project to the test. My team and I have found SDocs to be particularly useful for sharing agent debugging reports and getting easily copyable content out of Claude (e.g. a series of bash commands that need to be ran).<p>To encourage our agents to use SDocs we add a few lines about them in our root "agent files" (e.g. ~/.claude/CLAUDE.md or ~/.codex/AGENTS.md). When you use the cli for the first time there is an optional setup phase to do this for you.<p>I'm of course very interested in feedback and open to pull requests if you want to add features to SDocs.<p>Thank you for taking a look!