About 1400 Words of Skepticism about Markdown, and an Imagined Alternative | Hacker News Reader

About 1400 Words of Skepticism about Markdown, and an Imagined Alternative

cforster.com

25 pointsrhythmvs14 comments

I'm a huge fan of Markdown because it frees up extra taps/pecks on the keyboard with the knowledge that my final document is portable and understandable in its raw unrendered plain text to non-techies.

I expect all my documents to be web friendly also. Markdown ensures that extra tweaks (more work) will not be necessary when rendering my MD file for the web.

Blockquotes inside paragraphs are harder on the eyes - best kept as block elements for web reading.

Inline quotes are sufficiant for snippets of quotes within paragraphs - for most use-cases.

Markdown keeps things simple while enforcing good web writing practises for non-HTML folks or those of us who just want to focus on content and not tags in my opinion. I guess the semantic web is less a concern for me with Markdown because I'm focused on the final deliverable, a willing trade-off of a little non-semantic for the portability and readability benefits.

The bottom line for me is producing content with the least barriers. MD always seems to fit the bill.

I was a huge fan until I read this

http://talk.commonmark.org/t/heading-not-working/819

The kind of language markdown represent shouldn't be so hard to evolve to meet changing requirements, and yet here they are spinning in circles on a fairly modern representation that sought to be the long term solution to the language fragmentation.

I guess that's the intrinsic limit of mixing semmantic and syntax.

I've found markdown failing for me for very simple things.

Someone suggested ASCIIDOC as an alternative with similar feeling of being easily editable and readable as is. This was posted on HN a while ago

https://medium.com/@chacon/living-the-future-of-technical-wr...

I get the feeling this is one of the reasons John Gruber was so annoyed by the CommonMark effort - he felt his invention, the thing he called 'Markdown', was the idea of a human-friendly pidgin syntax for a more complex markup format. His personal Markdown implementation happened to target HTML, because that's what he personally needed, but I guess he expected all kinds of markdowns for all kinds of document syntaxes, with varying similarity to the one he wrote himself.

The idea of constraining Markdown to one particular syntax targeting one particular document type must have seemed like epically missing the point... which is a common outcome when a new idea meets popular approval.

From that point of view, Markdown's nearest relative would be AsciiDoc, which is a toolkit for making simple pidgins for the DocBook XML syntax. That tool happens to come with some reasonable defaults you can use as a base, but sure enough there's now the AsciiDoctor tool, which hard-codes AsciiDoc's defaults instead of re-implementing the generic framework.

I'm pretty sure he was irritated they tried to appropriate the name.

Gruber's logic is something like: I named my thing Markdown, please don't use that name without my permission (read the third term of the license: http://daringfireball.net/projects/markdown/license ).

The logic of the (at the time) Standard Markdown people was something like: screw that, you aren't even making any of the changes we need to your project.

Did you guys try Emacs' org-mode? I feel its syntax to be similar to markdown but way more powerful.

That's on my list to try, and I've watched a number of demos (the YouTube video of the Google Talk is quite impressive).

But... I use vim ;-)

So, something like jade then? If your annoyances are semantics and the verbosity of other markups. Roll your own semantics with +mixins, and otherwise, just write HTML, without the fluff?

Human readable, concise, fluent, and HTML is a lingua franca of its own. Even in jade, I still make frequent use of the :md filter for simple text, but otherwise, structure is utterly up to you. Markdown alone doesn't quite cut it even for CMS style 'content-block-goes-here' editing.

Jade is a templating engine, not a markup language as such.

Personally, I don't understand the persistent popularity of Markdown in the face of a much better alternative like Restructured Text, where the extension story is not an alternative between "hope this flavour of Markdown does what you want" and "just write HTML". Even something simple like tables is not covered by the Markdown "spec".

yes, but the author's issues with markdown are limitations of a limited markup. markdown is appealing thanks to the lack of verbosity, hence jade - terse, simple, yet extensible. markdown is nigh one-dimensional, your content should fit in a box, and offers little ability to provide semantics. HTML / XML are overly verbose, and painful for novice / non-technical users. a subset of jade solves these eloquently for me.

First off, Chris expand your acronyms. LaTeX is sufficiently well known there's no need for that. The Text Encoding Initiative, (which doesn't seem to be an actual encoding standard?), despite being active since the 1980s, and my own use of various markup systems since about the same time, was unknown to me:

https://en.wikipedia.org/wiki/Text_Encoding_Initiative

Even knowing that, it's not clear what problem exactly TEI solves.

Second: what's your goal? How are you looking to use Markdown?

For offline use in your own document preparation activities, I think Chris answered his own question. Markdown is extensible via HTML. If you want to use semantic elements such as emphasized text or <cite>Some Famous Book</cite>, then simply include those elements within your own source document.

A lot of us are using Markdown on third-party sites -- for myself it turns up on Reddit, Ello, Diaspora, and StackExchange ... in a mazy of twisty passages, all different. And I really don't have control over what's parsed or supported (Ello's lack of blockquote and Reddit's lack of images both drive me equally nuts).

