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 _______________________________________________ Markdown-Discuss mailing list Markdown-Discuss@six.pairlist.net http://six.pairlist.net/mailman/listinfo/markdown-discuss