On why Markdown is not a good, or even a half-decent, markup language | Hacker News Reader

On why Markdown is not a good, or even a half-decent, markup language

schwarze.bsd.lv

65 pointssmartmic109 comments

> So, the bottom line is: Do not use markdown. Do not use DocBook. Do not use Texinfo. Use mdoc(7) to maintain your source documents, and mandoc(1) to convert them when needed

Cool, let’s see what mdoc looks like:

> The following is a well-formed skeleton mdoc file for a utility "progname":

    .Dd $Mdocdate$
    .Dt PROGNAME section
    .Os
    .Sh NAME
    .Nm progname
    .Nd one line about what it does
    …

So, utterly incomprehensible. I’ll stick to Markdown, thanks!

It will never cease to amaze me how out of touch some technical people are... including the author of this markdown rant.

And the person that wanted to use PDF as web pages instead of HTML.

Agreed! I think this is the main problem with Markdown:

> The most official reference manual for markdown is the original one written by John Gruber in 2004. It is unmaintained since that time and leaves various ambiguities, such that different parsers tend to parse input somewhat differently in detail.

Its ridiculous that it hasn't been updated, though there have been some attempts.

You learn markdown by looking at a half page example for 5 minutes, you learn this abomination by studying a spec document. bad

Yeah, I also looked at mdoc and came to almost the same conclusion.

He's only saying if you want to write man docs use the syntax designed for it... Ok. It's horrible to read and write but it's probably the best thing to use.

OTOH if you want to write simple plain text that humans can read and write with no difficulty at all, but can also make nice richer text if you want, markdown is great.

Markdown obviously has a place and I quite like it, but if someone wants more expressiveness, I think Typst’s language does a very good job of being similar to markdown, yet giving you everything LaTeX can.

Unfortunately it doesn’t yet have an HTML export version (I would be okay with a simplified one as well for now, like only do paragraphs, emphasis, etc)

Didn't know about typst. Looks quite nice, I like that you can embed LaTeX style maths in it, but it is still quite readable.

Thank you for bringing up Typst, it is completely awesome, SO useful.

This is exactly what markdown achieves: comprehensible even when it is not rendered. Yet the author completely ignores that feature.

pandoc and ronn can also output roff man pages. Markdown is great for accessible, generic use without a need for special features. For special features or formatting, abstraction can be a hindrance. statamic, jekyll and such use YAML frontmatter for embedding metadata but it's not a full replacement for HTML or lossless HTML formats like slim, haml, pug, ace, macdom.

I always need a cheatsheet when using roff or latex because they're too much to remember if you're not using it everyday.

"Markdown is pitifully weak and powerless" because it lacks (obscure feature author wants).

If you want features, use a word processor, or LaTex, or something. Markdown is for documents that need only very basic formatting.

The future of this is probably some AI-based system where you put in raw text and tell the system "make it look good ... no, make it look more like a Medium article...optimize for SEO..."

Latex was invented to distract people who otherwise would overly complicate other things

I dunno if that what you meant, but it was pretty much designed so that the people that want to complicate everything go there complicating it, while the people that want to write something useful can just take complicators' work, use it, and raise their shoulders at every objection repeating "you are the one that designed it this way".

The original TeX doesn't work this way. That's why people don't collaborate directly in it.

I am with GP. When using LaTeX I was happy that it was difficult to easily change things. I had a thesis to write and took the solution that would create something good (even if I would not agree) and prevent me from easily choosing fonts for headers etc.

The keyword here is "easily". Of course I could learn the language and go wild. But, hey, I had a thesis to write so I had to make choices: PhD or fancy headers.

Nawh, it was invented to reinvent PostScript and create a barrier-to-entry to academic publishing.

Seriously, I still can't find a decent WSYSIWYG latex editor with the UX of the legacy Word equation editor or a graphing calculator. The closest I found was [0].

0. https://latexeditor.lagrida.com

> The future of this is probably some AI-based system where you put in raw text and tell the system "make it look good

This "boring" type of use is what makes me so damn excited for AI: reduction of low skill monotony.

To add on, can't you generally embed html where needed?

