31–40 of 89 posts
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.
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.
Maybe there's a great static site generator written in GO with strong Asciidoc support??
Antora is new to me as well, will review.
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 contribu…
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...
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
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…
My experience of Docutils is that it is a half finished undocumented mess. It doesn't really matter how good RST's syntax is.
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 contribu…
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.
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 center…
> 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 "stand…
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 center…
> 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 "stand…
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.
Earlier quoted context omitted.
> 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 "stand…
Isn't that essentially what Jupyter does?
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…
My experience of Docutils is that it is a half finished undocumented mess. It doesn't really matter how good RST's syntax is.
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.