Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

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

dewanahmed.com

Post reply on HN
Print view View original

71–80 of 89 posts

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

#71

Post by hakre »

nine_k wrote: post #59
russellbeattie wrote: post #36

Earlier quoted context omitted.

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…

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.

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

#72

Post by darekkay »

jszymborski wrote: post #13

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.

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.

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

#73

Post by tadfisher »

MrVandemar wrote: post #54
spaniard89277 wrote: post #7

I would say HTML?

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. The Great Novel of All Time Chapter One It was a dark and stormy night. Suddenly a shot rang out! A door slammed. The maid scream…

Whitespace collapsing just sucks, though. The SGML roots hamper HTML's ergonomics for human writers.

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

#74

Post by BiteCode_dev »

josephg wrote: post #62
BiteCode_dev wrote: post #30

Earlier quoted context omitted.

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…

Oh that’s lovely. Does it also support note blocks (like are used to render that page)? And are there implementations in other languages?

Yes, all admonitions (note, warning, danger) are supported, and worst case scenario, you can fallback on inlined rst if you really miss something.

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

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

#77

Post by nine_k »

hakre wrote: post #71
nine_k wrote: post #59

Earlier quoted context omitted.

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 this way.

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.

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

#78

Post by edurl »

bitexploder wrote: post #66
thangalin wrote: post #45

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

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.

I would love to know more about this documentation pipeline. Anything you can share (repos, docs, tooling...?)

Thanks.

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

#79

Post by boxed »

pie_flavor wrote: post #64
boxed wrote: post #43

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.

One of my favorite features about Rust: this is the default for all documentation comments, and thus for auto-generated API docs.

This documentation page: https://docs.iommi.rocks/en/latest/forms.html is generated from this pytest source: https://github.com/TriOptima/iommi/blob/master/docs/test_doc...

Is that how rust documentation works?

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

#80

Post by pie_flavor »

boxed wrote: post #79
pie_flavor wrote: post #64

Earlier quoted context omitted.

One of my favorite features about Rust: this is the default for all documentation comments, and thus for auto-generated API docs.

This documentation page: https://docs.iommi.rocks/en/latest/forms.html is generated from this pytest source: https://github.com/TriOptima/iommi/blob/master/docs/test_doc... Is that how rust documentation works?

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/

Post reply on HN