Markdown extensions

Richard Taytor dick at
Wed Jul 4 19:41:06 EDT 2007

In addition to the Markdown extensions/modifications of [Markdown Extra][] and [Pandoc][], I find these following to be of essential utility and I post them here for the interest of others wishing to extend Markdown, and to cultivate coherent common syntax. I invite comment/criticism regarding the nature of these extensions in form and function; however, I wish to avoid debate of the question of their fundamental utility/necessity.

1. element attributes
2. div & span
3. alternative headings

### element attributes (the attribute list)

example: `{#id .class name="value"}`

- the attribute list may contain (in any order):
- zero or one: #id
- one or more: .class, name="value" (name/value pairs may be written without quotes if the value contains no whitespace)
- for all elements, the attribute list:
- may appear either before or after the element contents
- *must* appear within element delimiters[^1]
- *special case*, for links and images:
- may appear inside the parentheses (with the other attributes: href and title), or in the definition for reference-style links
- for block elements, the attribute list:
- may appear on its own line, adjacent to the block (separated by a single newline)

### div


Div contents here...

- three or more [ and ] indicate open and close div tags (respectively)
- whitespace between div contents and markers may be omitted

### span

example: `spans are {use}ful`

- a primary advantage of span syntax is to attach an attribute list (though it can be useful without one as well)
- it may seem odd to use braces (too similar to the attribute list) but nesting is disambiguated (when the open and close markers are different)

### alternative headings (two kinds)

example: `###2 heading text`

- this syntax is identical to that of "unclosed" atx, except:
- one or more # may be used (to augment or diminish visual emphasis as desired, in the source text) with no effect on rendered output
- the # string *must* be followed by the heading level (1-6), and one or more space/tab

example: `#.1.3.12 heading text`

- same as above except
- the # string *must* be followed by a period, one or more integers separated by periods, and one or more space/tab
- the count of periods corresponds to the heading level
- the numeric string (integers separated by periods) is included in the heading (without the leading period)

[^1]: Of course, if the location of the attribute list is restricted (only before, or only after), then it may appear outside the element delimiters. For some reason, this seems to be a point of contention. I believe that a syntax extension of *natural* language should minimise restriction of the author (in the case of natural language, [TMTOWTDI][]).

Some reasons to keep the attribute list inside element delimiters:

- permits inclusion of whitespace around the attribute list (to make the source text more readable)
- increases consistency

for links/images, this locates the attribute list with the other element attributes (href and title)

like this: `[text](href "title" {attr})`
not this: `[text](href "title"){attr}`

- reduces ambiguity

`### [heading](href) {attr}`

is very similar but potentially quite different (the difference should be more obvious in the syntax) to

`### [heading](href){attr}`

- easy to parse

Some reasons to let the attribute list appear before *or* after element contents:

- to augment or diminish visual emphasis as desired, in the source text
- to make the source text more readable
- example: for adjacent inline elements, the attribute lists may be arranged to make the source text more readable

like this: `Inevitably, *{attr}Mark**down{attr}* will evolve, and/or fork.`
not this: `Inevitably, *Mark*{attr}*down*{attr} will evolve, and/or fork.`
- I see no compelling reason not to do this

[Markdown Extra]:

More information about the Markdown-Discuss mailing list