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.
> 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.
I feel like things have changed as the main interface for code has (for some) become an agent running in the cli. I feel like we (certainly I) check my code editor way less frequently than before. Because of that (for me) easily reading/rendering Markdown files has become more of a pain than it used to be.
If you problem is that you don't have a text editor open...just open it to read the file? When I click on a Markdown file, it opens in my code editor with the preview pane already open. Then I close it when I'm done. How is that different from any other file on a computer?
If your problem is that you don't want to use a text editor, there are many markdown viewers out there, both dedicated (MarkLite), as part of a larger tool (Obsidian) or even in an office suite (LibreOffice Writer).
If your problem is that you don't want fo leave the terminal, there are many command line markdown "renderers", at least as far as that is even technically possible (glow is markdown-specific, bat is more of a general fancy text file viewer).
I fail to see how any of these problems are even partially solved by a web app and a CLI tool that launches it, let alone any better than the existing solutions.
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?
You are right re privacy. It is possible to go from url hash -> parse -> server (that’s not what SDocs does to be clear).
I’ve been thinking about how to prove our privacy mechanism. The idea I have in my head at the moment is to have 2+ established coding agents review the code after every merge to the codebase and to provide a signal (maybe visible in the footer) that, according to them it is secure and the check was made after the latest merge. Maybe overkill?! Or maybe a new way to “prove” things?? If you have other ideas please let me know.
How about simply making the website an app and have it load your makedown file with a button and file browser. Just like e.g. https://app.diagrams.net/
And I believe you can then tell the browser that you need no network communication at that point. And a user can double check that.
If it's possible to isolate that part of the code, and essentially freeze it for long periods. At least people would know it wasn't being tweaked under them all the time.
I have something coming out soon (just working on it). Your client (browser) has hashing algos built into it. So the browser can run a hash of all the front end assets it serves. Every commit merged into main will cause a hash of all the public files to be generated. We will allow you to compare the hashes of the front end files in your browser with the hashes from the public GH project. Interested to know what you think...
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.)
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?
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.
That direction makes a lot of sense. If sdoc could output raw content — or parsed frontmatter and body separately — to stdout, agents could consume it directly without a browser step. Something like sdoc get <url> --format json piped into whatever the agent needs next.
The frontmatter-as-structured-data angle is where it gets interesting: an agent reading frontmatter as JSON could use it for routing, status checks, dependency resolution — not just presentation. Basically turning a sdoc URL into a queryable state artifact, not just a readable document.
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.
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?
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?
That’s exactly what happens. We encrypt client side. The sever only gets encrypted data. You can inspect the network request to see what the sever receives. Your decryption key always stays client side (in the url fragment).
Also, the short URL (which saves the content in cypher format on the server) is optional. It only triggers if you specifically trigger it (by clicking “Generate” at the top of the rendered document). If you don’t click that everything stays client side in the fragment.
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://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.
Re URL length: Yes... I have a feeling it could become an issue. I was wondering if a browser extension might give users the ability to have shorter urls without losing privacy... but haven't looked into it deeply/don't know if it would be possible (browser extensions are decent bridges between the local machine and the browser, so maybe some sort of decryption key could be used to allow for more compressed urls...)
i doubt it would be possible, it boils down to compression problem compressing x amount of content to y bits, since content is unpredictable it cannot be done without having intermediary to store it.
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
Thank you. If you use an AI agent you might be able to tell it to curl the target website, extract the content into a markdown file and then sdoc it. It might have some interesting ideas with images (using the hosted URLs or hosting them yourself somehow)
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.
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.
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:
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.
> 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.
I feel like things have changed as the main interface for code has (for some) become an agent running in the cli. I feel like we (certainly I) check my code editor way less frequently than before. Because of that (for me) easily reading/rendering Markdown files has become more of a pain than it used to be.
If you problem is that you don't have a text editor open...just open it to read the file? When I click on a Markdown file, it opens in my code editor with the preview pane already open. Then I close it when I'm done. How is that different from any other file on a computer?
If your problem is that you don't want to use a text editor, there are many markdown viewers out there, both dedicated (MarkLite), as part of a larger tool (Obsidian) or even in an office suite (LibreOffice Writer).
If your problem is that you don't want fo leave the terminal, there are many command line markdown "renderers", at least as far as that is even technically possible (glow is markdown-specific, bat is more of a general fancy text file viewer).
I fail to see how any of these problems are even partially solved by a web app and a CLI tool that launches it, let alone any better than the existing solutions.
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
Thanks for the kind words re the analytics!
You are right re privacy. It is possible to go from url hash -> parse -> server (that’s not what SDocs does to be clear).
I’ve been thinking about how to prove our privacy mechanism. The idea I have in my head at the moment is to have 2+ established coding agents review the code after every merge to the codebase and to provide a signal (maybe visible in the footer) that, according to them it is secure and the check was made after the latest merge. Maybe overkill?! Or maybe a new way to “prove” things?? If you have other ideas please let me know.
How about simply making the website an app and have it load your makedown file with a button and file browser. Just like e.g. https://app.diagrams.net/
And I believe you can then tell the browser that you need no network communication at that point. And a user can double check that.
No, I don't have any good ideas. Just hoping someone else does, or that I'm missing something.
I think it's in the hands of browser vendors.
The agent review a la socket.dev probably doesn't address all the gaps. I think you're already doing about as much as you reasonably can.
Thanks. The question has made me wonder about the value of some sort of real time verification service.
If it's possible to isolate that part of the code, and essentially freeze it for long periods. At least people would know it wasn't being tweaked under them all the time.
That is my half of a bad idea.
I have something coming out soon (just working on it). Your client (browser) has hashing algos built into it. So the browser can run a hash of all the front end assets it serves. Every commit merged into main will cause a hash of all the public files to be generated. We will allow you to compare the hashes of the front end files in your browser with the hashes from the public GH project. Interested to know what you think...
That sounds like a good idea. Any step toward transparent security is a good one.
For the "prove the server doesn't touch the data" problem — the realistic path today is probably reproducible builds + published bundle hashes.
My solution is now live at https://sdocs.dev/trust. Open to feedback
That's basically exactly what I'm working on now actually. We will let you compare all the publicly served files with their hashes on github
Ya. I could imagine a browser extension performing some form of verification loop for simpler webpages. Maybe too niche.
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?
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.
That direction makes a lot of sense. If sdoc could output raw content — or parsed frontmatter and body separately — to stdout, agents could consume it directly without a browser step. Something like sdoc get <url> --format json piped into whatever the agent needs next.
The frontmatter-as-structured-data angle is where it gets interesting: an agent reading frontmatter as JSON could use it for routing, status checks, dependency resolution — not just presentation. Basically turning a sdoc URL into a queryable state artifact, not just a readable document.
Interesting idea, do you have any ideas of states that could be particularly useful to have? It's not something I have thought of before
[dead]
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.
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?
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?
That’s exactly what happens. We encrypt client side. The sever only gets encrypted data. You can inspect the network request to see what the sever receives. Your decryption key always stays client side (in the url fragment).
Also, the short URL (which saves the content in cypher format on the server) is optional. It only triggers if you specifically trigger it (by clicking “Generate” at the top of the rendered document). If you don’t click that everything stays client side in the fragment.
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/
(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:
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.
Really nice implementation by the way.
Re URL length: Yes... I have a feeling it could become an issue. I was wondering if a browser extension might give users the ability to have shorter urls without losing privacy... but haven't looked into it deeply/don't know if it would be possible (browser extensions are decent bridges between the local machine and the browser, so maybe some sort of decryption key could be used to allow for more compressed urls...)
i doubt it would be possible, it boils down to compression problem compressing x amount of content to y bits, since content is unpredictable it cannot be done without having intermediary to store it.
For this use-case, maybe compression and then encoding would get more data into the URL before you hit a limit (or before users complain)?
I.e. .md -> gzip -> base64
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
Thank you. If you use an AI agent you might be able to tell it to curl the target website, extract the content into a markdown file and then sdoc it. It might have some interesting ideas with images (using the hosted URLs or hosting them yourself somehow)
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/
Thanks + thanks for the heads up. I will see what happens. It's a domain-name war out there!
In the spirit of r/IllegallySmolCats, perhaps SmolDocs is a possible option.
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.
https://sdocs.dev/trust Now lets you verify you're being served the actual open source code
Soon... there are 15 competing standards.
Nice, I've also built something like this we use internally. Will it reduce token consumption as well?
Thanks. Re tokens reduction: not that I’m aware of. Would you mind explaining how it might? That could be a cool feature to add
I had not heard of url fragments before. Is there a size cap?
Ish, but the cap is the length of url that the browser can handle. For desktop chrome it's 2MB, but for mobile Safari its 80KB.
The compression algo SDocs uses reduces the size of your markdown file by ~10x, so 80KB is still ~800KB of markdown, so fairly beefy.
It's 2^16=65,536 bytes for Firefox
Hadn’t heard of it either - very smart, could open lots of other privacy-friendliness-improved „client-based web“ apps
TYVM. Yeah, I am curious to explore moving into other file formats like CSVs.
Markdown style editing looks very easy and convenient
Thanks! One potential use case I have for it is being able to make "branded" markdown if you need to share something with a client/public facing.
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.
Thanks very much, maybe I can add something to ‘sdoc’ to make that easier
that'd be great, thanks!
[dead]