That's covered a bit in the article, but as a negative - in that to implement markdown you now need HTML parsing too.

ChatGPT can probably do that right now

This advice does appear to be coming from someone who writes webpages using roff... The core argument simply seems to be that markdown lacks sufficient structure to build "documents," which I agree is absolutely true and essentially part of the design.

IMO Markdown isn't intended to structure documents; it's intended to enhance plain text. If you find yourself constantly tweking at whitespace or special characters to provoke your markdown to behave, or if you are using so many features of md that you have to keep a reference handy, maybe you ought to use something different.

As an aside, I have used Front Matter (essentially a YAML header on markdown) for cases when a bit of structure or metadata is needed alongside a blob of text, and I think it strikes a great balance between writability and structure.

Markdown tables need to die in a fire though; what a wreck.

Is it meant to be? The appeal of Markdown is that it's easy to remember, reasonably friendly to non-technical people, and it looks good as plain text.

It’s even more than that - it’s a codification of plain text formatting conventions.

If you write a plain text document and you format it following markdown principles, you get a simple rich text version of your document for free. Your headings will be headings, your bullet points will be bullet points, and your code blocks will be code blocks.

Now, you can also ‘game’ markdown, writing the minimum possible plaintext to ‘trick’ it into making a pretty document while leaving the plain text ugly.

But in general, the idea of markdown is to start from ‘imagine I have a bunch of plain text files I’ve been formatting consistently for years. How can I make them look nice as rich text?’

I was about to say; even before I knew markdown, I was using a lot of its conventions informally. I was using # to denote headers, and surrounding things with asterisks to emphasize them, using > to denote quotes. When I found out about markdown, it took me about ten minutes to learn because it was stuff I was largely already doing.

For sure. I'd call it an excellent bad markup language. I use LogSeq daily and as a practical matter I much prefer Markdown to, say, Evernote's WYSIWYG approach, which was more of a pain to use and left me with notes so broken that they are impossible to fix. Or to this author's theoretically better system HTML, because it's more of a pain to write. Basically Markdown cares about formatting about as much as I do, which is barely.

I'll note this tension has a long history in CS: https://en.wikipedia.org/wiki/Worse_is_better

And I think it has a lot to do with a very particular notion of good, which is something like "conceptually pleasing to someone who has mastered the space".

It’s also fast and efficient to type on the keyboard. Plus it feels very natural. Much more natural than for example html or even bbcode, when you are typing out text.

Markdown is an authoring language (it's easy to write) rather than a publishing language (like XML, which is mostly replaces, which sucks to write in).

That’s a perfect way to put it! :)

> It’s also fast and efficient to type on the keyboard. Plus it feels very natural.

If you are solely an English writer then yes. Using md with some languages will quickly turn you into its hater. Certain formatting symbols aren’t easily accessible in some layouts, like backticks for code or ^ for superscript. Some symbols require extra keystrokes like ~ in german. Some layouts will require finger yoga exercises. Basically, any other text markups based on English (including LaTeX) are unfriendly to other languages. Thus an abnormal popularity of md across the apps makes them much less friendly for non-English users. Mobile typing pushes this pain to another level.

Yeah. My native language has some very awkward placements of certain symbols as well actually. But I chose to sacrifice the letters æ, ø, å years ago by switching to using US-based layouts on my computers. Sometimes I use Dvorak layouts (even have a custom one I made for my mechanical keyboard that I sometimes use). Most of the time I write on a computer in recent years has been using the keyboard on my MacBook Pro computers with just US QWERTY. I very rarely type anything in my native tongue on the computers. Mainly just on the phone. And I am 97% sure that the times I need æ ø å on my macOS laptops I can long-press or option click some of the related characters like a and o.

For a while, when I originally switched away from my native language QWERTY variant, I would sometimes need æ ø å on the computer and I would Google aelig oslash and aring respectively and find the symbols for those letters that way :p

So much this. I think I must be missing something here about the context here, but even then I think it's extremely hyperbolic for the author to make the leap from "I don't like Markdown for [x]" to "Markdown is objectively bad and should never be used in any context."

