Posted by dim0x69 10/26/2024
Key Features:
- Define dependencies between commands
- Supports shebangs
- Ability to pass arguments to code blocks
Would love feedback and thoughts!
Ref. makedown: https://github.com/tzador/makedown. Thanks for the idea! :)
In some of my projects I have little snippets of cli commands in the main README.
When I open the project in JetBrains IDE and I open the README of my project there, I can click on each code block to run it.
This way I can for example start up dependencies like say a little python3 web server to serve static files from one of the subdirs, simply by clicking on it in the readme. Instead of copy-pasting from the readme, and even instead of Ctrl+R in a terminal window and finding the correct commands for a project from history.
It almost reminds me a little bit of Plan9 and their Acme editor, where they were blurring the lines between text and commands. In Acme you can type a piece of text and then middle-button click I think it was to run the text as a command. Having executable blocks of code interspersed in a markdown document feels a little bit like that although in a different, more limited manner.
It was like a super rudimentary Jupyter Notebook system of my own making.
Eventually I switched away from my own run-and-insert system.
It's all open source. Please get involved! We'd be happy to have you.
We could expect failure conditions or assert correct outcomes.
It could become a little library of examples that change over time, as the software changes, granting us peace of mind that everything still works.
```sh name="build" deps=["install"]
npm run build
```
This would be displayed just fine in github, as it is valid gfm.
1: https://github.com/stateful/runme#runme-runs-markdown-- (Apache 2, golang)
I wondered why Runme wasn't already mentioned but it seems the comment got nested under a dead thread https://news.ycombinator.com/item?id=41955834
The central use case is to have a fun and fast way to play with browser code, using your favorite editor, and literate programming techniques. All while being open source, local first, and minimalist.
The repo (https://github.com/javajosh/simpatico/) is not yet npm/npx compatible so you have to fork and run. This is a local first, minimalist project that has ~2 small dependencies, which themselves have no deps, so publishing was not a priority.
Eventually I'd like to automate an md-> js process, such that the md is the canonical source for javascript and the final js is a build product. I'd also like to clean up the code and publish to npm, but sadly someone is squatting on the @simpatico handle and npm won't do anything. :(
- Astro: https://docs.astro.build/en/guides/integrations-guide/mdx/
- Docusaurus: https://docusaurus.io/docs/markdown-features/react
- Eleventy: https://www.11ty.dev/docs/languages/mdx/
- NextJS: https://nextjs.org/docs/pages/building-your-application/conf...