Markdown is a beautiful demonstration that document structure syntax can/should be simple. What most people do in Word is better done by just adjusting the document rendering/style, not the document structure...
I love the idea of extending markdown to include more visual elements, but if you're not careful you just reinvent HTML.
Here's my personal take on extending table syntax for charts. Easy to write, and if a renderer/parser understands the syntax you get a beautiful chart, and if it doesn't you get a table with slightly weird headings:
Tables are the one thing in markdown where I’d prefer to emphasize edit ergonomics over good looking unrendered text. Making a quick manual change like adding column to a markdown table is just unfun. I’ve always thought a json like format that a linter can organize would be better.
Which is all to say I really like the table proposal here - adding an optional linter to make the data look tabular in unrendered markdown will make it even better
> Making a quick manual change like adding column to a markdown table is just unfun.
This is one of those moments where I realize that the vim life spoils me. It's so easy to do this in vim that I don't even think about. I probably use it a dozen times per day such as commenting out code.
Ctrl + v, select where you want the character, then hit I (shift + i), type your thing, hit escape, and Bob's your uncle.
Even in Vim, the editing experience falls over when making markdown tables that have non-trivial content in their cells (multiple paragraphs, a code block, etc.). I recently learned that reStructuredText supports something called "list tables":
Where a table is specified as a depth-2 list and then post processed into a table. Lists support the full range of block elements already: you can have multiple paragraphs, code blocks, more lists, etc. inside a list item.
This syntax inspired the author of Markdoc[1] (who came from an rST background) to support tables using `<hr>`-separated lists[2] instead of nested lists (to provide more visual separation between rows).
I have found various implementations of list table filters for Pandoc markdown[3][4], but have never gotten around to using any of them (and I've tossed around ideas of implementing my own).
reStructuredText & AsciiDoc are so, so much better than Markdown since they have rich feature sets to actually build documentation, blogging, & so on. It’s a massive shame everyone would prefer _yet another Markdown fork_ like the OP.
Not to defend Word et. al. too much, they have plenty of problems, but keeping the structure simple and applying a style over it is a completely supported way of doing things.
I have documents with essentialy zero direct styling, just paragraph styles (for headings, bullets, code blocks, quotes) and character styles (links, inline code). The UI isn't super well optimized for that, but once you get used to it, it's so much nicer than Markdown or LaTeX for multi-page print work.
I work on a dashboarding / BI solution that is also built around markdown and clickhouse. www.evidence.dev
We moved to stripe's Markdoc variant for the component syntax last year and have been really happy with it. Models are good at writing it, people are good at reviewing it.
Here's an area chart that would issue a SQL query for weekly revenue totals:
My guess is parsability. It’s easier to look for sentinel ``` blocks as opposed to building an HTML processor. An XML processor would have been easier, but people like Markdown. So, here we are.
I also went with Front Matter for styling and added an interactive styling mode you can do on the web to test it out immediately. There are some examples on my homepage which demonstrate it in action.
SDocs is cli -> instantly rendered on web
Despite being in the browser, the content of SDocs rendered Markdown files remain local to you. SDoc urls contain your markdown document's content in compressed base64 in the url fragment (the bit after the `#`):
https://sdocs.dev/#md=GzcFAMT...(this is the contents of your document)...
The url fragment is never sent to the server (see https://developer.mozilla.org/en-US/docs/Web/URI/Reference/F...: "The fragment is not sent to the server when the URI is requested; it is processed by the client").
The sdocs.dev webapp is purely a client side decoding and rendering engine for the content stored in the url fragment.
This also means you can share your .md files privately by sharing the url.
Also, I’m sorry I high jacked your post to some degree with this comment.
It’s just a little too relevant for me not to leave a comment!
I'm starting to wonder if someone is selling 'open source CV booster' packages to executives looking to jump ship. This is obviously vibe-coded with Claude, has a broken link to `/superpowers` which indicates no human has read the README before publishing.
The profile seems to be a real person, CEO/CTO level of a small/medium company, but with zero history of OSS contributions, publishing anything or social media presence. It's the third project of this kind to show up in HN this week.
Broken /superpowers link was a real miss — I removed that directory because it had private context and didn't audit the README for references. Fixed now. CLAUDE.md is public in the repo if you want to see how it was built. Not trying to sell anyone anything; it's an experiment I put out to see if it's useful.
Indeed. This is just a vibe-coded addition to an already overcrowded space, with no indication of any intent to consult others or support it for real use.
I was expecting to find a link to a github pages site where I can see the rendered examples, but only found a link to the html sources in examples/out. Am I missing something?
jesus thank you, im so wary of any project that isn't going to do this bare minimum. static pages on gh are literally free it feels absurd to post this project to HN without doing that.
I feel your pain. My project is https://sdocs.dev, the homepage is actually the rendering of a markdown file (sdoc.md), so you can see how SDocs renders immediately. There are some links on the homepage to other Markdown files with some elaborate styles and charts
nope this is becoming a theme. many showhn posts that are about visualizations do not have any renderings of said visualizations. especially in github readme.
- add lint or errors, otherwise your formatting will break, e.g. LLMs and humans will add text too long or too short and your design system will not be able to handle this.
- it's great for low token input
- validate the layout of the user vs. the components used.
You have gone the full latex route. very interesting project. my purpose was simple, to keep mdv extremely simple nothing complex. I do not want full html/latex replication and for surely no inline code...
The only reason to use markdown is that you can read it and write it in a text editor unaware of syntax and rendering semantics. When this purpose is lost and your UX or reading or writing a document starts depending on renderer and your knowledge of how it works, the result becomes just another rich document format, where editor abstraction is a must. And then why all this is even needed? ODF does the job well.
Nice project. But at what point does Markdown just become Emacs Org-Mode? At least with Emacs you can write Lisp to make your document do anything you want.
With modern editors `<h2>foo<h2>` is one keystroke more than `## foo`. Might as well tap into the React ecosystem (I love Vue BTW) and get module-organization and DRY, live preview, syntax highlighting, autocomplete, linting, AI expertise etc.
There are tools to edit PPTs and movies with React.
The table syntax extension in the top comment is interesting — it solves the readability problem without breaking unrendered markdown. The ::y1 approach degrades gracefully.
One thing I keep running into with these markdown supersets: the rendering gap. You write locally, push somewhere, and suddenly the :::columns block is just raw text. Marp handles this well because the VSCode plugin closes that loop immediately.
Curious how MDV handles the renderer portability problem — is the spec open enough that editors could pick it up, or does it depend on the MDV CLI being in the chain?
This seems cool. For going from Markdown to slides I’ve often used Marp: https://marp.app/ — It doesn’t require much specialized syntax, it mostly does the right thing to turn plain Markdown sections into slides. Simple self-hostable HTML output and PDF export options. Already has a VSCode preview plugin, too. I noticed that Claude Code is able to generate Marp slides for you if you ask it, as well.
Best for slides that are just bullet points, full-slide images, and code. Especially code. Less good if you have a lot of images or need to do your own styles or layout.
I’m a product designer, and I could totally see this fitting into my workflow for design briefs, strategy, review, and crit docs. Markdown is too simple, and Figma is too visual. This feels like a great middle ground.
Always find it funny that software developers are stuck in the 1980's when it comes to making documents. Meanwhile normal people use programs to point and click with the new-fangled technology called "a mouse", and create richer documents that convey more information easier, and they do it faster. I guess when you get paid to write in code, it only makes sense to write more code.
Don't let me deprive you of a laugh, god knows we could all use one. But software developers are stuck on the benefits of source control and the workflows it provides. I'll take a pull request and a code review over "normal people" emailing each other attachments called "Q3 Presentation v7.final.final2.reallyfinalthistime.ppt" any day.
I like it when the two paradigms can be combined. Where you (or a non-developer) can set up a dashboard by point-and-click, but in the end there’s a source file that can be downloaded, revision controlled, deployed to different environments.
And in the best of worlds, that file format is simple enough to be understood in code reviews and scenarios where you want to generate them programmatically, not a huge incomprehensible json or xml.
I find this to be only even more important in 2026 where you could then also let a code agent generate the dashboard (any agent, any dashboarding software – no need for bespoke agent embeddings in the dashboard UI).
The mouse clickers can click their mouses and those of us (humans and machines) who prefers working with text files can do that. A good file format should take both into account.
Maybe not a direct answer to your question, but https://sdocs.dev has a cli built for agents. ‘sdoc —help’ and ‘sdoc schema’ and ‘sdoc charts’ teach your agent how to use it. You can try it with ‘npm i -g sdocs-dev’
there's so many of these now lol. what made you go with this over just extending mdx? also how do you handle escape when the expression body has * or # in it
Markdown is a beautiful demonstration that document structure syntax can/should be simple. What most people do in Word is better done by just adjusting the document rendering/style, not the document structure...
I love the idea of extending markdown to include more visual elements, but if you're not careful you just reinvent HTML.
Here's my personal take on extending table syntax for charts. Easy to write, and if a renderer/parser understands the syntax you get a beautiful chart, and if it doesn't you get a table with slightly weird headings:
Tables are the one thing in markdown where I’d prefer to emphasize edit ergonomics over good looking unrendered text. Making a quick manual change like adding column to a markdown table is just unfun. I’ve always thought a json like format that a linter can organize would be better.
Which is all to say I really like the table proposal here - adding an optional linter to make the data look tabular in unrendered markdown will make it even better
> Making a quick manual change like adding column to a markdown table is just unfun.
This is one of those moments where I realize that the vim life spoils me. It's so easy to do this in vim that I don't even think about. I probably use it a dozen times per day such as commenting out code.
Ctrl + v, select where you want the character, then hit I (shift + i), type your thing, hit escape, and Bob's your uncle.
Even in Vim, the editing experience falls over when making markdown tables that have non-trivial content in their cells (multiple paragraphs, a code block, etc.). I recently learned that reStructuredText supports something called "list tables":
https://docutils.sourceforge.io/docs/ref/rst/directives.html...
Where a table is specified as a depth-2 list and then post processed into a table. Lists support the full range of block elements already: you can have multiple paragraphs, code blocks, more lists, etc. inside a list item.
This syntax inspired the author of Markdoc[1] (who came from an rST background) to support tables using `<hr>`-separated lists[2] instead of nested lists (to provide more visual separation between rows).
I have found various implementations of list table filters for Pandoc markdown[3][4], but have never gotten around to using any of them (and I've tossed around ideas of implementing my own).
[1] https://markdoc.dev
[2] https://markdoc.dev/docs/tags#table
[3] https://github.com/pandoc-ext/list-table
[4] https://github.com/bpj/pandoc-list-table
reStructuredText & AsciiDoc are so, so much better than Markdown since they have rich feature sets to actually build documentation, blogging, & so on. It’s a massive shame everyone would prefer _yet another Markdown fork_ like the OP.
Same in Emacs, and, I suppose, in any editor with enough self-respect to support vertical blocks.
That's basically any editor with multi-cursor capability.
Any editor plugin makes it easy though
created a vscode plugin, try it
Not to defend Word et. al. too much, they have plenty of problems, but keeping the structure simple and applying a style over it is a completely supported way of doing things.
I have documents with essentialy zero direct styling, just paragraph styles (for headings, bullets, code blocks, quotes) and character styles (links, inline code). The UI isn't super well optimized for that, but once you get used to it, it's so much nicer than Markdown or LaTeX for multi-page print work.
What's the : in the divider?
That's header alignment marker. If it's on right, the header cell is aligned to right.
Looks cool.
I continue to love Markdown and always push it a bit further than Commonmark, with frontmatter, schemas, code fence metadata too.
I've been enjoying https://djot.net/ as a superset of Markdown that is feels very well designed and extensible too.
You may look into its syntax and tooling for prior art or some extra lift.
I'm trying to get a djot extension in Zed for syntax highlighting if anyone minds adding a to help signal some community interest.
https://github.com/zed-industries/extensions/pull/5206
I work on a dashboarding / BI solution that is also built around markdown and clickhouse. www.evidence.dev
We moved to stripe's Markdoc variant for the component syntax last year and have been really happy with it. Models are good at writing it, people are good at reviewing it.
Here's an area chart that would issue a SQL query for weekly revenue totals:
``` {% area_chart data="my_table" x="date" y="sum(revenue)" date_grain="week" /%} ```
This is XML without the < and >
Yeah, why not go directly the route of custom HTML elements in Markdown anyway, since HTML inside Markdown is valid?
My guess is parsability. It’s easier to look for sentinel ``` blocks as opposed to building an HTML processor. An XML processor would have been easier, but people like Markdown. So, here we are.
At least, that would’ve my rationale.
This is cool. Can you tell me more about the :: blocks thing. I didn’t know that was a Markdown element.
This problem has risen to the top of many people’s minds at this moment (including mine!). My Show HN for a similar cli + web based solution (https://sdocs.dev) is on the /show page now (https://news.ycombinator.com/item?id=47777633).
I also went with Front Matter for styling and added an interactive styling mode you can do on the web to test it out immediately. There are some examples on my homepage which demonstrate it in action.
SDocs is cli -> instantly rendered on web
Despite being in the browser, the content of SDocs rendered Markdown files remain local to you. SDoc urls contain your markdown document's content in compressed base64 in the url fragment (the bit after the `#`): https://sdocs.dev/#md=GzcFAMT...(this is the contents of your document)... The url fragment is never sent to the server (see https://developer.mozilla.org/en-US/docs/Web/URI/Reference/F...: "The fragment is not sent to the server when the URI is requested; it is processed by the client").
The sdocs.dev webapp is purely a client side decoding and rendering engine for the content stored in the url fragment.
This also means you can share your .md files privately by sharing the url.
Also, I’m sorry I high jacked your post to some degree with this comment. It’s just a little too relevant for me not to leave a comment!
> Can you tell me more about the :: blocks thing. I didn’t know that was a Markdown element.
They are Markdown directives
Tyvm
I'm starting to wonder if someone is selling 'open source CV booster' packages to executives looking to jump ship. This is obviously vibe-coded with Claude, has a broken link to `/superpowers` which indicates no human has read the README before publishing.
The profile seems to be a real person, CEO/CTO level of a small/medium company, but with zero history of OSS contributions, publishing anything or social media presence. It's the third project of this kind to show up in HN this week.
Broken /superpowers link was a real miss — I removed that directory because it had private context and didn't audit the README for references. Fixed now. CLAUDE.md is public in the repo if you want to see how it was built. Not trying to sell anyone anything; it's an experiment I put out to see if it's useful.
All of these are supported in pandoc markdown:
> .mdv is strict CommonMark plus four additions:
> YAML front-matter for title, theme, named styles, and dataset references.
> Fenced blocks for data/visuals: ```chart type=bar x=region y=sales.
> ::: containers for styled regions and layout: ::: callout / ::: columns.
> ::: toc for an auto-generated table of contents.
Indeed. This is just a vibe-coded addition to an already overcrowded space, with no indication of any intent to consult others or support it for real use.
I was expecting to find a link to a github pages site where I can see the rendered examples, but only found a link to the html sources in examples/out. Am I missing something?
I was curious to see them, too, so I uploaded the HTML examples here: https://tacticaltypos-tools.pgs.sh/mdv/examples/out/
jesus thank you, im so wary of any project that isn't going to do this bare minimum. static pages on gh are literally free it feels absurd to post this project to HN without doing that.
Adding it to todo list.
I feel your pain. My project is https://sdocs.dev, the homepage is actually the rendering of a markdown file (sdoc.md), so you can see how SDocs renders immediately. There are some links on the homepage to other Markdown files with some elaborate styles and charts
nope this is becoming a theme. many showhn posts that are about visualizations do not have any renderings of said visualizations. especially in github readme.
Funny to see this approach trending! I published this a month ago.
https://wire.wise-relations.com/guides/components/
my takeaway:
- add lint or errors, otherwise your formatting will break, e.g. LLMs and humans will add text too long or too short and your design system will not be able to handle this.
- it's great for low token input
- validate the layout of the user vs. the components used.
- seen here before: https://myst-parser.readthedocs.io/en/latest/syntax/optional...
You have gone the full latex route. very interesting project. my purpose was simple, to keep mdv extremely simple nothing complex. I do not want full html/latex replication and for surely no inline code...
The only reason to use markdown is that you can read it and write it in a text editor unaware of syntax and rendering semantics. When this purpose is lost and your UX or reading or writing a document starts depending on renderer and your knowledge of how it works, the result becomes just another rich document format, where editor abstraction is a must. And then why all this is even needed? ODF does the job well.
Nice project. But at what point does Markdown just become Emacs Org-Mode? At least with Emacs you can write Lisp to make your document do anything you want.
I'm struggling to figure out why I wouldn't just use Emacs Org or even Typst for this use case.
Typst is amazing, but if you want HTML output, it's not quite there yet.
Deepening on who your users are you might also say "at least with markdown they write Lisp and make their documents do whatever they like."
With modern editors `<h2>foo<h2>` is one keystroke more than `## foo`. Might as well tap into the React ecosystem (I love Vue BTW) and get module-organization and DRY, live preview, syntax highlighting, autocomplete, linting, AI expertise etc.
There are tools to edit PPTs and movies with React.
https://wyozi.github.io/react-pptx/ https://www.remotion.dev/
I'm using quarto for this sort of thing.
markdown is "english" in this AI era
The table syntax extension in the top comment is interesting — it solves the readability problem without breaking unrendered markdown. The ::y1 approach degrades gracefully. One thing I keep running into with these markdown supersets: the rendering gap. You write locally, push somewhere, and suddenly the :::columns block is just raw text. Marp handles this well because the VSCode plugin closes that loop immediately. Curious how MDV handles the renderer portability problem — is the spec open enough that editors could pick it up, or does it depend on the MDV CLI being in the chain?
It is supposed to be compatible with markdown. Also a vscode plugin is available in marketplace.
This seems cool. For going from Markdown to slides I’ve often used Marp: https://marp.app/ — It doesn’t require much specialized syntax, it mostly does the right thing to turn plain Markdown sections into slides. Simple self-hostable HTML output and PDF export options. Already has a VSCode preview plugin, too. I noticed that Claude Code is able to generate Marp slides for you if you ask it, as well.
Best for slides that are just bullet points, full-slide images, and code. Especially code. Less good if you have a lot of images or need to do your own styles or layout.
Good ideas. I am working on something similar but with a tiered complexity to fallback to html for complex use cases : https://github.com/livetemplate/tinkerdown, https://github.com/livetemplate/tinkerdown/blob/main/docs/gu...
Very cool.
I’m a product designer, and I could totally see this fitting into my workflow for design briefs, strategy, review, and crit docs. Markdown is too simple, and Figma is too visual. This feels like a great middle ground.
I like how markdown has now become a trend - would be interesting to see how this tool matures !
PS : Even I built an API tool on markdown - https://voiden.md.
Always find it funny that software developers are stuck in the 1980's when it comes to making documents. Meanwhile normal people use programs to point and click with the new-fangled technology called "a mouse", and create richer documents that convey more information easier, and they do it faster. I guess when you get paid to write in code, it only makes sense to write more code.
Don't let me deprive you of a laugh, god knows we could all use one. But software developers are stuck on the benefits of source control and the workflows it provides. I'll take a pull request and a code review over "normal people" emailing each other attachments called "Q3 Presentation v7.final.final2.reallyfinalthistime.ppt" any day.
I like it when the two paradigms can be combined. Where you (or a non-developer) can set up a dashboard by point-and-click, but in the end there’s a source file that can be downloaded, revision controlled, deployed to different environments.
And in the best of worlds, that file format is simple enough to be understood in code reviews and scenarios where you want to generate them programmatically, not a huge incomprehensible json or xml.
I find this to be only even more important in 2026 where you could then also let a code agent generate the dashboard (any agent, any dashboarding software – no need for bespoke agent embeddings in the dashboard UI).
The mouse clickers can click their mouses and those of us (humans and machines) who prefers working with text files can do that. A good file format should take both into account.
Looks wonderful, is there a skill or prompt that can teach agents how to use this format?
Maybe not a direct answer to your question, but https://sdocs.dev has a cli built for agents. ‘sdoc —help’ and ‘sdoc schema’ and ‘sdoc charts’ teach your agent how to use it. You can try it with ‘npm i -g sdocs-dev’
Putting the markdown in the URL, that is very clever!
there's so many of these now lol. what made you go with this over just extending mdx? also how do you handle escape when the expression body has * or # in it
Frontmatter should now be in the markdown standard.
wow, I didn't know that, and I;m using markdown daily. thx!