Why Markdown and not **** (insert your favorite markup here)

Is it really possible to create a markup which will suit everyone? I don’t think so. The problem with markdown, or any of the hunders of markdown derivatives, is it’s very static: you can’t expand it without “forking” it.

Will commonmark be able to please a scientist? A novel writer? A blogger? A web developper? Won’t it miss a critical feature?

Before markdown was invented, there were other markup languages. I choose txt2tags many years ago because even if it’s not perfect, the basic syntax is very logical and easy to learn (most of the reasoning from the creole website are valid for txt2tags : http://www.wikicreole.org/wiki/Reasoning), and most of all the killer feature is you can create your own specifications, which will be written in the header of your document, so other people will read what modifications or additions were made.

If you look at:
https://raw.githubusercontent.com/farvardin/whatistxt2tags/master/whatistxt2tags.t2t

you can see lines starting with “preproc”, which will use regex to expand the original markup. This way, with only a dozen of lines, I can make a txt2tags document which can read most of the markdown syntax.

I think therefore if you choose to create a Common Markup, you should leave a way for developpers to easily customise it for their own purposes (read: regex).

Including additional processing rules directly into the document is an interesting idea. I guess something similar could be done in markdown’s YAML header blocks that many implementations use. However, documents with images and possible templates/CSS already depend on external files anyway, so it seems we can just as well write the additional rules in an external script.

In the markdown world, currently you can for example use pandoc and python or haskell scripts, and a proposal for directives has been discussed.

I use ASCIIDoc (specifically the ASCIIDocter variation) on a major file listing site I run. Its syntax makes far more consistent sense to me.

AsciiDoc and Markdown are optimized for different things. As John Gruber emphasizes in his Markdown documentation, Markdown emphasizes ease of reading in source format. Here’s an example:

AsciiDoc (from their manual):

1. List item one.
+
List item one continued with a second paragraph followed by an
Indented block.
+
.................
$ ls *.sh
$ mv *.sh ~/tmp
.................
+
List item continued with a third paragraph.

2. List item two continued with an open block.
+
--
This paragraph is part of the preceding list item.

a. This list is nested and does not require explicit item continuation.
+
This paragraph is part of the preceding list item.

b. List item b.

This paragraph belongs to item two of the outer list.
--

CommonMark equivalent:

1. List item one.

   List item one continued with a second paragraph followed by an
   Indented block.

       $ ls *.sh
       $ mv *.sh ~/tmp

   List item continued with a third paragraph.

2. List item two continued with an open block.

   This paragraph is part of the preceding list item.

   1. This list is nested and does not require explicit item continuation.

      This paragraph is part of the preceding list item.

   2. List item b.

   This paragraph belongs to item two of the outer list.

Note that the AsciiDoc is at least as easy to write, perhaps easier, because you don’t need to worry about indentation. But the CommonMark source is more readable; the indentation makes clear the structure of the list in a way that mirrors how it would be displayed in a browser or on the page.

4 Likes

Nope. Markdown isn’t designed to suit everyone. It’s designed to streamline content editing for the most commonly used HTML tags. It’s not a panacea and it never claimed to be.

Again, markdown isn’t meant to be a one-size-fits-all solution. It seems like you’re caught up by the Law of the instrument. Markdown is just a tool. Use it only when appropriate.

I think the name has made you confused as to the purpose of CommonMark. This isn’t to create a “Common Markup”. It’s to formalize markdown as a syntax.

The syntax of markdown is what’s getting standardized, and that is all. It’s up to implementors to make their implementations extensible. While we have already started discussions about extensions to the markdown syntax, I haven’t yet seen any steps to formalize syntax for the proposed extensions.

If you would like an implementation to make it easy for developers to extend markdown, and you aren’t finding any existing implementations that suit your needs, I recommend that you take it upon yourself to build your own implementation and share it with the community.

https://github.com/markdown-it/markdown-it i know couple of guys, who already did it :slight_smile:

3 Likes