[HN Gopher] Show HN: SmallDocs - Markdown without the frustrations
___________________________________________________________________
Show HN: SmallDocs - Markdown without the frustrations
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!
Author : FailMore
Score : 39 points
Date : 2026-04-15 11:29 UTC (3 days ago)
| moeadham wrote:
| I had not heard of url fragments before. Is there a size cap?
| FailMore wrote:
| 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.
| vivid242 wrote:
| Hadn't heard of it either - very smart, could open lots of
| other privacy-friendliness-improved ,,client-based web" apps
| FailMore wrote:
| TYVM. Yeah, I am curious to explore moving into other file
| formats like CSVs.
| moaning wrote:
| Markdown style editing looks very easy and convenient
| FailMore wrote:
| 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.
| stealthy_ wrote:
| Nice, I've also built something like this we use internally. Will
| it reduce token consumption as well?
| FailMore wrote:
| 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
| pdyc wrote:
| 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 wrote:
| 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...)
| pdyc wrote:
| 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.
| mystickphoenix wrote:
| 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
| FailMore wrote:
| (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 wrote:
| 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
| FailMore wrote:
| 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.
| big_toast wrote:
| 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.
| FailMore wrote:
| Thanks. The question has made me wonder about the value of
| some sort of real time verification service.
| pbronez wrote:
| 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 wrote:
| Thanks + thanks for the heads up. I will see what happens. It's
| a domain-name war out there!
| FailMore wrote:
| 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.
| Arij_Aziz wrote:
| 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
| FailMore wrote:
| 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)
___________________________________________________________________
(page generated 2026-04-18 23:00 UTC)