HN Explorer

Show HN: SmallDocs – Markdown without the frustrations

92 points by FailMore ↗ HN
Hi HN, I’d like to introduce you to SmallDocs (https://sdocs.dev). SDocs is a CLI + webapp to instantly and 100% privately elegantly preview and share markdown files. (Code: https://github.com/espressoplease/SDocs)

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 was built to resolve these pain points.

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.

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.

To achieve this SDoc urls contain your markdown document's content in compressed base64 in the url fragment (the bit after the `#`):

https://sdocs.dev/#md=GzcFAMT...(this is the contents of your document)...

The cool thing about the url fragment is that it is never sent to the server (see https://developer.mozilla.org/en-US/docs/Web/URI/Reference/F...: "The fragment is not sent to the server when the URI is requested; it is processed by the client").

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!)

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.

If you share a SDocs URL, your styles travel with it because they are added as YAML Front Matter - https://jekyllrb.com/docs/front-matter/ - to the markdown file. E.g.:

   ---

   styles:

     fontFamily: Lora

     baseFontSize: 17

     ...

   ---
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).

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.

I'm of course very interested in feedback and open to pull requests if you want to add features to SDocs.

Thank you for taking a look!

22 comments

[ 3.5 ms ] story [ 57.1 ms ] thread
moeadham
I had not heard of url fragments before. Is there a size cap?
vivid242
Hadn’t heard of it either - very smart, could open lots of other privacy-friendliness-improved „client-based web“ apps
moaning
Markdown style editing looks very easy and convenient
stealthy_
Nice, I've also built something like this we use internally. Will it reduce token consumption as well?
pdyc
i also used fragment technique for sharing html snippets but url's became very long, i had to implement optional url shortener after users complained. Unfortunately that meant server interaction.

https://easyanalytica.com/tools/html-playground/

FailMore
(I left a stand alone comment, but:) A little update: I added privacy-focused optional shorter URLs to SDocs.

You can read more about the implementation here: https://sdocs.dev/#sec=short-links

Briefly:

  https://sdocs.dev/s/{short id}#k={encryption key}
                      └────┬───┘   └───────┬──────┘
                           │                │
                      sent to           never leaves
                       server           your browser
We encrypt your document client side. The encrypted document is sent to the server with an id to save it against. The encryption key stays client side in the URL fragment. (And - probably very obviously - the encryption key is required to make the sever stored text readable again).

You can test this by opening your browser's developer tools, switch to the Network tab, click Generate next to the "Short URL" heading, and inspecting the request body. You will see a base64-encoded blob of random bytes, not your document.

big_toast
URL data sites are always very cool to me. The offline service worker part is great.

The analytics[1] is incredible. Thank you for sharing (and explaining)! I love this implementation.

I'm a little confused about the privacy mention. Maybe the fragment data isn't passed but that's not a particularly strong guarantee. The javascript still has access so privacy is just a promise as far as I can tell.

Am I misunderstanding something and is there a stronger mechanism in browsers preserving the fragment data's isolation? Or is there some way to prove a url is running a github repo without modification?

[1]:https://sdocs.dev/analytics

edgardurand
For the "prove the server doesn't touch the data" problem — the realistic path today is probably reproducible builds + published bundle hashes.

  Concretely: the sdocs.dev JS bundle should be byte-for-byte reproducible                                                                                                         
  from a clean checkout at a given commit. You publish { gitSha, bundleSha256 }
  on the landing. Users (or agents) can compute the hash of what their browser                                                                                                     
  actually loaded (DevTools → Sources → Save As → sha256) and compare.                                                                                                             
   
  That closes the "we swapped the JS after deploy" gap. It doesn't close                                                                                                           
  "we swapped it between the verification moment and now" — SRI for SPA
  entrypoints is still not really a thing. That layer is on browser vendors.                                                                                                       
                                                                                                                                                                                   
  The "two agents review every merge" idea upthread is creative, but I worry                                                                                                       
  that once the check is automated people stop reading what's actually                                                                                                             
  verified. A dumb published hash is harder to fake without getting caught.                                                                                                        
                                                                                                                                                                                   
  (FWIW, working on a similar trust problem from the other end — a CLI + phone                                                                                                     
  app that relays AI agent I/O between a dev's machine and their phone                                                                                                             
  [codeagent-mobile.com]. "Your code never leaves your machine" is easy to                                                                                                         
  say, genuinely hard to prove.)
pbronez
Cool project. Heads up - there’s a commercial company with a very similar name that might decide to hassle you about it:

https://www.sdocs.com/

FailMore
A little update: I added privacy-focused optional shorter URLs to SDocs.

