Progress

We've only just started, these rules are likely going to change (and are completely incomplete right now), and the implementation's built for correctness rather than elegance or speed.

Other than that - things are going great!

---

Top Level Concepts

• Processing should be conducted on a line-by-line basis
• The contents of a line cannot affect the output of any preceding line

General Rules

• Leading and trailing whitespace will be ignored (with the exception of code blocks)
• Multiple blank lines will count as one blank line (with the exception of code blocks)
• HTML entity replacement will be conducted on appropriate characters not interpreted as specs

Finally - the most important rule of them all...

• There is nah line-break

---

ID, CSS & Data specifications

• Any block/in/line spec can be suffixed with a CSS class spec @classSpec
• Multiple CSS classes may be specified at once, separated by the '&' character @classSpecOne&classSpecTwo
• When specified with a double @ as it's opening spec, any CSS classes are split by dashes and any left part taken as base CSS class, all distinct classes are added @@btn-large becomes class='btn btn-large' and @@btn-large.btn-danger becomes class='btn btn-large btn-danger'
• Any block/in/line spec can be suffixed with an Id spec ?idSpec
• Any block/in/line spec can specify both a CSS and an Id spec in any order @classSpec?idSpec and ?idSpec@classSpec
• When output - the Id spec comes before the CSS spec, which comes before the data spec id='idSpec' class='classSpec' data-spec='dataSpec'
• Any block/in/line spec can be suffixed with a Data spec $key=value
• Multiple data specs may be specified at once, separated by the '&' character $keyOne=valueOne&keyTwo=valueTwo
• All data keys will be formatted to the HTML data attribute standard from capitalisation, thisFirstKey becomes this-first-key
• Dashes will replace non-alphanumeric characters in data keys, so my.first.key and my_first_key both become my-first-key
• Multiple dashes will be replaced down to a single dash my---first becomes my-first
• By default any Id / CSS / Data spec is valid
• However whitelists may provide exclusive lists of Id and CSS specs. Any invalid spec is ignored and not output.
• Id specs can only be used once. A subsequent use of the same Id will be invalid and ignored.
• An Id / CSS spec is closed explicitly by a repeat of it's initial character ?idSpec? or @classOne&classTwo@
• An Id / CSS spec is closed implicitly by a space ?idSpec Some content or @classOne.classTwo Some content

---

Line Specifications

• Line specs format the whole line following them - excluding any block spec closures
• Line specs may occur immediately following a block spec open
• Line specs must appear at the start of a line (excepting the above)

# - Headings Done