Just look at some of these other examples the author lauds. I've been writing code for most of my life and I find roff's manpage to be absolutely inscrutable. I don't understand the context in which you'd need to pick between roff and Markdown, they seem like they're solving completely different problems for totally different audiences.

Likewise, asciiflow.com serves something that isn't a good, or even half-decent graphics package for diagramming.

Yet, I had to crank out diagrams recently, and found every single program I knew had become enshittified to the point of not being usable.

I got the job done with asciiflow box-and-arrow diagrams, pasted into a word processing document as monospaced-font paragraphs.

I like https://mermaid.live if https://excalidraw.com/ is not an option.

This is kind of absurd. Markdown has very specific use cases. For example, using any number of free apps, you can maintain a folder of notes that are human-readable, machine-parsable, that will effectively be useful forever.

You’re really gonna keep that folder of text files in “very good” LaTeX??

All the things are tools in the toolbox.

Nits:

Markdown is general purpose but limited. It's a big improvement on plain text files. Thank you Aaron Swartz (RIP) and John Gruber.

I sure don't hand-code doc directly in PDF or PostScript formats, although people used to do the latter before TeX was ubiquitous.

Comparing Markdown and LaTex is silly. One is intended for intuitive plain text input, the other is, as the author points out, almost a full postscript style programming language. I don’t know what mdoc is optimizing for, but it’s sure not intuitive.

This post feels like a rant by someone who’s just having a bad day. Not sure why it’s even on HN.

It is not a markup language, period.

...It's a great convention on how to do common stuff in plain text. Plain text. Let me repeat: plain text.

(I'm accidentally doing "a different todo list approach" now due to it, and it is so surprisingly awesome; sorry, busy doing stuff off of my "weird todo list"!)

> It is not a markup language, period.

The clue being right there in the name.

Wow, my mind is kind of blown. How did I not notice that before?

Don't worry, you're not alone. And I think we didn't notice because... there are no markup tags anywhere to be noticed!

Hey, can you describe your surprisingly awesome approach? I am curious.

Instead of thinking in terms of "list items" think in terms of... days.

There is only so much that can be done in a day but it is very reassuring to see just at a glance what was actually done. Also, this makes never-ending lists pruning super easy and peaceful - "if this item has been carried over for a month and I haven't touched it then it means it's not needed".

And all I use for this is gedit (which is notepad.exe with syntax highlight if you so desire) and have the .txt files sync to my Nextcloud instance.

(Note: So far I use it only for personal projects mixed with day-to-day chores.)

Notepad.exe does plain text. Markdown adds all kinds of extra.

My summary of this rant: Ivory Tower bullshit

Markdown is phenomenal. It gives end users simple and easy to remember ways to perform the most common formatting operations but leaves the text in a state that it was be parsed by humans without an actual markdown renderer.

Personally I highly prefer Asciidoc. It’s like md, but is (much) better defined. And it works on GitHub too! https://docs.asciidoctor.org/asciidoc/latest/asciidoc-vs-mar...

Is everyone forgetting the original purpose of Markdown as described by its creator?

https://daringfireball.net/projects/markdown/

Probably. Everyone has also long since forgotten the original purpose of HTML! ;-)

Ah yes, to have flashing marquee text scroll across the screen. The good old days :D

Here are a few Markdown documents I've typeset into PDF:

* https://impacts.to/downloads/lowres/impacts.pdf

* https://pdfhost.io/v/4FeAGGasj_SepiSolar_Highlevel_Software_...

* https://dave.autonoma.ca/blog/2020/04/28/typesetting-markdow...

My text editor, KeenWrite[1] (see tutorials[3] for details), converts from Markdown to XHTML. The XHTML is then typeset using the ConTeXt typesetting software to create a PDF. The PDF is stylized using a theme[2].

What Markdown is missing, in particular flexmark-java, is a standard CommonMark extension for cross-references and citations[4].

[1]: https://github.com/DaveJarvis/keenwrite

[2]: https://github.com/DaveJarvis/keenwrite-themes/tree/main/exa...

[3]: https://www.youtube.com/playlist?list=PLB-WIt1cZYLm1MMx2FBG9...