You can read more about the implementation here: https://sdocs.dev/#sec=short-links

Briefly:

  https://sdocs.dev/s/{short id}#k={encryption key}
                      └────┬───┘   └───────┬──────┘
                           │                │
                      sent to           never leaves
                       server           your browser
We encrypt your document client side. The encrypted document is sent to the server with an id to save it against. The encryption key stays client side in the URL fragment. (And - probably very obviously - the encryption key is required to make the sever stored text readable again).

You can test this by opening your browser's developer tools, switch to the Network tab, click Generate next to the "Short URL" heading, and inspecting the request body. You will see a base64-encoded blob of random bytes, not your document.

fredericgalline
Nice implementation — the URL fragment trick for privacy is clever.

Related pattern I've leaned into heavily: treating .md files as structured state the agent reads back, not just output. YAML frontmatter parsed as fields (status, dependencies, ids), prose only in the body. Turns them from "throwaway outputs" into state the filesystem enforces across sessions — a new session can't silently drift what was decided in the previous one.

Your styling-via-frontmatter is the same mechanism applied to presentation. Have you thought about a read mode that exposes the frontmatter as structured data, for agents that consume sdoc URLs downstream?

FailMore
I think the next thing I want to do (but not sure how to implement yet) is to make it easy for your agent to go from SDocs url to content. I don't know if that's via curl or a `sdoc` command, or some other way... That could include the styling Front Matter / the agent could specify it.

At the moment the most efficient way to get sdocs content into an agent is to copy the actual content. But I think that's not too beautiful.

Arij_Aziz
This is a neat tool. I always had to manually copypaste longs texts into notepad and convert it into md format. Obvisouly i couldn't parse complex sites with lots of images or those that had weird editing. this will be useful
petersumskas
> Markdown files are slightly annoying to read/preview

Maybe I’ve missed the intentions of markdown, but the ability to easily read the plain text version has always been the killer feature.

Rendering as html is a nice bonus.

I understand there are plenty of useful things to say “but what about…” to, like inline images, and I use them. But they still detract from what differentiated markdown in the first place.

The more of that you add, the more it could have been any document format.

beckford
Using fragments for secure data has been discussed before on hn: https://news.ycombinator.com/item?id=23036515. Tldr: it may not go directly to the server (unless you are using a buggy browser or web client) but the fragment is captured in several places.
franga2000
I can't believe I'm saying this, but this should be an Electron app. Or Tauri or whatever.

Seriously, it's a really nice Markdown app, but the "launch a CLI to urlencode your file" flow is such a messy way of doing this. Just open the file like any other app. Sure, the web version is convenient for demonstrating to people or one-off use, but it's no way to work day to day.

As for the motivation... "Fiddly to send/receive"?? Just send the file like you would any other. Don't you have to send other files? So you already have a way of doing this. Just do that. Bonus points for being able to easily receive an edited file, make diffs, etc., as well as the person on the other side being able to use whatever viewer/editor they prefer, not the one you pushed onto them.

How is sending a GIGANTIC link any better? If your file is nearly as long as the shit my LLMs write, you'll reach the chat character limit on most platforms, even though the file itself is well within file upload limits. And now there's a link shortener to solve this problem, which just defeats the purpose of it being offline and independent of a cloud service.

hatappo
I am excited about this really cool idea. I read the update, but does it mean there are two approaches: one where you pack all the content into fragments, and another where you encrypt it on the client side, save it to the server, and reduce the content to data containing only the key?

Also, wouldn't it be better if the encryption and fragmented compression could also be handled on the web client side?

saadn92
This is PrivateBin for markdown, right? Same URL fragment trick.

My actual problem with markdown isn't previewing, it's search. I've got maybe 50 .md files scattered across different project directories from AI coding sessions. Three weeks from now when I'm trying to remember where I wrote down how to fix some specific issue, grep -r is all I've got and it's terrible for this.

dolmen
My current frustration with Markdown is that Gemini is very bad at producing them.

Just because gemini.google.com uses Markdown for its output, it doesn't seem to be able to properly output Markdown from Markdown: always corrupted.

Just yesterday I asked gemini.google.com to write a README.md for a software project: the Markdown was broken from the closing first code block "```bash" and the rest of the doc was in the output like if it wasn't the doc anymore. An escaping issue. So I asked it to give me the same README.md encoded as Base64: once decoded the content was broken from the same point, but after that that wasn't Markdown anymore but binary data. It looks like Gemini leaked raw binary tokens in the Base64.

Very reliable tech. Is is too much to expect reliable Markdown escaping? Shouldn't this be a solved problem long ago?