What about MDX?
https://ghostinspector.com/blog/rebuilding-jekyll-website-ne...
Markdown, Asciidoc, or reStructuredText – a tale of docs-as-code
61–70 of 89 posts
Re: Markdown, Asciidoc, or reStructuredText – a tale of docs-as-code
#62Last 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 contribu…
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?
Re: Markdown, Asciidoc, or reStructuredText – a tale of docs-as-code
#63Last 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 contribu…
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…
What's holding the web back by 20 years are . 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.
Re: Markdown, Asciidoc, or reStructuredText – a tale of docs-as-code
#64We 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.
Re: Markdown, Asciidoc, or reStructuredText – a tale of docs-as-code
#65Wikipedia 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.wikip…
> 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…
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:
let a = "foo";
```js let a = "foo"; ```
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.
Re: Markdown, Asciidoc, or reStructuredText – a tale of docs-as-code
#66> 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.
Re: Markdown, Asciidoc, or reStructuredText – a tale of docs-as-code
#67Earlier 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…
What's holding the web back by 20 years are . 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 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.
Re: Markdown, Asciidoc, or reStructuredText – a tale of docs-as-code
#68(Opinions are my own)
> 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.
Re: Markdown, Asciidoc, or reStructuredText – a tale of docs-as-code
#69Last 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 contribu…
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…
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.
Re: Markdown, Asciidoc, or reStructuredText – a tale of docs-as-code
#70Once you learn a language like markdown, why even bother with the markup? You know what denotes a header or whatever in the source. You might as well just write in plain text and not bother with the markup at that point once you’ve set up these formatting guidelines for yourself. Plain text readmes worked for like 50 years so far, they seem fine.