[4]: https://talk.commonmark.org/t/cross-references-and-citations...

This is a great opportunity to extol the superior text layout capabilities of Latex. In your third pdf [1], look at page 2, para starting from "No doubt...". Compare to the same rendered in plain latex [2]. Two problems that jump immediately.

* There are six word breaks in your pdf, zero in the latex version. (well, good-nature is a compound word in the original text).

* Notice the "river" [3] of spaces that runs downs from "Enfield"

I have no idea why other fixed layout engines don't adopt the superior text-layout algorithms of latex.

[1] https://dave.autonoma.ca/blog/2020/04/28/typesetting-markdow...

[2] https://i.imgur.com/Rs7ai0G.png

[3] https://en.wikipedia.org/wiki/River_(typography)

> There are six word breaks in your pdf, zero in the latex version. (well, good-nature is a compound word in the original text).

I use ConTeXt. ConTeXt uses the same Knuth-Plass algorithm for line breaks as LaTeX. I've allowed ConTeXt to hyphenate liberally. There is a setting to control hyphenation. See lesshyphenation, morehyphenation:

https://wiki.contextgarden.net/Command/setupalign

> Notice the "river" [3] of spaces that runs downs from "Enfield"

ConTeXt probably has tweaks for this as well. Keep in mind, I typeset Jekyll and Hyde in 2020 and am not a ConTeXt expert; ConTeXt has had countless improvements since then.

> adopt the superior text-layout algorithms of latex

Pretty sure ConTeXt is capable of producing the same quality of document as LaTeX.

* https://wiki.contextgarden.net/Documentation

* https://tex.stackexchange.com/questions/36/differences-betwe...

* https://tug.org/levels.html

KeenWrite looks cool and useful; thanks for the reference.

It does appear that the real heavy lifting in this workflow is still all done by TeX, and that Markdown (with lots of extensions) is more or less a database of blobs to feed the template engine.

I would suggest the question: Is what you have at the end really a Markdown document if it has no context without KeenWrite's extensions or templates? I think the article under discussion is a bit pedantic, but I'm pretty sure the author would say that what you end up with is a KeenWrite document.

> I'm pretty sure the author would say that what you end up with is a KeenWrite document.

Documents written in KeenWrite can be typeset using tools that already exist:

* https://pandoc.org/

* https://yihui.org/knitr/

* https://github.com/jfisteus/html2xhtml

I've kept compatibility with pandoc (CommonMark) and knitr a priority; I wrote KeenWrite to replace a shell script that was calling out to those software packages. My Typesetting Markdown blog posts dive into that script and programs:

https://dave.autonoma.ca/blog/2019/05/22/typesetting-markdow...

Further, KeenWrite only supports plain TeX, which means that the typesetting system can be any software that is TeX-compatible: LaTeX, ConTeXt, LuaTeX, ExTeX, KaTeX, etc.

Yes I was being a bit pedantic as well! :)

Seriously though I do like the workflow you've put together with KeenWrite. I have a potential application where it might be a great fit to replace some markdown->pdf workflows I have built. In my case, I use a Front Matter header to pass structured data along with the markdown to generate templated HTML which can then be "typeset" with the extensions provided by HTMLDOC or wkhtmltopdf.

Thanks again for posting and replying. Pleased to make your acquaintance.

> Thanks again for posting and replying. Pleased to make your acquaintance.

Likewise!

> I use a Front Matter header to pass structured data

The impetus for developing that shell script (ergo KeenWrite) was using variables in documents. KeenWrite injects structured, interpolated YAML strings back into documents by replacing Moustache syntax (or `r# ...` syntax for R docs). This means that the same structured data can be reused for multiple documents, allowing for single sources of truth and a clean separation of content from presentation. Also, variables can be used in diagrams.

As for Front Matter, data can be passed in from the command line[1]:

    -v metadata.yaml \
    --metadata="title={{book.title}}" \
    --metadata="author={{book.author}}"

Under the hood, KeenWrite places the metadata inside the intermediate XHTML document as <meta> tags inside the <head>. These are parsed by ConTeXt using an XSLT-like syntax that converts them into TeX instructions[2].

