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
example:
[[[
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]: http://www.michelf.com/projects/php-markdown/extra/
[Pandoc]: http://sophos.berkeley.edu/macfarlane/pandoc/README.html
[TMTOWTDI]: http://en.wikipedia.org/wiki/TMTOWTDI