Markdown, Asciidoc, or reStructuredText – a tale of docs-as-code

This page summarizes the projects mentioned and recommended in the original post on news.ycombinator.com

Our great sponsors
  • SonarLint - Clean code begins in your IDE with SonarLint
  • InfluxDB - Build time-series-based applications quickly and at scale.
  • SaaSHub - Software Alternatives and Reviews
  • macchiato

    Markdown can literally be code. 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 notebook tool. https://github.com/ResourcesCo/macchiato/blob/main/scripts/m... https://github.com/ResourcesCo/notebook

  • notebook

    Markdown can literally be code. 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 notebook tool. https://github.com/ResourcesCo/macchiato/blob/main/scripts/m... https://github.com/ResourcesCo/notebook

  • SonarLint

    Clean code begins in your IDE with SonarLint. Up your coding game and discover issues early. SonarLint is a free plugin that helps you find & fix bugs and security issues from the moment you start writing code. Install from your favorite IDE marketplace today.

  • oauth2-proxy

    A reverse proxy that provides authentication with Google, Azure, OpenID Connect and many more identity providers.

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

  • djot

    A light markup language

    The creator of Pandoc is creating a markup language worth looking at: https://djot.net/

  • eleventy-plugin-asciidoc

    Eleventy plugin to add support for AsciiDoc.

  • examples

    TensorFlow examples (by tensorflow)

    It's in JSON at least by default. Here's an example: https://github.com/tensorflow/examples/blob/master/courses/u...

  • KeenWrite

    Free, open-source, cross-platform desktop Markdown text editor with live preview, string interpolation, and math.

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

    https://github.com/DaveJarvis/keenwrite/issues/120

  • InfluxDB

    Build time-series-based applications quickly and at scale.. InfluxDB is the Time Series Platform where developers build real-time applications for analytics, IoT and cloud-native services. Easy to start, it is available in the cloud or on-premises.

  • iommi

    Your first pick for a django power cord

    is generated from this pytest source: https://github.com/TriOptima/iommi/blob/master/docs/test_doc...

    Is that how rust documentation works?

  • mdBook

    Create book from markdown files. Like Gitbook but implemented in Rust

    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.

    [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/

  • book

    The Rust Programming Language

    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.

    [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/

NOTE: The number of mentions on this list indicates mentions on common posts plus user suggested alternatives. Hence, a higher number means a more popular project.

Suggest a related project

Related posts