Do post any questions you may have on the discussions forum[3].

[1]: https://github.com/DaveJarvis/keenwrite/blob/main/docs/cmd.m...

[2]: https://github.com/DaveJarvis/keenwrite-themes/blob/main/xht...

[3]: https://github.com/DaveJarvis/keenwrite/discussions/

I'd be interested in KeenWrite if it supported MacOS. Your pandoc/ConTeXt guide is top notch. ConTeXt is very underrated.

It's written in Java. People have run it on MacOS. I don't have a .dmg file, though.

https://github.com/DaveJarvis/keenwrite#other

If that doesn't work for you, please open an issue and describe what you'd like for MacOS.

I stand corrected. Thank you!

On LaTeX:

> Little context sensitivity

... this is close to a disqualifyingly wrong statement.

(I literally work with Markdown on a daily basis as my actual day job. Markdown really does suck.)

The only way in which (La)TeX is not context sensitive is that it's sensitive to the entire global TeX state at all times. There's no notion of grammar in TeX, _at all_. It's hard to trust the rest of the content in there after this.

Strong agree on the lack of a decent definition list notation. Strong agree on roff. Moderately strong on most of his critique Pretty strong disagree that markdown is an abominably bad choice: it's problems are fixable.

A single canonical reference and a little restraint and a dl definition would do it for me, regarding man page creation.

>A single canonical reference

https://commonmark.org/

(2014 updated 2021) the original OpenBSD article is (2017) and there's still no good canonical DL instantiation -commonmark goes into "do it in HTML" which is .. FAIL in my book.

So, a "standard" which has been continuously revised since 2014 and doesn't have definition lists except as "use HTML"

That was the best attempt to update it and improve upon it.

Its mostly successful, but not entirely. Wish Gruber would just link to that instead of his old, bugger, out of date spec.

> [Markdown] allows embedding arbitrary HTML code, both at the block and at the flow level. That makes writing any parser for it very hard because you basically have to include a full HTML parser and then add context sensitive complications...You also have to worry about all the security caveats of HTML. For example, HTML allows embedding Javascript, so you get to implement a Javascript interpreter as well, and to secure it.

Is it just me, or is a JavaScript interpreter irrelevant to a Markdown parser?

Markdown "supports" embedded HTML but that does not mean that your chosen implementation must support it. Personally, I think it's a misfeature and wouldn't want to touch any markdown lib that tried to put too much emphasis on something like validating or sanitizing HTML and Javascript. That's a project with too much scope creep.

It is. I know of zero Markdown implementations off the top of my head that bother to parse JavaScript - if there's JS embedded in HTML embedded in Markdown, it gets passed through as a block element on the HTML side (which may or may not be parsed, either).

TFA is drawing at straws to dunk on a format they don't like.

  #Heading

  Here's why allowing arbitrary HTML and JS in your Markdown makes parsing painful

  <script>
    console.log("</script> is a closing tag for script blocks");
  </script>

I haven't seen anything new in this space and I just finished a project using a markdown format I invented called Tagged{Text}. I'm happy to present it here for your consideration.

In creating my blog and static site I started using Markdown but couldn't get around the limitations. So I invented a simple file format for tagging text into a tree like structure. It has a formatting style modeled after LaTeX. It has served me well (two websites and two blogs).

I call it an "agnostic markdown format" because no tags are defined ahead of time. The user defines everything and writes python filters to generate the output from the tags. I have lots of python code to parse and generate HTML. It has a macro processor, calculator, git date, and other useful tags.

Here is an article about Tagged{Text}: https://etcutmp.com/taggedtext.html Another website built using this format: https://etcutmp.com/evolve5 Source Code: https://github.com/kjs452/tagged_text Source Code for the second website: https://github.com/kjs452/Evolve5Help

The main python file is: taggedtext.py (the parser). All the other python code are filters to generate or transform the tagged text tree into something else. For example, tt_macros.tt implements the DEFINE{} tag.

When you have a certain kind of mind, you tend to see "simplicity" in a way that might not be recognizable to others. I think Mr. Schwarze might be one of those minds, seeing his history with Free/OpenBSD.

