31 ms·
Show HN: Mdx – Execute your Markdown code blocks, now in Go
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 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 https://github.com/tzador/makedown. Thanks for the idea! :)
- nikolay 2y ago[flagged]
- stevekemp 2y agoI 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 https://github.com/skx/runme
- sourishkrout 2y agoGreat name ;)! Co-creator of https://github.com/stateful/runme 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 https://docs.runme.dev/resources/architecture
- oezi 2y agoGreat! One hint: your examples need to be escaped to show the fence syntax. Add 4 spaces I think.
- sourishkrout 2y agoCould you please link the example? In the repo itself? There are quite a few. I want to be sure we get that fixed.
- oezi 2y agoThe first one for example: uptime I can't see the fence instructions (without entering raw, I guess)
- stevekemp 2y agoI've added that now, thanks!
- sourishkrout 2y agoAh, the other Runme... that explains why I couldn't find it.
- deleted 2y ago[deleted]
- lagniappe 2y agoThis 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?
- nicoburns 2y agoYou might want to reconsider the name. MDX is already a well-known technology that combines markdown with JSX https://github.com/mdx-js/mdx/ https://github.com/mdx-js/mdx/
- zoover2020 2y agoCame here to say this, confusion ensued.
- edsammy 2y agomarko or godown would be fun
- no_wizard 2y agoMarko too is taken https://markojs.com/ https://markojs.com/
- jrajav 2y agoIt 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 https://storybook.js.org/docs/writing-docs/mdx
- ValentineC 2y agoNot just Storybook, but most modern JavaScript-based static site generators, for example: - Astro: https://docs.astro.build/en/guides/integrations-guide/mdx/ https://docs.astro.build/en/guides/integrations-guide/mdx/ - Docusaurus: https://docusaurus.io/docs/markdown-features/react https://docusaurus.io/docs/markdown-features/react - Eleventy: https://www.11ty.dev/docs/languages/mdx/ https://www.11ty.dev/docs/languages/mdx/ - NextJS: https://nextjs.org/docs/pages/building-your-application/configuring/mdx https://nextjs.org/docs/pages/building-your-application/conf...
- dcmatt 2y agoAlso Multidimensional expressions, popular in OLAP cubes. https://en.wikipedia.org/wiki/MultiDimensional_eXpressions https://en.wikipedia.org/wiki/MultiDimensional_eXpressions
- wdavidw 2y agoIt is similar to how CoffeeScript literate works.
- eterps 2y agoCould use some more (or better?) examples of how this can be useful.
- glyphacki 2y agoI 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 2y agoIf 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.
- codetrotter 2y agoI 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 2y agoAlso 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.
- jpillora 2y agoSee also https://github.com/jpillora/md-tmpl https://github.com/jpillora/md-tmpl
- luckman212 2y agoFor 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 https://github.com/twibiral/obsidian-execute-code
- luckman212 2y agoI spelled 'execution' wrong. Ugh. Careful running those codeblocks :)
- Galanwe 2y agoCool, at last we can now `curl | mdx` Github readmes instead of copy pasting `curl | bash` from them!
- theK 2y agoCool 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 2y agoHelix and Emacs have that built in by the way
- mdaniel 2y ago> 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
- oezi 2y agoSimilar in Ruby/shameless pluck: https://github.com/coezbek/baker 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.
- javajosh 2y agoI wrote something similar, but for the web. I call it "Literate Markdown" (https://simpatico.io/lit.md 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 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 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 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/ 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. :(
- dingnuts 2y agoah, 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 2y agoAre you referring to this? https://orgmode.org/worg/org-contrib/babel/languages/ob-doc-shell.html https://orgmode.org/worg/org-contrib/babel/languages/ob-doc-...
- dingnuts 2y agoYes, the feature is called org-babel and it lets you write and execute polyglot literate programs.
- alwayslikethis 2y agoorg babel supports way more languages. Elisp (obviously), python, C, C++, Java, you name it
- VyseofArcadia 2y agoThose who do not understand Emacs are doomed to reinvent it, poorly. With apologies to Henry Spencer.
- oezi 2y agoCasting off the shackles of Lisp! There are worse mistakes.
- bluesnews 2y agoThis 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
- 2y ago
- starkparker 2y agocf. rundown https://github.com/elseano/rundown https://github.com/elseano/rundown
- kchr 2y agoI need a rundown of your clients.
- oezi 2y agoCan you compare to https://github.com/bashup/mdsh https://github.com/bashup/mdsh ?
- pomdtr 2y agoI 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 2y agoRunMe[1] seems like it is what you're looking for: https://docs.runme.dev/usage/run-tag https://docs.runme.dev/usage/run-tag 1: https://github.com/stateful/runme#runme-runs-markdown-- 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 https://news.ycombinator.com/item?id=41955834
- drunken_thor 2y agoThis 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.
- admc 2y agoI'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 2y agoI did not know runme.dev. Thanks for reaching out! It looks absolutely awesome
- huac 2y agoreminds me a lot of rmarkdown - which allows you to run many languages in a similar fashion https://rmarkdown.rstudio.com/ https://rmarkdown.rstudio.com/
- kitd 2y agoCongratulations! Nice work. If you like this, another similar tool, though one specifically geared towards builds, is xc. https://xcfile.dev/ https://xcfile.dev/
- Serenacula 2y agoI 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.
- josephbergevin 2y agoI 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 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.