I'd like to commend you on building something and putting it out in there in the world, keep doing that! Also the idea of running commands and code from Markdown is obviously awesome. I think you'll find that the folks you get to use this will want a ton more features, like project wide config, interactive stdin, .ENV tooling, passing of variables between inputs and a lot more. That's why we built runme.dev, the kernel is built in Go, please come join our community and contribute.
This is a great tool for writing technical documentation sites. It will allow you to run tests on your code samples, ensuring that they are up to date and working with the most recent library release. We were in progress of doing this with Shopify.dev before I left.
Supports backticks for shell and triple backticks for executing Ruby code.
If blocks are successfully executed they are marked as done (using markdown [x] checkboxes). So you can incrementally run a file without executing stuff twice.
Cool idea. Stuff like this reminds me why I like the vim ecosystem so much. At least since the introduction of terminal buffers, most people I know that use vim for serious code work have a form of "send text under cursor to shell"
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.
Also to add, for a while in the past before I found that the IDE I use could execute code blocks I made a little program that would take each code block in a markdown document and run them one after the other, and it would look to see if a “text” fence followed right after the code fence. In that case it would write the output of that command into the text fence. If there was no text fence, it would run the command without inserting any of its input into the document.
It was like a super rudimentary Jupyter Notebook system of my own making.
Eventually I switched away from my own run-and-insert system.
ah, someone has reimplemented another feature of Org Mode.
Well, this will mean Org files exported to Markdown can remain executable just like they were in Emacs, so maybe this makes Org Babel more valuable as well, for those of us that prefer a structured markup language for notes and literate programming
And thanks to pandoc it's not hard to go back and forth
I wrote something similar, but for the web. I call it "Literate Markdown" (https://simpatico.io/lit.md) and you write markdown and your html/css/js/md code blocks are both exposed as text and as code blocks for execution in the browser. The format expects to a) be transformed and exposed by a special server (https://simpatico.io/reflector.md) and b) rendered in a browser. This code also includes a simple test harness that, for example, turns the favicon green/red depending on if exceptions are thrown in your code (https://simpatico.io/testable.js) I also wrote an acceptance test that loads most of the interesting parts of the site in iframes and combines their test output (https://simpatico.io/acceptance). That page also has notes for using headless chrome to run the tests. Also, the server (lazily) caches all transforms with file watcher invalidation, disallows 3rd party cookies, and starts up instantly.
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. :(
It also sees very wide use, it's not just a proof of concept - most who've used any recent major version of Storybook (84k stars) would know about it: https://storybook.js.org/docs/writing-docs/mdx
I guess these kinda toy scripts/utilities get written a lot as they're not really super-common and there's no well-known standard.
I wrote my own version too, a while back, because it seemed like it would be useful (and indeed it has been) - a golang tool to list/search/run named blocks from markdown, joining multiple blocks together if instructed to do so:
We've expanded significantly onto the idea of a toy script/utility to bring multi-modality (editor, notebook, terminal, browser) with shared sessions to what's at the core, a universal task runner (see architecture link below).
I'd love to chat about combining efforts if you love hacking on this. The same goes for the author of `mdx`.
For Obsidian users, I'm a fan of the Execute Code[0] plugin which allows exexution of codeblocks straight from your notes.
[0]: https://github.com/twibiral/obsidian-execute-code
I spelled 'execution' wrong. Ugh. Careful running those codeblocks :)
I'd like to commend you on building something and putting it out in there in the world, keep doing that! Also the idea of running commands and code from Markdown is obviously awesome. I think you'll find that the folks you get to use this will want a ton more features, like project wide config, interactive stdin, .ENV tooling, passing of variables between inputs and a lot more. That's why we built runme.dev, the kernel is built in Go, please come join our community and contribute.
Congratulations! Nice work.
If you like this, another similar tool, though one specifically geared towards builds, is xc.
https://xcfile.dev/
This is a great tool for writing technical documentation sites. It will allow you to run tests on your code samples, ensuring that they are up to date and working with the most recent library release. We were in progress of doing this with Shopify.dev before I left.
Similar in Ruby/shameless pluck:
https://github.com/coezbek/baker
I call this a Project-Setup-as-Code tool.
Supports backticks for shell and triple backticks for executing Ruby code.
If blocks are successfully executed they are marked as done (using markdown [x] checkboxes). So you can incrementally run a file without executing stuff twice.
Cool, at last we can now `curl | mdx` Github readmes instead of copy pasting `curl | bash` from them!
Note: If one writes a cell with "you can install this with `curl | mdx`" this ends up in an infinite loop xD.
That's both exhilarating and terrifying at the same time. Please don't tempt me. At least it's better than:
Cool idea. Stuff like this reminds me why I like the vim ecosystem so much. At least since the introduction of terminal buffers, most people I know that use vim for serious code work have a form of "send text under cursor to shell"
Helix and Emacs have that built in by the way
I would prefer an api base on codeblocks meta string and json attributes.
```sh name="build" deps=["install"]
npm run build
```
This would be displayed just fine in github, as it is valid gfm.
reminds me a lot of rmarkdown - which allows you to run many languages in a similar fashion https://rmarkdown.rstudio.com/
Can you compare to https://github.com/bashup/mdsh ?
Could use some more (or better?) examples of how this can be useful.
I do something similar.
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.
Also to add, for a while in the past before I found that the IDE I use could execute code blocks I made a little program that would take each code block in a markdown document and run them one after the other, and it would look to see if a “text” fence followed right after the code fence. In that case it would write the output of that command into the text fence. If there was no text fence, it would run the command without inserting any of its input into the document.
It was like a super rudimentary Jupyter Notebook system of my own making.
Eventually I switched away from my own run-and-insert system.
I can think of code examples in the documentation. At least you make sure the code is executed or even check the output of the examples.
If only we had a mechanism for demonstrating correct and incorrect ways to use a particular software.
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.
cf. rundown https://github.com/elseano/rundown
ah, someone has reimplemented another feature of Org Mode.
Well, this will mean Org files exported to Markdown can remain executable just like they were in Emacs, so maybe this makes Org Babel more valuable as well, for those of us that prefer a structured markup language for notes and literate programming
And thanks to pandoc it's not hard to go back and forth
Are you referring to this?
https://orgmode.org/worg/org-contrib/babel/languages/ob-doc-...
org babel supports way more languages. Elisp (obviously), python, C, C++, Java, you name it
Yes, the feature is called org-babel and it lets you write and execute polyglot literate programs.
This idea isn't just from one source but that doesn't mean another implementation isn't worthy.
We did similar at a company I worked for 15 yrs ago
Those who do not understand Emacs are doomed to reinvent it, poorly.
With apologies to Henry Spencer.
Casting off the shackles of Lisp! There are worse mistakes.
This is really cool, I was just thinking recently about something like that. What do you plan to add to it next? What do you think of Go?
It is similar to how CoffeeScript literate works.
See also https://github.com/jpillora/md-tmpl
I wrote something similar, but for the web. I call it "Literate Markdown" (https://simpatico.io/lit.md) and you write markdown and your html/css/js/md code blocks are both exposed as text and as code blocks for execution in the browser. The format expects to a) be transformed and exposed by a special server (https://simpatico.io/reflector.md) and b) rendered in a browser. This code also includes a simple test harness that, for example, turns the favicon green/red depending on if exceptions are thrown in your code (https://simpatico.io/testable.js) I also wrote an acceptance test that loads most of the interesting parts of the site in iframes and combines their test output (https://simpatico.io/acceptance). That page also has notes for using headless chrome to run the tests. Also, the server (lazily) caches all transforms with file watcher invalidation, disallows 3rd party cookies, and starts up instantly.
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. :(
You might want to reconsider the name. MDX is already a well-known technology that combines markdown with JSX https://github.com/mdx-js/mdx/
Also Multidimensional expressions, popular in OLAP cubes. https://en.wikipedia.org/wiki/MultiDimensional_eXpressions
It also sees very wide use, it's not just a proof of concept - most who've used any recent major version of Storybook (84k stars) would know about it: https://storybook.js.org/docs/writing-docs/mdx
Not just Storybook, but most modern JavaScript-based static site generators, for example:
- 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...
marko or godown would be fun
Marko too is taken https://markojs.com/
Came here to say this, confusion ensued.
You really didn't know Runme [0] existed?
[0]: https://docs.runme.dev/installation/cli
I guess these kinda toy scripts/utilities get written a lot as they're not really super-common and there's no well-known standard.
I wrote my own version too, a while back, because it seemed like it would be useful (and indeed it has been) - a golang tool to list/search/run named blocks from markdown, joining multiple blocks together if instructed to do so:
https://github.com/skx/runme
Great name ;)! Co-creator of https://github.com/stateful/runme here.
We've expanded significantly onto the idea of a toy script/utility to bring multi-modality (editor, notebook, terminal, browser) with shared sessions to what's at the core, a universal task runner (see architecture link below).
I'd love to chat about combining efforts if you love hacking on this. The same goes for the author of `mdx`.
https://docs.runme.dev/resources/architecture
Great!
One hint: your examples need to be escaped to show the fence syntax. Add 4 spaces I think.
I've added that now, thanks!
Could you please link the example? In the repo itself? There are quite a few. I want to be sure we get that fixed.
The first one for example: uptime
I can't see the fence instructions (without entering raw, I guess)