Markdown's fantastic for generating pure HTML. However, if I had a print deliverable, or any complicated function like transclusion or conditionals, I'd maybe nudge the user to try out an alternative, Asciidoc or something else.

Why do I say that when you can do so many cool things with Markdown? Well, "so many cool things" is sort of the problem. You build up a unique Mkdwn/Extension/<Insert_Framework_Of_Choice/> stack every time you do a "cool thing", until eventually you're writing docs for what is, in effect, a bespoke parser. Knock out one block of that - say, like, your company's InfoSec department decides that technical writers having NPM is a Very Bad Idea - and your cool thing gets scaled back or broken outright. It's much better for your docs' lifecycle to use just the core of the spec, and not be dependent on a flurry of extensions and dependencies for the business of making docs.

I don't include edge uses, where extensions excel. To take one example, Mr. Rojas' excellent WireViz program (https://github.com/wireviz/WireViz). If that gets knocked out, my document still builds into PDFs.

The price you pay, of course, is a more niche ecosystem; Asciidoc tooling is maybe a tenth or a fiftieth of what's dedicated to the M*kd*n Multiverse. And of course, if you're writing simple docs that go straight to HTML without so much as thinking about a print layout, then Markdown is the easy choice.

I think the people commenting that this isn't what markdown is for should take up their argument with the people who were saying that openbsd should rewrite all the man pages in markdown.

> "Abominable"

The author refers to Markdown as "Abominable" at the end of the page.

I am always skeptical when someone has this level of disdain for any technology. The overall argument that "Markdown is bad" would be stronger if they noted the pros of Markdown, and why the pros are less valuable in aggregate than pros of other languages.

I came to the same conclusion while trying to work out a good documentation single-sourcing setup that could successfully target multiple formats like markdown, mdoc, be injected into code, etc.

I still use markdown for what it does well, but I feel like virtually every other (lightweight) markup language misses the mark as well.

Last year I started writing some posts that are about this in a very vague way (6 so far at https://t-ravis.com/room/doc/) to help order my own thinking and lay some groundwork for eventually demonstrating where a lot of them fall short.

(Caveat: I'm not suggesting anyone stop using them for any given project that doesn't need to target multiple output formats. They aren't unusable. They just all have problems that make virtually all of them difficult to use as a single source.)

For technical documentation? Sure, I see how the alternatives make more sense. But for more general use, like formatting shorter posts on forums and social media? Markdown seems quite adequate there, and dealing with any of the listed recommendations would be unbearable for many users. I’m not sure if the article was written for a very specific audience or expected to be read in a given context, or if the author overgeneralises their conclusion to all applications that a markup may have. (In the former case, it just doesn’t work as a standalone piece, in my opinion, so I don’t see much that could be said about it here.)

On a side note, the text only glosses over TeXinfo, calling it officially dead based on an e-mail from 9 years ago, while it’s had many new releases since; I’m not sure what to make of that. Would anyone have more insight into that?

> For technical documentation?

How's this?

https://whitemagicsoftware.com/softcover/technical.pdf

This article, and many of the comments here, seem to be written from the perspective of someone who would never think to read the "source code" for a document in the original text format and thinks that the transformed document is the only one they should be looking at.

And for those folks, sure, markdown sucks.

But some of us still view source code as primary and want to "use" the docs in the same context we use when "editing" the docs.

Frankly I'm enough of a curmudgeon that I view the whole conceit of markdown (that it was a concession to the "pretty formatted docs" people that was acceptable to us README dinosaurs) as a step too far. Nothing short of writing docs in proprietary WYSIWYG editors will ever be enough for those folks, and we shouldn't have tried.

Pretty much all of OPs complaints are answered by AsciiDoc. I've used it for my books, docs, etc. It's fantastic and has amazing toolchain support in IDEs, GitHub, etc. The big (good) publishers use it as their standard (O'Reilly, Manning, etc.).

My only complaint with markdown is generally whoever is rendering it chooses terrible values for line heights. I'm not sure if this is part of the spec, but it looks terrible.

Here [1] is an example. The dividers underneath headers should have less top padding, so that it's visually associated with the header and not ambiguously associated with either the body or header (or neither).

[1] https://docs.github.com/assets/cb-55935/mw-1440/images/help/...

As far as I understand, Markdown only defines an HTML output. How it should look like is another story.

While I agree with you about GitHub's dividers being too low, I think it's GitHub's problem. Not related to Markdown.

It's great for taking notes. Store it in some repo and u get a globally accessable notebook with version control

I thought so as well, until I used it. And then I realised that I'd rather go back to OneNote than use markdown. It's just too limited without introducing HTML.

Eventually settled on using ms instead of OneNote, gets me that local goodness and beautiful PDFs but also allows me to define things and make it a bit more domain-specific whenever needed. Used it for several documents at work, got compliments on how good they looked. Wild for a relatively limited system from the 70's.

> Eventually settled on using ms instead of OneNote

This name is too short to Google, and Google thinks I am referring to Microsoft, or even OneNote, when I search for it. Do you have a link to this “ms” tool from the 1970s?

It's good enough for me as I use an editor most of the time. If it's serious enough for me to write it down and revisit, it's time to use an editor.

Markdown is fast and easy and covers the basics. For a lot of use cases, those qualities make it pretty good.

I agree. I had the terrible idea to build a Markdown library in Prolog and I discovered how it's full of quirks. There's CommonMark which tries to be more precise but they have already published at least 25 versions of the spec (and still is not 1.0) and some things are just defined by an algorithm.

While I was doing that, I found Djot, a language very similar to Markdown (a bit more verbose sometimes) but much better specified (and with some additional features). So I did a Djot library in Prolog too.

Many moons ago after having long criticised shortcomings of a reasonably popular system,[1] I finally arrived at a moment of enlightenment:

It is a simple tool, accessible to many, which is useful for simple tasks.

The chief architect of the system didn't comment on the note, but did as he frequently did with various critiques of mine, indicate having seen it.

Markdown fits this description, and really should be considered on those grounds. And it's suitable for documents of often surprising complexity.

Manpages are a specific document type, which have co-evolved with a specific document processor. I've used that processor, and even, whilst at uni, wrote term papers using it. I've forgotten virtually all that knowledge: roff(1) and kin are obscure and complicated. They're also not especially human-readable, in ways that Markdown, other lightweight markup languages, HTML, LaTeX, and DocBook, say, are.

________________________________

Notes:

1. Google+, as it happens. Which had its own bastardised and painfully limited markup notation. And no, it didn't kill FB, but it was used extensively by tens of millions.

Markdown isn't a good markup language compared to LaTeX. I wouldn't typeset a paper with it. However, I wouldn't write my notes or a blog with LaTeX.

The thing that frustrates me with Markdown is that there are about as many different flavors as there are implementations. Once you get beyond bold and _italics_ it is a trip out to some help page to figure out what the special snowflake syntax is this time. How do you make a link? Embed an image? Make billeted lists? Embed pre formatted code? Who knows?

I love how your bold came out in italics. Maybe making your point for you.

https://news.ycombinator.com/formatdoc

This submission title has been editorialized, contrary to the HN guidelines.

The submitted URL appears to be the man page for a "mandoc" command.

The author's website is designed to look like the OpenBSD manual's web page. This is a blogpost about mandoc/markdown in the form of a man page...for mandoc...very clever.

http://schwarze.bsd.lv/mandoc.7

Also apparently the submission title needs (2017).

I never saw the attraction to Markdown. I especially despised the end a line with two or more invisible characters to insert a line break.

If it wasn't for Github, I probably wouldn't be using it at all. There were so many Wiki markup dialects and a Wiki Creole that could serve as a base to make a more featured popular one.

It's not my favorite feature by any means but linebreaks are almost always an issue: practically all Markdown-ish or wikitext-ish formats don't give significance to single line breaks to allow hard-wrapping the source without affecting its rendering, which doesn't leave you with many "nice" options for actually doing explicit linebreaks when you do want them.

I've seen ones where you put something like a plus at the end of the line, the spaces from Markdown, or something like MediaWiki's format where you just can't do it without falling back to writing in some explicit HTML.

> I especially despised the end a line with two or more invisible characters to insert a line break.

I love Markdown, but I also hate this. The only benefit is that is discourages people from messing with line breaks.

Oh boy! Another thread about what a POS Markdown is! As someone who wrote a similar blog post which someone then posted to HN, I'm just going to sit back with some popcorn and enjoy watching the keyboard jockeys and pedants belittle and dismiss yet another voice of reason. Markdown is a 20+ year old hack which needs to be killed with prejudice. It's continued popularity is not just bewildering, it's just plain sad.

I'll just repeat what I always say in these threads: We're in the second decade of the 21st century, and can send anyone on Earth a custom colored emoji in 8 shades of skin color, but bold, italics, bullets and headings are somehow an impossible technological hurdle. Why? Because all the geeks keep insisting that formatting text using random keyboard symbols is a great idea.

I got to the bottom and saw that the author thinks TeX is not only a viable alternative to Markdown in the spaces Markdown is heavily used, but is their favorite such "alternative".

And so anyway, despite nodding along with a few arguments above that point, I have concluded that the author and I are looking for extremely different things out of our text markup languages. I want just about as far from TeX as possible - at that point, I may as well just write README.txt's in plain text that resembles Markdown or GemText, but in a less formal manner. At least it'll look the same level of good/bad/whatever in vim as it will when dumped into an HTML file, or a PDF, or whatever. With TeX, I basically have to render the document for it to be readable.

Markdown was never meant to be perfect. It was meant to be simple. It's actually so simple that I could teach my parents how to write a Markdown document in a few minutes.

The fact that the author doesn't have to introduce what Markdown is, could give him a hint about why Markdown is not that bad. It's useable, super simple and stupid. It's so stupid that it's used.

I don't think anyone wants to write the README in their GitHub repositories in LaTeX, or worse, in mdoc. I prefer a markup document I can learn in 3 min than a "perfect" markup language barely readable by humans, requiring people to read an obscure and painful documentation for days/weeks.

> I hereby offcially declare it the shittiest markup language i have seen so far. Basically, it hasn't any strong point whatsoever, but the downsides are numerous, scary, and cover practically every relevant aspect:

Wow. No need to read this rant further.

it’s obviously half-decent enough for most folks. /shrug

I primarily use Markdown in all my note-taking and blog-writing. It’s fine for it, for me. But lots of these criticisms of Markdown resonated with me. I know it’s a rough analogy, but I’m waiting for Markdown’s “TypeScript”, so to speak: A markup language that is a superset of Markdown, but adds a lot of value by addressing some (the more the better) of the usability and predictability deficiencies pointed out in this blog post.

Markdown doesn't meet the author's needs. OK, that's fine. They shouldn't use it. But others find it useful, regardless of Markdown's limitations. Which is fine, too. The markup language you use (or don't use) doesn't determine or influence the quality of what you're writing.

Use what works for you. That could be Markdown, vanilla HTML, LaTeX, DocBook, (x)roff, whatever. No need to justify your choices.

It's not a good markup language, it really isn't. It's not good at semaphore either, or paving roads. I tried spackling a hole in my drywall with it, and it failed miserably. But when you want to write a document that is both human readable and machine interpretable, and you've only got 30 seconds to learn the syntax, nobody has ever been able to beat it. So I guess it depends on what you want.

> For example, it doesn't provide any syntax for definition lists

I mean, it does, its called HTML: The key point of it was to dip into another language if you needed to express complex things, not, add everything to the main language

Don't measure a fish by it's ability to climb a tree. The point of markdown is that it's dead simple, it lets you provide some basic structure and formatting but is still easily readable in plain text.

> in some contexts, documentation authors are required by third-party policies to provide markdown versions of their documentation

Well that's not markdown's fault.

My unicycle is not good, or even half decent at carrying groceries.

i am not surprised that the owner of this linux.com website doesnt understand markdown and promotes latex as an alternative. its a type of guy

It gets the job done in most cases it is used.

Today I learned opinions can be wrong.

Today I learned opinions can be wrong

Reply on news.ycombinator.com