[HN Gopher] Markdown, Asciidoc, or reStructuredText - a tale of ...
___________________________________________________________________
Markdown, Asciidoc, or reStructuredText - a tale of docs-as-code
Author : mooreds
Score : 105 points
Date : 2022-11-04 15:20 UTC (7 hours ago)
(HTM) web link (www.dewanahmed.com)
(TXT) w3m dump (www.dewanahmed.com)
| billforsternz wrote:
| 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.
| wbamberg wrote:
| 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.
|
| If you're interested, we blogged about this project:
| https://openwebdocs.org/content/posts/markdown-conversion/.
| russellbeattie wrote:
| 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.
| BiteCode_dev wrote:
| 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.
|
| 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.
| mdaniel wrote:
| https://myst-
| parser.readthedocs.io/en/latest/syntax/syntax.h... is
| excellent, and one of my major pain points. I usually give up
| and just use ` when I need to talk about backticking in
| markdown but that idea is much, much better
|
| 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
| vedranm wrote:
| 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.
|
| [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/
| ComputerGuru wrote:
| 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!
| e12e wrote:
| Surely, these are also markdown headers? Big
| === Small -----
|
| I actually prefer those when editing in a text editor - like a
| nicely formatted plain text email.
| giobox wrote:
| 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.
| addisonj wrote:
| 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 :)
|
| 0 - https://formidable.com/open-source/spectacle/
| thangalin wrote:
| > Most folks mention that Markdown is not suitable for serious
| documentation projects.
|
| 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...
| PaulWaldman wrote:
| 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.
| thangalin wrote:
| > These look great! Were these generated with KeenWrite?
|
| Thank you! My sci-fi story, autonoma, 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
| all2 wrote:
| 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.
|
| [0] https://orgmode.org/manual/Working-with-Source-Code.html [1]
| https://docs.racket-lang.org/scribble/how-to-doc.html#%28par...
| benatkin wrote:
| 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.
| euroderf wrote:
| > 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 ?
|
| Someone pls correct me if I'm OTL.
| benatkin wrote:
| 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.
| cratermoon wrote:
| Isn't that essentially what Jupyter does?
| benatkin wrote:
| It's in JSON at least by default. Here's an example: https:
| //github.com/tensorflow/examples/blob/master/courses/u...
| deathanatos wrote:
| 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._
|
| 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.)
| IshKebab wrote:
| My experience of Docutils is that it is a half finished
| undocumented mess. It doesn't really matter how good RST's
| syntax is.
| WorldMaker wrote:
| 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.
| bonzini wrote:
| docutils is a mess, sphinx tooling and extensibility are much
| better though.
| innocentoldguy wrote:
| 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.
| jszymborski wrote:
| 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.
| pbronez wrote:
| I agree. Every time I think about picking a markup language, I
| wind up wanting to use Asciidoc but then getting frustrated by
| the tooling.
|
| Maybe there's a great static site generator written in GO with
| strong Asciidoc support??
|
| Antora is new to me as well, will review.
| sofixa wrote:
| Hugo (a great static site generator) supports Asciidoc, but
| it needs Asciidoc for the parsing.
| e12e wrote:
| I thought the answer always was "pandoc" when the question was
| (un)structured markup...
| kevin_thibedeau wrote:
| 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.
| innocentoldguy wrote:
| Antora is pretty nice for large documentation projects. For
| smaller projects, you may want to try 11ty and the Asciidoctor
| plugin: https://github.com/saneef/eleventy-plugin-asciidoc
| Tomte wrote:
| Maybe a solution: AsciidoctorJ is an official JVM port (using
| JRuby). You just get the jar file and execute it.
| geokon wrote:
| 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
| russellbeattie wrote:
| 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.
|
| 1. https://en.m.wikipedia.org/wiki/Lightweight_markup_language
| taink wrote:
| > 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?
| mooreds wrote:
| 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?
| subpixel wrote:
| Stripe's Markdoc (markdoc.dev) is very promising.
|
| 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.
| fluidcruft wrote:
| Two things on my radar to check out are MyST markdown and
| quarto.
| macintux wrote:
| The creator of Pandoc is creating a markup language worth
| looking at: https://djot.net/
| macintux wrote:
| Related recent discussion: Elements Of a Great Markup Language
|
| https://news.ycombinator.com/item?id=33381373
| packetlost wrote:
| 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
| BiteCode_dev wrote:
| Same.
|
| 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.
| boxed wrote:
| 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.
| keybored wrote:
| 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.
| euroderf wrote:
| 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) ?
| LukeShu wrote:
| 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.
| kzrdude wrote:
| 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.
| ilyt wrote:
| 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...
| NoThisIsMe wrote:
| What is "regular markup"?
| keybored wrote:
| Markup not of the lightweight kind.
| spaniard89277 wrote:
| I would say HTML?
| breck wrote:
| Why not all 3 at once: https://scroll.pub/public/blog/indented-
| heredocs.html
| runningmike wrote:
| 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
___________________________________________________________________
(page generated 2022-11-04 23:00 UTC)