Show HN: Mdx – Execute your Markdown code blocks, now in Go

[dim0x69]

Hey HN! I recently came across makedown here on HN and loved the concept. Wanting to learn Go, I thought this could be a great starter project - so I started working on my own Go implementation, which I’m calling mdx (https://github.com/dim0x69/mdx).

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! :)

[luckman212]

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

[luckman212]

I spelled 'execution' wrong. Ugh. Careful running those codeblocks :)

[dingnuts]

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

[oezi]

Are you referring to this?

https://orgmode.org/worg/org-contrib/babel/languages/ob-doc-...

[dingnuts]

Yes, the feature is called org-babel and it lets you write and execute polyglot literate programs.

[alwayslikethis]

org babel supports way more languages. Elisp (obviously), python, C, C++, Java, you name it

[Bromeo]

Yup, looks like org-babel is at least 15 years old. https://github.com/taruti/org-babel/tree/master

I don't think it ever had huge adoption across whole teams, but I hope if there are new implementations that they take away a number of lessons you can gather from 15 years of org-babel.

[VyseofArcadia]

Those who do not understand Emacs are doomed to reinvent it, poorly.

With apologies to Henry Spencer.

[oezi]

Casting off the shackles of Lisp! There are worse mistakes.

[bluesnews]

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

[Serenacula]

I would put forward that mdx is not a great choice of name, given that it already has a standard meaning in the markdown ecosystem: markdown with inline react components.

[oezi]

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.

[Galanwe]

Cool, at last we can now `curl | mdx` Github readmes instead of copy pasting `curl | bash` from them!

[aziis98]

Note: If one writes a cell with "you can install this with `curl | mdx`" this ends up in an infinite loop xD.

[lioeters]

That's both exhilarating and terrifying at the same time. Please don't tempt me. At least it's better than:

  chatgpt -m "I'm feeling lucky" | sudo bash

[drunken_thor]

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.

[theK]

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"

[dingnuts]

Helix and Emacs have that built in by the way

[mdaniel]

> Emacs have that built in by the way

Org mode is stellar at that "code in document" tangling, but I'll be honest that I loathe the M-| behavior in emacs since, unlike its vim friend, it puts the output in a separate buffer, placing the burden upon me to copy/cut it back into the source buffer

[karthink]

You can add a prefix arg to replace the region with the result. (Any numeric prefix works, so I usually do M-0 M-| since that's easy to type with the meta key held down, and 0 and | are close together.)

[alexflpf]

Just add a prefix arg to replace the region you run it on: C-u M-|

[josephbergevin]

I started in on a similar project a few months ago when I was going through a short "burn out" phase, haha.

https://github.com/josephbergevin/codebook-md

Have a look, I'd love to get some feedback. For me, it's in a good enough state that I'm able to use it in my everyday coding - but it definitely has a lot of room for improvement.

[admc]

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.

[dim0x69]

I did not know runme.dev. Thanks for reaching out! It looks absolutely awesome

[kitd]

Congratulations! Nice work.

If you like this, another similar tool, though one specifically geared towards builds, is xc.

https://xcfile.dev/

[eterps]

Could use some more (or better?) examples of how this can be useful.

[codetrotter]

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.

[codetrotter]

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.

[sourishkrout]

This Jupyter notebook-like system you're describing here is basically Runme. It do not yet have an IntelliJ/Jetbrains plugin; however, the Kernel Architecture outside of the headless CLI allows for integration into any IDE or UI.

It's all open source. Please get involved! We'd be happy to have you.

[glyphacki]

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.

[DJBunnies]

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.

[pomdtr]

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.

[mdaniel]

RunMe[1] seems like it is what you're looking for: https://docs.runme.dev/usage/run-tag

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

[oezi]

Can you compare to https://github.com/bashup/mdsh ?

[lagniappe]

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?

[huac]

reminds me a lot of rmarkdown - which allows you to run many languages in a similar fashion https://rmarkdown.rstudio.com/

[starkparker]

cf. rundown https://github.com/elseano/rundown

[kchr]

I need a rundown of your clients.

[wdavidw]

It is similar to how CoffeeScript literate works.

[javajosh]

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. :(

[jpillora]

See also https://github.com/jpillora/md-tmpl

[nicoburns]

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/

[jrajav]

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

[ValentineC]

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...

[dcmatt]

Also Multidimensional expressions, popular in OLAP cubes. https://en.wikipedia.org/wiki/MultiDimensional_eXpressions

[lsaferite]

I came to make the same comment, so glad it's been brought up and reenforced.

https://mdxjs.com/

[zoover2020]

Came here to say this, confusion ensued.

[edsammy]

marko or godown would be fun

[no_wizard]

Marko too is taken https://markojs.com/