Show HN: Ledge.sh – Runnable Markdown Notes (ledge.sh)
Ledge is a Markdown notebook that runs shell commands, code, SQL, etc from inside your own notes.
I built Ledge because I spend much of my day copy/pasting commands from my notes into the terminal. I was inspired by how much cmux helped me organize my terminals - but there was still a split brain between my notes and frequently run commands. I've been daily-driving it for the past few weeks and use it for deploys, API calls, smoke tests, etc.
Ledge runs your real shell just like a terminal app and can be hosted locally or remotely over SSH using ledge-server. I've been building it since July and have recently added support for all the major platforms: Mac (Silicon), Windows (WSL required), Linux, iOS, Android. Mobile devices require SSH access to a ledge-server and Android is still in beta and looking for beta testers (see link on website)!
It's built on Bun and Electrobun and is free and open-source. Feel free to review the code and contribute at https://github.com/ledgesh/ledge
Feedback is very much welcome. Any must-have features that are missing?
84 comments
[ 4.0 ms ] story [ 20.2 ms ] threadFeel free to get in touch if you are open to an exchange, you can find my contact details in the write-up.
I always thought it was only a matter of time before I came across another project just like it.
I wish Notion could just integrate these things together and make it work, or someone build an Obsidian plugin. More often than not it would be so convenient to do something like this.
To be clear, is the issue with org-babel that it's not accessible to other people on the team? or something else that this solves?
Markdown (although it doesn't adhere to a strict standard) is ubiquitous, and support for Ledge notebooks degrades gracefully. If one doesn't have Ledge installed to run it, it can be assumed that their editor is able to render markdown. Even opened in a plain text editor, markdown is a lot easier on the eyes than org (IMHO).
UX matters.
0: https://github.com/atuinsh/desktop
For people who used these tools long-term: what held them back? UX/accessibility, or do people simply prefer keeping documents separate from the actual work?
we saw a bunch of issues with desktop, in no particular order
1. authoring runbooks is difficult, most people barely document their work let alone make it executable
2. keeping runbooks up to date is difficult, they are error-prone across systems
3. agents are now pretty good at a number of the tasks these ideas solve for, and are good at working around issues caused by docs becoming out of date/etc
all these tools are great for your own notes, but are very difficult to scale
1. Ledge's bet is it shouldn't feel like authoring at all. I've always had markdown docs chock full of commands and docs so making them runnable was the next logical step for me.
2. True. Keeping any kind of documentation up to date is difficult
3. Also true. I'm hoping Ledge's built-in agent support will bridge that gap and allow agents to help keep the docs up-to-date
And yes, a "Team" notebook is a challenge. Technically anyone with SSH access can all share a Ledge notebook. But that probably doesn't get us all the way there.
Thanks again for providing your thoughts. This by no means is a solved problem but I'm interested to see where it goes!
To give a bit more discouraging advice to Ledge, these tldr insights have made me run circles to resolve. My experience is that one will start getting into build system and dependency mapping to make this sustainable. And then if one wants something more universal, one ends up building something like homebrew, which doesn’t even cover all OSs for good reason.
As you dig deep across system dependency and updates and configurations, there are crazy, crazy, crazy cascading bugs that popup from personal experience. As an example of how this comes up in practice, this is why many teams end up building on Electron as a common cross-platform bug fixer (Tauri has catching up to do although generally works well).
- Keep diagram source (eg Graphviz dot) with the document.
- Write software developer manuals that can reference code robustly as the code changes (eg include code snippets from source based on regex).
- Literate Coding / Reproducible Research pattern. Eg, org file explains and generates/builds/runs code and graphs/figures which then get included back into the document.
Some of the problems
- At some scale, one needs a DAG (eg make) or to make every command idempotent with fast no-op. Otherwise, each little change to a source block takes too long and there is a worry that something didn't update which should.
- At some scale, the document becomes the size of a library/package and it does not compose and/or I want to run the code outside of the document.
- The unenlightened around me do not use Emacs so an org file is a "me" file. In some ways this is a plus as it keeps others fingers out of my pie but it also means no way to share the baking.
That was in the days before LLMs. As ellieh's #3 points out, things are different now (we all know that). I now have an LLM externalize org-babel. The LLM maintains an org or LaTeX document describing bits of work, an external library/CLI which runs to produce content including putting numerical results into LaTeX macros, a Makefile or Snakemake to regenerate content and figures. When things are found to change prior understanding the LLM remakes a section of prose in the LaTeX document. I then write my own notes or another LaTeX document so that the trip through eyeballs to fingers on the keyboard assures I keep some level of understanding.
Likewise, in the software documentation goal, it's far better to give a good LLM access to the source and have it generate documentation targeting some learning goal with follow exploration via Q&A than it is to read some prepared document that assumes my goal. Software documentation is kind of a relic useful only for those people that have not yet taken up LLM tools.
https://github.com/atuinsh/desktop
[1]: https://www.youtube.com/watch?v=YufgfbUgEgI and xiki.org
More prior art: xcfile²
I've used xc³ for a long time now and it's fairly solid. The idea of runnable markdown is definitely useful. A lot of projects have attempted it and none that I've seen have achieved what I'd call perfection, however, xc gets close enough for my needs.
I'll check out Ledge a bit more thoroughly and give some feedback if I can think of anything constructive. I think xc is probably more suited for my uses, however, I do like electrobun and that seems like a good runtime to build something like this.
Here's what I like about xc:
1. It's built with GO and brings all the power of go's template engine. The portability of go's runtime means that it is just one binary and doesn't have any crazy runtime dependencies.
2. It has a built in dependency system so that each block of code can be predicated on another block completing. It can also ensure that each block in a dependency chain runs just once.
I've built a sort of configuration management system for my home infrastructure with config files in a git repo and all the deployment scripts and dependencies directly in the readme. I use it to maintain and deploy changes to my router, firewall rules, dhcp and dns, git repositories, and various containers.
1. https://en.wikipedia.org/wiki/Literate_programming
2. https://xcfile.dev/
3. https://github.com/joerdav/xc