• The hash character (#) specifies the line will be formatted as a heading.
• A single # will become a H1, ## becomes a H2, ### becomes a H3 and so on.
• The level of the heading may be specified after a single # as a number #100 equates to H100
• There is no limit to the depth of heading that may be specified

/ - Comment

• The remainder of the line is treated as comment and not processed further by line-down
• Except if the outputComments option is enabled in which case the remainder of the line will be rendered wrapped in HTML comments

---

Inline Specifications

• Inline specs format a section of a line.
• Inline specs do not flow between lines - they finish when the line does
• When handling inline specifications, whitespace is preserved. So ** I'm strong ** is <strong> I'm strong </strong>
• As a consequence implicitly closed id/class specs will leave a whitespace in their output, considering explicitly closing them if this is not desired, i.e. **?lead?A strong lead** to produce <strong id='lead'>A strong lead</strong> or **?lead?@classy@A strong lead** to produce <strong id='lead' class='classy'>A strong lead</strong>

Name	Spec	Outputs	Rendered As	Comments
Bold / strong	Something **important**	Something <strong>important</strong>	Something important	Done
Italics / emphasis	Something //oblique//	Something <em>oblique</em>	Something oblique	Done
Underline	Something __reinforced__	Something <u>reinforced</u>	Something reinforced	Done
Superscript	Something ^^raised up^^	Something <sup>raised up</sup>	Something raised up	Done
Subscript	Something !!pulled down!!	Something <sub>pulled down</sub>	Something pulled down	Done
Small	Something >>small>>	Something <small>small</small>	Something small	Done
Strike through	Something ~~that was relevant~~	Something <strike>that was relevant</strike>	Something that was relevant	Done
Code	Something ::Codified::	Something <code>Codified</code>	Something Codified	Done
Span	Something ``Spanned``	Something <span>Spanned</span>	Something Spanned	Done
Hyperlinks
Images

---

Block Specifications

• Block specs are always the first non-whitespace characters
• Block specs can be on their own line - and their corresponding opening element will be output on its own line
• Block specs can be on a line before other content - and their corresponding opening element will be output at the start of the line
• Block specs may be nested
• Nested block spec open/closes must be on separate lines
• Block specs may be explicitly closed
• Explicit block spec closes must be the last non whitespace characters on a line
• A block spec that appears at both the start and end of a line when there is any open block will be treated as a close
• Explicit block closes may be out of sequence - you can explicitly open a block quote and a paragraph and then only explicitly close the block quote (the paragraph will be implicitly closed).
• All currently open block specs are implicitly closed by an empty line (a line with no non-whitespace characters)
• An implicit paragraph is opened by a line that contains no line or block spec, and is not currently in a block spec (excluding blockquote)
• An implicitly opened paragraph will be closed by the explicit opening of any block spec

& - Unordered list items

• The depth of the item may be specified after a single & as a number &10 nests a list item ten levels deep
• The depth of the item may be specified by the number of &'s so &&& nests a list item 3 levels deep
• If an unordered list item line spec occurs outside of an ordered list - a new implicit unordered list is started
• List items cannot be explicitly closed, they are implicitly closed by the next item or by the closing of their list

+ - Ordered list items

• The depth of the item may be specified after a single + as a number +10 nests a list item ten levels deep
• The depth of the item may be specified by the number of +'s so +++ nests a list item 3 levels deep
• If an ordered list item line spec occurs outside of an ordered list - a new implicit ordered list is started
• List items cannot be explicitly closed, they are implicitly closed by the next item or by the closing of their list

Two double quotes - "" - Block Quotes Done

• Outputs as the blockquote element
• Allows implicit paragraphs to be created within it
• Implicit block spec closure stops at a block quote

Two apostrophes - '' - Paragraph Done

• Output as the p element
• Use over the implicit paragraph block allows Id and CSS specs to be added

Three dashes - --- Horizontal Rule Done

• Self closing block
• Must start and end the line

Percent then a ampersand - %& Unordered list

Percent then a plus sign - %+ Ordered list

• Allows trailing number to specify start number - %+50 outputs as <ol start='50'>
• Any start attribute is output after any id/css/data specs - <ol id='lead' class='trash' data-spec='basicRules' start='50'>

Two dollar signs - $$ Preformatted Code

Four dollar signs - $$$$ Data Block

• Specifies that the enclosed area will have data captured from data specs and output as a HTML 5 data block.
• CSS class specifies format : json, xml
• Output separately at the end
• Cannot be nested, must occur at the root of the document
• Multiple data blocks may occur in a single document
• If no id spec is provided - one is generated from the scheme : data-block-{index} where {index} is an auto-increment number scoped to the document starting at 1.
• If not already set, the option generateIds is set true for the scope of the block

Two vertical pipes - || Line Down free zone

Options Planned

idWhitelist

Explicit list of allowed ids, either just a list or a hashmap of tags to ids

cssWhitelist

Explicit list of allowed CSS classes, either just a list or a hashmap of tags to classes

idBlacklist

Explicit list of DISallowed ids

cssBlacklist

Explicit list of DISallowed CSS classes

deprecatedTags

Mapping of elements to replacement element and CSS class

generateIds

Whether or not to automatically generate IDs for significant elements if no explicit ID is given - can be either a boolean or a list of elements to generate for - currently only boolean supported - generate for h, p & li

autodetectHyperlinks

Whether to auto-detect http:// and other prefixes as links

implicitDataBlockCapture

Whether to include an implicit data block around the entire document (any existing explicit data blocks are preserved and rendered separately)

implicitBaseCssClasses

A list of CSS base classes to add to normal CSS specs when matching the first part of any hyphenated class, i.e. 'btn','label' means that @btn-large&label-danger&ignored-bored becomes class="btn label btn-large label-danger ignored-bored"

additionalInlineSpecs

A list of custom inline spec formats - TBD if this is a good idea or not

linkFormatters

A hashmap of link prefixes to custom formatters

outputComments

Whether to render comments into the HTML output