As I said on Twitter, this was a great article, but needs to mention Jekyll, which was one of the OG static site generators. There are others such as eleventy as well.
I was kinda shocked that asciidoc came up as the recommended documentation solution; we use it and were looking to possibly make a move because of some of the warts (includes are great, but then make updating doc more complex, no one line ifdef check, feels a bit aged).
Anyone have any other suggestions we should look at?
Points to the Markdown family for using mostly nice syntax. I mean the basics like lists, links, and headings look fine (I can do without the underlined headings or whatever they are called though). Markdown is nice for readmes and simple notes. Usage beyond that is not quite questionable to but debatable.
Asciidoc seems to have a solid backend. But it seems to have a problem with nesting. Nesting things should be tablestakes in a markup language.
I don’t know much about RestructuredText (no, I won’t play these silly free-caps games) but it doesn’t look that nice to me for whatever reason. It looks the closest to regular markup to me except they have replaced things like brackets with backticks.
And finally I am glad that I never have to use some Wiki lightweight markup variant with silly syntax like using X numbers of apostrophes for emphasis or whatever.
For a long time reStructuredText was "the Python thing", the way POD is "the Perl thing", where it's the "only" choice in that ecosystem, but you didn't really see it outside of that ecosystem. But nowadays (thanks to Sphinx?) reStructuredText is also used for big systems-y projects, including the Linux kernel docs and Envoy proxy.
rST is nice for making complete documents, but for smaller things it just is not practical. For one-off things (like github comments) or smaller wikis, markdown is just more practical. rST has bigger reliance on a mildly smart editor than markdown has, just to handle indentation.
The upside of rST is that it's just more complete, it has more document elements available. Markdown is often written without thought to having a readable plain text document, but rST is often very readable in plain text too.
Markdown have a bit of fragmentation problem. CommonMark and Github variant have been nice steps forward, but for code I'd like to have some more extensions rolled in as another standard. For code docs in particular ability to just embed text diagrams would be great, you can hack around that with PlantUML but then you need to have stuff that supports it...
Does any of them make it easy to (a) define & use footnotes, and then (b) render the footnotes flexibly as a default, for example as either (b.1) end-of-page (in page-oriented physical formats) or (b.2) in Tufte-style side notes (in unpaged online formats) ?
"Nesting things should be tablestakes in a markup language."
This is my beef with Markdown. Automatically numbered lists always break for me--every time. And Markdown doesn't support decimal numbered lists (1, 2, 2.1, 2.2).
I can ignore spacing, because every markdown has bad spacing (space before and after a formatted block or header or list), but I loath the inflexibility of numbered lists.
That said, for my projects I use Markdown, because its so simple--necessary and (mostly) sufficient.
Markdown can simply be code - the fenced code blocks are quite enjoyable to work with. RMarkdown is this. Before I learned of RMarkdown I had written something to extract code blocks with filenames that are visible in the rendered page (since hiding it at the end of the first triple backquote codefence isn't great for visibility). I'm currently working on a JavaScript-centered notebook tool (rather than Python centered or R centered as two great ones are). https://github.com/ResourcesCo/macchiato/blob/main/scripts/m...https://github.com/ResourcesCo/notebook
Markdown nested lists could also be used as an alternative to JSON and YAML - they would appear as bullets in a rendered markdown file. I didn't know about this until I started experimenting but inline code blocks can contain backquotes just like fenced code blocks can contain triple backquotes, by wrapping them in a greater number of backquotes.
> Markdown can simply be code - the fenced code blocks are quite enjoyable to work with.
Hmm, if a Markdown file can have code interspersed, then can't a code file have Markdown interspersed, and the two interpretations of the file could in some sense be symmetric - and equally valid ?
Obv such "interspersions" exist in certain implementations, but I don't think such symmetries do, nor is there anything like a "standard" for it.
Literate programming using Markdown - who'da thunk it ?
Ah yes, it's stored as JSON, but look at all those "cell_type": "markdown", interspersed with the code cells. From the standpoint of a user, a Jupyter notebook is code and markdown interspersed.
Yes, but support for showing the Markdown version is much more widespread.
observablehq puts Markdown in JavaScript code.
I think it works better with Markdown even if it wasn't supported in multiple places, but since it does, I think having Markdown be the container format is a clear winner.
There is also MDX but I prefer stuff that displays in the rendered view as well as in the source. Of course the renderers can change, but that's slow.
As for inverting them without losing the data, that seems possible and would be interesting to see.
The "insanity" of the section characters isn't really … it's just that the adorning character doesn't matter so much. (Other than it has to be the same.)
The picture-of-a-tweet nails it, but the author misses the point. It's not "we have Python devs" it's "reST has the best syntax for extensibility": if you need to start doing some sort of macro or pre-processing, reST's syntax is cut out for that. M↓ is not; you'll need to do it out of band. Or, to put it differently, reST's directives offer extension hooks.
> You’ll need to set up an identity and access management (IAM) service in front of your static website. Unless IAM is your jam, it’s better to avail of a managed service to tackle it.
Honestly, while I think reST has a more cleanly thought out syntax that will allow you to grow the complex use cases docs will inevitably hit … the tooling just isn't as good, IMO. Markdown parsers are prolific … reST … not so much, particularly outside of Python. (And IMO, docutils in Python is not very easy to use if you want fine control over parsing & output. It's there, but just hard to take advantage of.) M↓'s syntax is also somewhat limiting: there's just not a lot it can do. (Admonitions, in particular, are useful in tech docs and missing.) There's always HTML, … but that's just not the same.
From my experience: after a few years working with it I finally realized it's extremely well documented once you understand which document you are looking for and some of the underlying abstraction patterns that reST uses. It's just a badly organized mess that seems unorganized or half-finished at casual glance, because so much of the documentation was almost entirely written for the audience of reST's implementors and extenders, and even should be user-facing stuff like "how to write in reST" assumes low level familiarity with its abstractions and have read the documentation in a different order. (Which also is why it can often look "half-finished", it's assuming you already know the correct order to read it in, which isn't necessarily the order it presents itself as.)
reST actually has a strong enough spec document that you could reimplement it some other language that isn't Python and assume a base level compatibility (very contrary to Markdown's case and many flavors), and the reason there aren't more reST engines/libraries in other languages is as much the network effects of the existing ecosystem around Python-based extensions (and Sphinx) more than anything technical or missing in the specs.
I don't know why people are so keen to put distance between themselves and HTML. HTML is a rich, expressive markup language with strong accessibility features that is also consistent and simple.
I write in HTML the way some people write in Markdown using the abbreviated (but valid) syntax.
<!DOCTYPE html>
<title>The Great Novel of All Time</title>
<h1>Chapter One</h1>
<p>It was a dark and stormy night.
<p>Suddenly a shot rang out!
<p>A door slammed. The maid screamed.
If you avoid closing things that don't need to be closed, and use whitespace (and a syntax-highlighting editor) it's easy to write and easy to eye-parse.
I love Asciidoc, but the tooling is pretty crummy. It's not much fun to install and manage asciidoctor if you aren't into the ruby space, and pandoc doesn't take asciidoc as an input.
Its the first I'm hearing of Antora though, so I'll be sure to check that out.
You can actually used it interactively from the repl in clojure as well if you need access to the api. I forget why, but it made using the reveal.js output much easier than getting the extension working through the command line
Pandoc weds you to their particular flavor of Markdown as it's the basis for the internal data representation. All other formats it supports are limited to what its MD can do.
I've migrated our project documentation from pure asciidoctor to Antora and my team loves it. It took some time to set it up the way we wanted, but the effort was worth it.
Surprised to hear that Asciidoctor tooling is challenging. If you're ok going extension-less, then something akin to `brew install asciidoctor` is enough.
I also prefer to use these in place of # and ## for <h1>/<h2> - IMO it makes document cleaner and easier for reader to parse when markdown files are viewed as plain-text.
I've done a lot of research and testing with Markdown, Asciidoc, and reStructuredText to see which would work best for my company's documentation needs. We ended up going with Asciidoc and Antora for the following reasons.
Asciidoc:
* Almost as simple as Markdown.
* Less convoluted than reStructuredText.
* Excellent support for complex tables, captions, callouts, etc.
* We prefer Asciidocs table structure to Markdown's since it is easier to create and maintain.
* Excellent documentation.
Antora:
* Comes with a default template, which makes building prototypes easier.
* Ability to pull from multiple git repositories.
* Native Asciidoc support.
* Fast compile times.
* Good documentation.
Based on our research, I even migrated my personal 11ty sites from Markdown to Asciidoc and have been quite happy with it.
I'm primarily a Python dev. I *hate* RST. I despise that it's really the only viable choice for docstrings in Python and wish for something rustdoc-like to be ported to Python
Last year we changed the source format for MDN from some extremely messy, WYSIWYG-authored HTML to something that would be easier for authors to use. We considered Asciidoc and reST, and despite its limitations, we chose Markdown (GFM specifically) for two reasons:
1. We get a _lot_ of casual contributors to MDN: about 180-200 unique contributors/month, most of whom we never see again. Almost all of them can contribute much more easily with Markdown than with anything else. Many of these people are unlikely to put even an half an hour into learning a new syntax.
2. Markdown has great tooling support. For example, if we want to run Prettier over our embedded code samples, it's really easy if we are in Markdown. If we are in Markdown we will get nice formatting just about everywhere, including GitHub of course and most people's editors.
One thing that made the choice easier for us is that MDN's a very mature doc site, so we had a very good idea of which Markdown limitations were likely to be a problem for us.
You made the right choice, rst is not user friendly, even for tech savvy people.
I'll take the opportunity to do a shameless plug for the amazing "Markedly Structured Text", or MyST, a markdown flavor that is both easy to write like markdown, and expressive like rst.
Basically, if you know markdown, you can write decent MyST already. In fact, any markdown is valid MyST and .md is a valid file extension for MyST.
Once you want more, the syntax offers richer construct, but still easy enough to use.
I wanted to love asciidoc because the format rocks, but it never took off and the tooling is still lacking. MyST piggy back on markdown ecosystem, this is less of a problem.
Also, the devs behind it also have a very good track record at creating a good FOSS ecosystem.
The “one more backtick” syntax is a very early Markdown feature explicitly mentioned by John Gruber (originally only for inline code, of course). It might even be in the original “spec”, I don’t remember, but it dates way back and is implemented by virtually all half-decent Markdown parsers. It’s one of the least utilised feature, however, so huge kudos for MyST to clearly explain it and raise awareness.
I work in an academic setting and I can second the sentiment. For a while, we used reStructuredText for writing the teaching materials. Every so often I would have the students that would get inspired to contribute something to the teaching materials, but would subsequently get demotivated by having to learn the rST syntax and tooling.
After a few years, I gave up and switched from rST and Sphinx to Markdown and MkDocs [2]. We addressed the limitations of Markdown with PyMdown Extensions [3]. Still haven't looked back; for our specific use case of writing (computer science) teaching materials, Markdown is a better choice than rST.
Thanks @vedranm! I especially like your side-by-side comparison of the process of contributing using Markdown versus reST. It really encapsulates the difference that reasonably seamless tool support makes. I need to look more into MkDocs...
You are welcome. I have no connection to its development aside from some minor translation updates and bug reports, but I can only recommend it.
What I like is how easy it is to host MkDocs on GitHub Pages via built-in support, but you can even make it behave like Jekyll with GitHub Actions. Shameless self-plug of another blog post: https://gaseri.org/en/blog/2022-11-01-publishing-material-fo...
I still cannot believe MDN decided to abandon web standards for the garbage that is Markdown. Worse yet, they seem proud of themselves for doing it.
Rather than actually solve the problem of filtering WYSIWYG input/output, providing a solution for creating easy to create and maintain semantic HTML, Mozilla shunted it aside and now use a stack of custom tooling and libraries and yet another Markdown-alike variant text format with their own scripting embeds and then patted themselves on the backs for all the effort they "saved".
Mozilla is supposed to be the standard bearer for web standards. It's sad to see that bunch of myopic techies decided to go with a trendy solution that just trashed a core principle of the organization (#6) for one of its most important products. It set an example others are now following, and as a result, MDN put the web back probably two decades.
Rather than embarking on something that proved to be hard by decades of trying, or inventing something complex and unique, Mozilla took a less powerful existing tool, very simple and well known to every contributor.
They acted as if they tried to make it simple and easy for the community to keep MDN up and up to date. Outrageous!
Well, by the book and its origins, there is no improvement just because in Markdown you can use any HTML. Markdown itself is part of the try when you follow the path of its history and when marketed as a subset, it means (and that approach may be valid), let us go back and reduce to the early set of HTML tags.
I wrote enough basic HTML tags back in 1995 to say that writing _this way_ is way more ergonomic than <i>this way</i>.
The thing is that HTML (and SGML) was invented, but Markdown was discovered as a set of best practices through decades of text-only mailing lists. This is something that many people found natural enough.
Sure, if adding symbols to text is enough, why do more?
It's bending perhaps history of mankind in my book a little too much, saying the author of Markdown has discovered that and not lets say, someone else the "one or other" millennia earlier.
And writing on the computer is commonly the least ergonomic form of writing at all.
What's holding the web back by 20 years are </closing tags>. If it wasn't for them, CMS would not have had to be invented, and everybody would be blissfully authoring effortlessly semantic hypertext like they do with Markdown now.
Heh, you're not wrong. I've thought for a while there should be some sort of valid, but easily hand-written version of HTML5 where any text between two newlines is considered a paragraph. That alone would go a long way to making HTML more text-editor friendly.
Other block-level elements would auto-close either at a new line or when a new block tag starts, headers would automatically create <sections> that end when a new header appears, and inline elements would end at the next space, newline or generic end tag like </>, so they could be nested.
A lot of this is done already in the browser. A valid HTML doc just needs a doctype, title and a body tag and the spec specifies all the rest will be filled in automatically. The spaghetti logic employed to add in missing closing tags to keep pages looking decent is mind boggling. Seems like there could be a few additional spec rules and then plain-text HTML would be just as easy to create as any other markup.
I've upbooped this perspective but I disagree. Markdown trivially compiles to HTML and is justifiably loved (aside from the proud markdown haters, old and jaded and scarred by it not working for their weird usecase that one time), and you haven't suggested an alternative which addresses the problems they had with the mess caused by wysiwyg output. But maybe you have a better solution? Beyond the entitled expectation that it's someone elses job to fix it.
Also #6 of their manifesto is about interoperability. Markdown is a great choice for this if you are consistent in your approach. No lock in, human and readible.
Is it worth mentioning org-mode [0] and Racket's documentation system Scribble [1]. Docs as code and the tangle functionality in org-mode's Babel seem to fit right together. I am only familiar with Scribble by name.
Wikipedia has a nice summary of the various "lightweight markup languages", including a comparison of syntax, and how each one converts into HTML. [1]
As I wrote last week in a post that got flamed to pure carbon here on HN, the amount of man hours lost avoiding HTML is beyond comprehension. All of these languages are seriously flawed half-baked solutions to a problem that's already been solved.
> All of these languages are seriously flawed half-baked solutions to a problem that's already been solved.
I tend to think so aswell but there is a big exception: code highlighting. Having a no-js solution to code highlighting implies having a build step to handle just that (unless you actually do it yourself while writing the docs, which would be insane). I haven't spent a lot of time researching it, but I have yet to find a tool as simple to use as e.g. Pygments or Chroma (with Sphinx and Hugo, respectively). What would you recommend?
Just treat HTML like any other markup text. Markdown doesn't concern itself with images, CSS or syntax highlighting either, why does HTML have to? Since Markdown requires a build step, there's no reason to dismiss the idea for HTML. The big difference is that HTML is simply more flexible.
In both cases you need to add some sort of markup to identify the code, right? In HTML it looks like:
<code class="js-syntax"> let a = "foo"; </code>
And Markdown looks like:
```js let a = "foo"; ```
But in HTML, you have a bunch of options built into the file itself: A WYSIWYG editor could add the syntax highlighting before saving, a build step could add in the appropriate styles before publishing, or a JS script could be added to the page and the browser could deal with it. A Markdown file only has one option: Here's your blob of code in plain text, go find some library to convert it.
HTML is just a text document that happens to have had 30 years of work put into its spec and millions of man-hours put into optimizing its Object Model and parsing engine. It can be as simple as bog-standard Markdown output, or contain all the meta data needed without relying on custom tags and other hacks.
All I know is that you would have to be out of your mind to use rST where you cannot nest inline markup. You can't have inline code with a link in it. How crazy is that?
Yes, it's extensible. But I don't want to write a role just to add bold to a reference!
I have spent a lot of time looking in this space recently for helping to revamp documentation and I really really have fallen in love with Markdoc.
Markdoc just hits the sweet spot of being super easy to get started with but elegantly extensible that makes it scale. I think the OP here simplifies a bit though of what Markdoc is. While it is pretty simple to integrate into a next.js site for a SSG doc site, it is more of a library that can be integrated into almost any site or rendering framework.
In some ways, this is the biggest "challenge" of Markdoc right now. It isn't focused on a polished out-of-the-box experience like Docusaurus or MKDocs, but is instead more of a DIY tool.
That said though, what is there is really great. With the ability to create custom tags easily and then the ability to analyze and transform an AST in a simple, but easy to understand way, I think markdoc is actually a great option for more than just building a doc site, but as a more general purpose tool for authoring any text-heavy content.
With Markdoc, I have built:
* a higher level utility for creating a "library" of content with consistent ids for stable and validated links
* a validation library to ensure that doc structures follows best practices like having metadata tags in the frontmatter, properly nests headers and doesn't skip H3s, etc
* an integration for authoring and reusing doc content in spectacle[0] presentations
* have a clear direction of how to "scale" docs-as-code as we were struggling to do that with a simple, flat file of markdown files
I have started to toy with the idea of a more general purpose CMS built around markdoc... but in general, a really great tool and kudos to stripe team for building it :)
We have reached stage 6 in iommi: docs from tests.
The docs are written as strings in a special tests directory, with special markup to mark code that is not included in the output, and special code for generating (at test-time) and creating inline iframes for results where applicable.
Code examples in docs that aren't executed will very often be wrong. That's just a fact of life. So we execute them all.
The meaning is the same; the syntax is different. All triple-backtick codeblocks in doc comments, unless annotated 'ignore', are run as tests when you run `cargo test`. So from this file[0], this doc page[1] is generated. And there's more flexibility than 'run or ignore' too, e.g. one on that page is marked ```compile_fail,E0277 to fail the test if it compiles or has a different compilation error than expected. And then every code block known to be runnable has a Run button you can click to open the snippet in the Rust Playground.
These are API docs, but mdBook[2], which generates documentation that looks like this[3], has a test command which checks the code blocks the same way.
False choices imho: nowadays just combine markdown, rst and living code in notebooks using the great Jupyter book system. It is build on sphinx but resolved crucial friction points by creating MyST markdown. Brilliant and simple to use. And it is FOSS. Check https://jupyterbook.org/en/stable/intro.html
I think Markdown can be used in serious documentation projects. I am biased, given that I've been working on my free and open source, cross-platform Markdown editor for several years:
These look great! Were these generated with KeenWrite?
I've been generating PDF documentation with Obsidian. The challange is when a document will have multi, non-technical, owners. Invariably the "solution" is to open the PDF in Word.
> These look great! Were these generated with KeenWrite?
Thank you! My sci-fi story, autónoma, is the reason I started to work on KeenWrite, and can be fully generated from within the app. The others could be edited in KeenWrite, but there'd probably need to be some work done to get the HTML/CSS preview panel to display the various annotated sections correctly. Speech bubbles (::: bubbletx and ::: bubblerx), for example, currently work in KeenWrite, but the spectrographic lines in the Impacts Project would need to have special CSS written to render correctly in the preview.
> The challange is when a document will have multi, non-technical, owners. Invariably the "solution" is to open the PDF in Word.
Teaching people to separate content from presentation takes a lot of effort. That's also a process problem. You could ask people to provide feedback by adding notes into the PDF, rather than editing it directly.
At some point it'd be nice to see real-time collaboration added to KeenWrite, which would go a little ways to helping solve multiple users editing a single document:
We have an entire consulting documentation pipeline build on Pandoc. Everything is written in Markdown. It took a good bit of tooling to make our reports easy to write, but that is mostly automation around our industry specific artifacts. Our reports look quite nice IMO.
It’s all internal, unfortunately. It essentially cobbles together markdown documents into a processing pipeline that ultimately makes a PDF. Pandoc does a lot of the heavy lifting getting it all into Latex before PDFing. We have lots of quality of life features around figures, findings, and all the things you expect in a professional report. We use Python doit, and other things to sequence out markdown fragment assembly. We have plugins for processing tool output into markdown and it will run Python and R files that generate markdown as a part of the processing pipeline so you can programmatically generate any content your heart desires. Just to give an idea of tooling :)
I found the article to be rather superficial, for example;
"The original version of Markdown by John Gruber doesn’t specify the syntax unambiguously. For example, it doesn’t have table formatting."
Table formatting is an example of a missing feature in a deliberately minimalist specification. Or possibly a feature that is handled elsewhere in the markdown "stack" (by html). So if the syntax is indeed not specified unambiguously (facts not in evidence?) then this isn't a good way of demonstrating that.
Markdown is pretty great, I would even say the idea is genius. however markdown is a terrible markup language, it completely fails to add any sort of semantic meaning to the text.
So people keep trying to add the semantic bits onto markdown, a process which I would argue destroys the genius of markdown in the first place.
Markdown is intended to be a nice looking text document. with strict limits on the format so that it can be transformed into a nice looking typeset document. If your base text document does not look great, you are doing markdown wrong. You would be better off with an actual markup language. This is also why I think markdown editors are wrong. again the whole point of markdown is to have a great looking text document, a text editor is perfect for this, any other specialized editor will produce a bad looking document.
I would accept any of those instead of the steaming pile of Word docs full of screenshots, bloated PowerPoint presentations, PDFs and various other proprietary formats we have at my current job.
On the flip side, the stuff in the pile mostly wasn't authored by technical writers. The people who used tabs and blank lines for formatting and boldface+font size changes for section heads would be probably just create the same kind of semantic messes, but with the added bonus of having a BOM marker at the head of the document and CRLF line endings.
In my (admittedly) brief experience dabbling with asciidoc, I really don't like the opinionated approach on how styles should be injected to the generated HTML output.
Say that I generate a table using asciidoc's built-in syntax, the output will always generate HTML elements with the CSS classes already defined:
For me, this output is needlessly verbose for a setup that uses nothing but default flags. Worse, it doesn't provide much of a leeway to change the classes or even let me use some other ways to style the elements.
I prefer markdown's (and markdoc's) approach to styling, in that it doesn't really try to define any. My take on this is that stylings of the output should be be coupled with the toolings, as opposed to being bolted into the language standards.
> GFM is, by far, the most popular flavor of Markdown.
It is very sad because gfm is essentially "done" evolving. There's no desire from people I've spoken with to improve the implementation or add new features. For example: Multiline tables.
> Many tech companies love the rich ecosystem of Remark to transform Markdown with plugins. Still, extendability is the subject where Markdown scores the lowest.
The state of the world here is quite painful. I'd also like to say a prayer for anyone else out there writing custom extensions to cmark-gfm in c.
> reStructuredText offers a number of useful directives out-of-the-box. For example, admonitions (“safety messages” or “hazard statements”) can appear in rST like this...
We've been able to implement this as an extension in cmark-gfm and hoedown. It is quite painful but it is doable.
Markdown is just as extendable if you have control of all of the parsers and rendering code for your organization. This is no small feat.
88 comments
[ 3.2 ms ] story [ 163 ms ] threadI was kinda shocked that asciidoc came up as the recommended documentation solution; we use it and were looking to possibly make a move because of some of the warts (includes are great, but then make updating doc more complex, no one line ifdef check, feels a bit aged).
Anyone have any other suggestions we should look at?
Anything AsciiDoc can do, Markdoc can be extended to do, from variables through includes.
React or HTML output. AST transforms or functions. Upcoming editor support etc.
The community isn’t there yet but I predict it will show up.
Asciidoc seems to have a solid backend. But it seems to have a problem with nesting. Nesting things should be tablestakes in a markup language.
I don’t know much about RestructuredText (no, I won’t play these silly free-caps games) but it doesn’t look that nice to me for whatever reason. It looks the closest to regular markup to me except they have replaced things like brackets with backticks.
And finally I am glad that I never have to use some Wiki lightweight markup variant with silly syntax like using X numbers of apostrophes for emphasis or whatever.
The upside of rST is that it's just more complete, it has more document elements available. Markdown is often written without thought to having a readable plain text document, but rST is often very readable in plain text too.
This is my beef with Markdown. Automatically numbered lists always break for me--every time. And Markdown doesn't support decimal numbered lists (1, 2, 2.1, 2.2).
I can ignore spacing, because every markdown has bad spacing (space before and after a formatted block or header or list), but I loath the inflexibility of numbered lists.
That said, for my projects I use Markdown, because its so simple--necessary and (mostly) sufficient.
Markdown nested lists could also be used as an alternative to JSON and YAML - they would appear as bullets in a rendered markdown file. I didn't know about this until I started experimenting but inline code blocks can contain backquotes just like fenced code blocks can contain triple backquotes, by wrapping them in a greater number of backquotes.
Hmm, if a Markdown file can have code interspersed, then can't a code file have Markdown interspersed, and the two interpretations of the file could in some sense be symmetric - and equally valid ?
Obv such "interspersions" exist in certain implementations, but I don't think such symmetries do, nor is there anything like a "standard" for it.
Literate programming using Markdown - who'da thunk it ?
Someone pls correct me if I'm OTL.
observablehq puts Markdown in JavaScript code.
I think it works better with Markdown even if it wasn't supported in multiple places, but since it does, I think having Markdown be the container format is a clear winner.
There is also MDX but I prefer stuff that displays in the rendered view as well as in the source. Of course the renderers can change, but that's slow.
As for inverting them without losing the data, that seems possible and would be interesting to see.
The picture-of-a-tweet nails it, but the author misses the point. It's not "we have Python devs" it's "reST has the best syntax for extensibility": if you need to start doing some sort of macro or pre-processing, reST's syntax is cut out for that. M↓ is not; you'll need to do it out of band. Or, to put it differently, reST's directives offer extension hooks.
> You’ll need to set up an identity and access management (IAM) service in front of your static website. Unless IAM is your jam, it’s better to avail of a managed service to tackle it.
We throw ours behind Github, I think using https://github.com/oauth2-proxy/oauth2-proxy ; then Github is our IAM.
Honestly, while I think reST has a more cleanly thought out syntax that will allow you to grow the complex use cases docs will inevitably hit … the tooling just isn't as good, IMO. Markdown parsers are prolific … reST … not so much, particularly outside of Python. (And IMO, docutils in Python is not very easy to use if you want fine control over parsing & output. It's there, but just hard to take advantage of.) M↓'s syntax is also somewhat limiting: there's just not a lot it can do. (Admonitions, in particular, are useful in tech docs and missing.) There's always HTML, … but that's just not the same.
(I've no experience w/ AsciiDoc.)
reST actually has a strong enough spec document that you could reimplement it some other language that isn't Python and assume a base level compatibility (very contrary to Markdown's case and many flavors), and the reason there aren't more reST engines/libraries in other languages is as much the network effects of the existing ecosystem around Python-based extensions (and Sphinx) more than anything technical or missing in the specs.
I write in HTML the way some people write in Markdown using the abbreviated (but valid) syntax.
<!DOCTYPE html>
<title>The Great Novel of All Time</title>
<h1>Chapter One</h1>
<p>It was a dark and stormy night.
<p>Suddenly a shot rang out!
<p>A door slammed. The maid screamed.
If you avoid closing things that don't need to be closed, and use whitespace (and a syntax-highlighting editor) it's easy to write and easy to eye-parse.
No includes though.
https://news.ycombinator.com/item?id=33381373
Its the first I'm hearing of Antora though, so I'll be sure to check that out.
Maybe there's a great static site generator written in GO with strong Asciidoc support??
Antora is new to me as well, will review.
Asciidoc:
* Almost as simple as Markdown.
* Less convoluted than reStructuredText.
* Excellent support for complex tables, captions, callouts, etc.
* We prefer Asciidocs table structure to Markdown's since it is easier to create and maintain.
* Excellent documentation.
Antora:
* Comes with a default template, which makes building prototypes easier.
* Ability to pull from multiple git repositories.
* Native Asciidoc support.
* Fast compile times.
* Good documentation.
Based on our research, I even migrated my personal 11ty sites from Markdown to Asciidoc and have been quite happy with it.
Good news though, the jupyter devs created myst (https://myst-parser.readthedocs.io/en/latest/syntax/syntax.h...), a superset of markdown that has almost all the features of rst, and can embed rst when it falls short.
And there is a plugin to use it with sphinx. It can even reside in a project that started with rst files, both format can coexist.
With this and sphinx-autoreload, writing doc is so much better.
1. We get a _lot_ of casual contributors to MDN: about 180-200 unique contributors/month, most of whom we never see again. Almost all of them can contribute much more easily with Markdown than with anything else. Many of these people are unlikely to put even an half an hour into learning a new syntax.
2. Markdown has great tooling support. For example, if we want to run Prettier over our embedded code samples, it's really easy if we are in Markdown. If we are in Markdown we will get nice formatting just about everywhere, including GitHub of course and most people's editors.
One thing that made the choice easier for us is that MDN's a very mature doc site, so we had a very good idea of which Markdown limitations were likely to be a problem for us.
If you're interested, we blogged about this project: https://openwebdocs.org/content/posts/markdown-conversion/.
I'll take the opportunity to do a shameless plug for the amazing "Markedly Structured Text", or MyST, a markdown flavor that is both easy to write like markdown, and expressive like rst.
Basically, if you know markdown, you can write decent MyST already. In fact, any markdown is valid MyST and .md is a valid file extension for MyST.
Once you want more, the syntax offers richer construct, but still easy enough to use.
Check it out: https://myst-parser.readthedocs.io/en/latest/syntax/syntax.h...
I wanted to love asciidoc because the format rocks, but it never took off and the tooling is still lacking. MyST piggy back on markdown ecosystem, this is less of a problem.
Also, the devs behind it also have a very good track record at creating a good FOSS ecosystem.
but I think https://myst-parser.readthedocs.io/en/latest/syntax/syntax.h... is misguided; AFAIK <!-- commentary --> is legal in markdown and far less likely to surprise someone, both with an abnormal comment character as well as the forced block break
But so far I never needed to.
> And are there implementations in other languages?
That's the probably the biggest limition for myst: for now it's very new and is only implemented in Python.
I supposed it's a good opportunity to learn rust by creating a parser :)
After a few years, I gave up and switched from rST and Sphinx to Markdown and MkDocs [2]. We addressed the limitations of Markdown with PyMdown Extensions [3]. Still haven't looked back; for our specific use case of writing (computer science) teaching materials, Markdown is a better choice than rST.
[1] https://gaseri.org/en/blog/2017-07-29-why-we-use-restructure...
[2] https://gaseri.org/en/blog/2021-08-16-markdown-vs-restructur...
[3] https://facelessuser.github.io/pymdown-extensions/
What I like is how easy it is to host MkDocs on GitHub Pages via built-in support, but you can even make it behave like Jekyll with GitHub Actions. Shameless self-plug of another blog post: https://gaseri.org/en/blog/2022-11-01-publishing-material-fo...
Rather than actually solve the problem of filtering WYSIWYG input/output, providing a solution for creating easy to create and maintain semantic HTML, Mozilla shunted it aside and now use a stack of custom tooling and libraries and yet another Markdown-alike variant text format with their own scripting embeds and then patted themselves on the backs for all the effort they "saved".
Mozilla is supposed to be the standard bearer for web standards. It's sad to see that bunch of myopic techies decided to go with a trendy solution that just trashed a core principle of the organization (#6) for one of its most important products. It set an example others are now following, and as a result, MDN put the web back probably two decades.
They acted as if they tried to make it simple and easy for the community to keep MDN up and up to date. Outrageous!
The thing is that HTML (and SGML) was invented, but Markdown was discovered as a set of best practices through decades of text-only mailing lists. This is something that many people found natural enough.
It's bending perhaps history of mankind in my book a little too much, saying the author of Markdown has discovered that and not lets say, someone else the "one or other" millennia earlier.
And writing on the computer is commonly the least ergonomic form of writing at all.
Other block-level elements would auto-close either at a new line or when a new block tag starts, headers would automatically create <sections> that end when a new header appears, and inline elements would end at the next space, newline or generic end tag like </>, so they could be nested.
A lot of this is done already in the browser. A valid HTML doc just needs a doctype, title and a body tag and the spec specifies all the rest will be filled in automatically. The spaghetti logic employed to add in missing closing tags to keep pages looking decent is mind boggling. Seems like there could be a few additional spec rules and then plain-text HTML would be just as easy to create as any other markup.
Also #6 of their manifesto is about interoperability. Markdown is a great choice for this if you are consistent in your approach. No lock in, human and readible.
[0] https://orgmode.org/manual/Working-with-Source-Code.html [1] https://docs.racket-lang.org/scribble/how-to-doc.html#%28par...
As I wrote last week in a post that got flamed to pure carbon here on HN, the amount of man hours lost avoiding HTML is beyond comprehension. All of these languages are seriously flawed half-baked solutions to a problem that's already been solved.
1. https://en.m.wikipedia.org/wiki/Lightweight_markup_language
I tend to think so aswell but there is a big exception: code highlighting. Having a no-js solution to code highlighting implies having a build step to handle just that (unless you actually do it yourself while writing the docs, which would be insane). I haven't spent a lot of time researching it, but I have yet to find a tool as simple to use as e.g. Pygments or Chroma (with Sphinx and Hugo, respectively). What would you recommend?
In both cases you need to add some sort of markup to identify the code, right? In HTML it looks like:
And Markdown looks like: But in HTML, you have a bunch of options built into the file itself: A WYSIWYG editor could add the syntax highlighting before saving, a build step could add in the appropriate styles before publishing, or a JS script could be added to the page and the browser could deal with it. A Markdown file only has one option: Here's your blob of code in plain text, go find some library to convert it.HTML is just a text document that happens to have had 30 years of work put into its spec and millions of man-hours put into optimizing its Object Model and parsing engine. It can be as simple as bog-standard Markdown output, or contain all the meta data needed without relying on custom tags and other hacks.
Yes, it's extensible. But I don't want to write a role just to add bold to a reference!
Markdoc just hits the sweet spot of being super easy to get started with but elegantly extensible that makes it scale. I think the OP here simplifies a bit though of what Markdoc is. While it is pretty simple to integrate into a next.js site for a SSG doc site, it is more of a library that can be integrated into almost any site or rendering framework.
In some ways, this is the biggest "challenge" of Markdoc right now. It isn't focused on a polished out-of-the-box experience like Docusaurus or MKDocs, but is instead more of a DIY tool.
That said though, what is there is really great. With the ability to create custom tags easily and then the ability to analyze and transform an AST in a simple, but easy to understand way, I think markdoc is actually a great option for more than just building a doc site, but as a more general purpose tool for authoring any text-heavy content.
With Markdoc, I have built: * a higher level utility for creating a "library" of content with consistent ids for stable and validated links * a validation library to ensure that doc structures follows best practices like having metadata tags in the frontmatter, properly nests headers and doesn't skip H3s, etc * an integration for authoring and reusing doc content in spectacle[0] presentations * have a clear direction of how to "scale" docs-as-code as we were struggling to do that with a simple, flat file of markdown files
I have started to toy with the idea of a more general purpose CMS built around markdoc... but in general, a really great tool and kudos to stripe team for building it :)
0 - https://formidable.com/open-source/spectacle/
The docs are written as strings in a special tests directory, with special markup to mark code that is not included in the output, and special code for generating (at test-time) and creating inline iframes for results where applicable.
Code examples in docs that aren't executed will very often be wrong. That's just a fact of life. So we execute them all.
Is that how rust documentation works?
These are API docs, but mdBook[2], which generates documentation that looks like this[3], has a test command which checks the code blocks the same way.
[0]: https://doc.rust-lang.org/stable/src/alloc/string.rs.html#76
[1]: https://doc.rust-lang.org/stable/std/string/struct.String.ht...
[2]: https://rust-lang.github.io/mdBook/
[3]: https://doc.rust-lang.org/book/
PDFs I've written in Markdown and typeset using ConTeXt:
* https://pdfhost.io/v/4FeAGGasj_SepiSolar_Highlevel_Software_...
* https://pdfhost.io/v/mhw8jCJzw_autnoma
* https://dave.autonoma.ca/blog/2020/04/28/typesetting-markdow...
* https://impacts.to/downloads/lowres/impacts.pdf
I think Markdown can be used in serious documentation projects. I am biased, given that I've been working on my free and open source, cross-platform Markdown editor for several years:
https://github.com/DaveJarvis/keenwrite/blob/master/docs/scr...
I've been generating PDF documentation with Obsidian. The challange is when a document will have multi, non-technical, owners. Invariably the "solution" is to open the PDF in Word.
Thank you! My sci-fi story, autónoma, is the reason I started to work on KeenWrite, and can be fully generated from within the app. The others could be edited in KeenWrite, but there'd probably need to be some work done to get the HTML/CSS preview panel to display the various annotated sections correctly. Speech bubbles (::: bubbletx and ::: bubblerx), for example, currently work in KeenWrite, but the spectrographic lines in the Impacts Project would need to have special CSS written to render correctly in the preview.
> The challange is when a document will have multi, non-technical, owners. Invariably the "solution" is to open the PDF in Word.
Teaching people to separate content from presentation takes a lot of effort. That's also a process problem. You could ask people to provide feedback by adding notes into the PDF, rather than editing it directly.
At some point it'd be nice to see real-time collaboration added to KeenWrite, which would go a little ways to helping solve multiple users editing a single document:
https://github.com/DaveJarvis/keenwrite/issues/120
Thanks.
"The original version of Markdown by John Gruber doesn’t specify the syntax unambiguously. For example, it doesn’t have table formatting."
Table formatting is an example of a missing feature in a deliberately minimalist specification. Or possibly a feature that is handled elsewhere in the markdown "stack" (by html). So if the syntax is indeed not specified unambiguously (facts not in evidence?) then this isn't a good way of demonstrating that.
So people keep trying to add the semantic bits onto markdown, a process which I would argue destroys the genius of markdown in the first place.
Markdown is intended to be a nice looking text document. with strict limits on the format so that it can be transformed into a nice looking typeset document. If your base text document does not look great, you are doing markdown wrong. You would be better off with an actual markup language. This is also why I think markdown editors are wrong. again the whole point of markdown is to have a great looking text document, a text editor is perfect for this, any other specialized editor will produce a bad looking document.
On the flip side, the stuff in the pile mostly wasn't authored by technical writers. The people who used tabs and blank lines for formatting and boldface+font size changes for section heads would be probably just create the same kind of semantic messes, but with the added bonus of having a BOM marker at the head of the document and CRLF line endings.
Say that I generate a table using asciidoc's built-in syntax, the output will always generate HTML elements with the CSS classes already defined:
For me, this output is needlessly verbose for a setup that uses nothing but default flags. Worse, it doesn't provide much of a leeway to change the classes or even let me use some other ways to style the elements.I prefer markdown's (and markdoc's) approach to styling, in that it doesn't really try to define any. My take on this is that stylings of the output should be be coupled with the toolings, as opposed to being bolted into the language standards.
edit: formatting
> GFM is, by far, the most popular flavor of Markdown.
It is very sad because gfm is essentially "done" evolving. There's no desire from people I've spoken with to improve the implementation or add new features. For example: Multiline tables.
> Many tech companies love the rich ecosystem of Remark to transform Markdown with plugins. Still, extendability is the subject where Markdown scores the lowest.
The state of the world here is quite painful. I'd also like to say a prayer for anyone else out there writing custom extensions to cmark-gfm in c.
> reStructuredText offers a number of useful directives out-of-the-box. For example, admonitions (“safety messages” or “hazard statements”) can appear in rST like this...
We've been able to implement this as an extension in cmark-gfm and hoedown. It is quite painful but it is doable.
Markdown is just as extendable if you have control of all of the parsers and rendering code for your organization. This is no small feat.