To a large extent, for works of a few dozen to 10,000 words, possibly even longer, heading structured documents work great. Markdown is just that: a quick and only slightly dirty way to create content for which presentation specification (e.g., bold and italic specs) is more than sufficient. I mean, yeah, it's fucking wonderful that HTML has, in theory, all this wonderful semantic markup. Dig into the source of pretty much any site out there, with very few exceptions, and you'll find they're simply butchered. Table layouts and directives for titles and headings and absolute positioning all over the page.... Or worse, custom styles which make even and look stunningly attractive.

If anything, documents tend to go to the other extreme: too many entities, too much markup, too much crud, too much design. To the point that I'm far too frequently scraping raw text from documents and rebuilding them (usually with Markdown) to a simple basic PDF or HTML page that I can actually fucking read.

OCD, it's a hell of a drug.

My suggestion: get over it.

You cannot get both a SIMPLE and a COMPLETE markup language. One is the enemy of the other.

Settle for good enough.

The problems I've got with Markdown (or any of the other lightweight markup languages: https://en.wikipedia.org/wiki/Lightweight_markup_language) is that standards aren't, parsers and interpreters (particularly on third-party sites) vary and/or suck, and stuff I'd really like to see (superscript, subscript, footnot, ToC generators, equation support) aren't well supported. Hell, we can't even rely on blockquotes, images, character escaping, and superscripts being uniformly treated.

Use Mardown. Or switch to another LWML. And extend it with HTML. Use post-processing scripts to add those div wrappers and metadata you want (I'm basically doing the same for my own work).

The one other element that might make sense, and which you don't address, is a document standard -- I'd really appreciate if documents had standard metadata: title, author, publication date. Something vaguely like an RFC #822 of text document metadata (and fortunately we've got *so many standards to choose from: https://en.wikipedia.org/wiki/Metadata_standards -- Ob xkcd 927).

It's also not clear how or why LaTeX itself isn't suitable here. It's plaintext, more structured than Markdown, yet generally easier to code than HTML.

I do appreciate the tip on ScholarlyMarkdown, which looks like it might address a few of my own interests.

I never really understood the point of these simplified markup languages. I see Markdown and ReST being pushed on non-technical writers who just don't want to use a text-based markup language. They want Word, or Google Docs, or a rich edit box, or something like that.

As for me, yeah I like writing in plain text but given the choice I'd rather just write in HTML which I already know, rather than use something like Markdown. I don't find Markdown to be particularly time-saving or easier to use. Or if I'm writing something where I particularly care about beautiful typesetting or I need a table of contents and an index I'll use LaTeX which has been developed for decades specifically for scholarly and technical writing.

These users want familiarity, and get false simplicity / silo-lock-in. I'm not fond of giving emacs to everyone anymore, but even the simple fact of showing that simple text can be transformed into formatted beauty can open their mind.

Otherwise, IMO, they don't understand they have a computer wanting to compute for them, they see a weird typewriter simulator that they should appease as much as possible otherwise that god might crash taking their hard (because the software is obscure) work down the drain.

Now I also find markdown good enough. Headers, paragraphs, lists, quotes, links... Gruber's page list 10 kinds, easy to remember for anyone; balanced, minimal and generic document feature set.

Markdown and other LWMLs are just that: lightweight.

I've used over the years nroff, HTML, Wordstar and Wordperfect (which aren't _quite_ markup languages, though with their "reveal codes" modes they're close), HTML, DocBook, and LaTeX. Probably a few others. Oh: Twiki, MediaWiki and some other site-specific formatting languages. Generally in vim (which I'm using here and now for what it's worth).

For much of the period from 1999 onward, basically, if I wanted to write anything vaguely structure, I went straight to HTML. It's not _too_ bad, and you can generally patch up any holes with tools like tidy (though it doesn't speak HTML5...).

LaTeX (which I only really got down a year or two back) turned out to be a lot lighter than I'd anticipated, and is pretty good, overall. I actually recommend it pretty strongly, and may well either start or more frequently finish longer-form docs using it. If you're producing publication-quality work, it's really got a ton of win to it.

The fundamental problem with HTML in my book is that it simply has too much presentation mixed up in it. It's possible to use it generically, but you've got to think about it somewhat. Markdown's not perfect, but in terms of creating a main content block you can drop into a lot of other forms, it's got strong arguments.

Despite years of HTML, and, really, a lot of familiarity with it, Markdown beats it, if only because one of the most1fundamental text units, the paragraph, requires no additional formatting.

(That's a principle strength of LaTeX as well.)

It _also_ greatly simplifies both unordered and ordered list construction. Blockquotes and code blocks are trivial. Dittoes headers.

Bold and italic text are easy, though you lose semantic distinctions as I noted above. Links are roughly equivalent.

Tables -- not great, but certainly no worse than HTML.

And so long as you're authoring offline, if you want HTML you've got it -- Markdown's effectively extensible.

As a fundamental authoring tool: really good.

Of course, if you prefer not using it, nobody's holding a gun to your head.

Reply on news.ycombinator.com