Markdown extensions

[Richard Taytor]

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