Show HN: SmallDocs - 用于私密 Markdown 阅读与分享的命令行工具和 Web 应用
7 分•作者: FailMore•4 个月前
大家好，我想向大家介绍 SmallDocs (<a href="https://sdocs.dev" rel="nofollow">https://sdocs.dev</a>)。它是一个开源的 CLI + webapp，可以即时且100%私密地预览、分享和可选地设置 Markdown 文件的样式。（代码：<a href="https://github.com/espressoplease/SDocs" rel="nofollow">https://github.com/espressoplease/SDocs</a>）
我们使用基于命令行的代理越多，`.md` 文件就越成为我们日常生活的一部分。它们的输出非常适合代理生成，但对人类来说却有点令人沮丧：Markdown 文件阅读/预览起来有点烦人，分享/接收起来也很麻烦。SDocs 是我构建的一个工具，旨在解决这些痛点。
如果你运行 `sdoc path/to/file.md`（在 `npm i -g sdocs-dev` 之后），它会立即在浏览器中打开，供你预览（使用我们希望看起来不错的默认样式），并且你可以立即分享该 URL。
我们的代理生成的 `.md` 文件包含我们的一些最敏感的信息（关于代码库、未解决的错误、生产日志等）。因此，100% 的隐私是 SDocs 的一个重要组成部分。
为了实现这一点，SDoc URL 在 URL 片段（`#` 之后的部分）中包含你 Markdown 文档的内容，采用压缩的 base64 编码：
<a href="https://sdocs.dev/#md=GzcFAMT...(this" rel="nofollow">https://sdocs.dev/#md=GzcFAMT...(this</a> 是你的文档的内容)...
关于 URL 片段，很酷的一点是它永远不会被发送到服务器（参见 <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>：“当请求 URI 时，片段不会被发送到服务器；它由客户端处理”）。
sdocs.dev webapp 纯粹是一个客户端解码和渲染引擎，用于渲染存储在 URL 片段中的内容。这意味着你的文档内容会保留在你和那些你选择分享的人手中，SDocs 服务器无法访问它。（欢迎随意检查/让你的代理检查我们的代码来确认这一点！）
由于 `.md` 文件可能在未来的工作中发挥重要作用，SDocs 希望推动在 Markdown 文件中设置样式和渲染有趣内容的界限。还有很多工作要做，但首先，你可以添加复杂的样式并以可视化的方式渲染图表。SDocs 根目录（使用我们的默认样式渲染 `sdoc.md`）有图片和链接到一些冒险的例子。`sdoc schema` 和 `sdoc charts` 为你或你的代理提供了关于如何充分利用 SDocs 格式的详细信息。
如果你分享一个 SDocs URL，你的样式会随之一起传递，因为它们被添加为 YAML 前置元数据 - <a href="https://jekyllrb.com/docs/front-matter/" rel="nofollow">https://jekyllrb.com/docs/front-matter/</a> - 到 Markdown 文件中。例如：
```
styles:
fontFamily: Lora
baseFontSize: 17
```
在工作中，我们一直在测试这个项目。我和我的团队发现 SDocs 对于分享代理调试报告和从 Claude 中轻松复制内容（例如，需要运行的一系列 bash 命令）特别有用。
为了鼓励我们的代理使用 SDocs，我们在根“代理文件”中添加了几行关于它们的内容（例如，~/.claude/CLAUDE.md 或 ~/.codex/AGENTS.md）。当你第一次使用 CLI 时，有一个可选的设置阶段可以为你完成此操作。
当然，我对反馈非常感兴趣，如果你想为 SDocs 添加功能，欢迎提交 pull request。
感谢你的关注！
查看原文
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!