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

51–60 of 89 posts

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

#51

Post by taink »

russellbeattie wrote: post #34

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.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 to find a tool as simple to use as e.g. Pygments or Chroma (with Sphinx and Hugo, respectively). What would you recommend?

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

#52

Post by mdaniel »

BiteCode_dev wrote: post #30
wbamberg wrote: post #26

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…

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…

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 is legal in markdown and far less likely to surprise someone, both with an abnormal comment character as well as the forced block break

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

#53

Post by thangalin »

PaulWaldman wrote: post #47
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…

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.

> 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

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

#54

Post by MrVandemar »

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

If you avoid closing things that don't need to be closed, and use whitespace (and a syntax-highlighting editor) it's easy to write and easy to eye-parse.

No includes though.

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

#55

Post by somat »

Markdown is pretty great, I would even say the idea is genius. however markdown is a terrible markup language, it completely fails to add any sort of semantic meaning to the text.

So people keep trying to add the semantic bits onto markdown, a process which I would argue destroys the genius of markdown in the first place.

Markdown is intended to be a nice looking text document. with strict limits on the format so that it can be transformed into a nice looking typeset document. If your base text document does not look great, you are doing markdown wrong. You would be better off with an actual markup language. This is also why I think markdown editors are wrong. again the whole point of markdown is to have a great looking text document, a text editor is perfect for this, any other specialized editor will produce a bad looking document.

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

#56

Post by wbamberg »

vedranm wrote: post #33
wbamberg wrote: post #26

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…

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

Thanks @vedranm! I especially like your side-by-side comparison of the process of contributing using Markdown versus reST. It really encapsulates the difference that reasonably seamless tool support makes. I need to look more into MkDocs...

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

#57

Post by cratermoon »

I would accept any of those instead of the steaming pile of Word docs full of screenshots, bloated PowerPoint presentations, PDFs and various other proprietary formats we have at my current job.

On the flip side, the stuff in the pile mostly wasn't authored by technical writers. The people who used tabs and blank lines for formatting and boldface+font size changes for section heads would be probably just create the same kind of semantic messes, but with the added bonus of having a BOM marker at the head of the document and CRLF line endings.

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

#58

Post by cratermoon »

benatkin wrote: post #39
cratermoon wrote: post #37

Earlier quoted context omitted.

Isn't that essentially what Jupyter does?

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

Ah yes, it's stored as JSON, but look at all those "cell_type": "markdown", interspersed with the code cells. From the standpoint of a user, a Jupyter notebook is code and markdown interspersed.

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

#59

Post by nine_k »

russellbeattie wrote: post #36
wbamberg wrote: post #26

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…

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!

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

#60

Post by saltymimir »

In my (admittedly) brief experience dabbling with asciidoc, I really don't like the opinionated approach on how styles should be injected to the generated HTML output.

Say that I generate a table using asciidoc's built-in syntax, the output will always generate HTML elements with the CSS classes already defined:

    
      
        
        
      
      
        
          Column heading 1
          Column heading 2
        
      
      
        
          Column 1, row 1

         Column 2, row 1

        
        
          Column 1, row 2

          Column 2, row 2
For me, this output is needlessly verbose for a setup that uses nothing but default flags. Worse, it doesn't provide much of a leeway to change the classes or even let me use some other ways to style the elements.

I prefer markdown's (and markdoc's) approach to styling, in that it doesn't really try to define any. My take on this is that stylings of the output should be be coupled with the toolings, as opposed to being bolted into the language standards.

edit: formatting

Post reply on HN