Documentation

README.md

@@ -0,0 +1,4 @@
+# Markdown Library
+
+* [Markdown syntax reference](markdown.md)
+* [Creating custom syntax](custom.md)

custom.md

@@ -0,0 +1,25 @@
+# Custom Syntax Modules
+
+Syntax falls into two categories: block syntax and inline syntax. Block syntax operates on one or more whole lines of content to form structures like paragraphs, lists, tables, etc. Inline syntax operates on stretches of text within a block, such as marking a word as bold or inserting a link.
+
+## Block Reader
+
+Block readers extend from `MDBlockReader`.
+
+They have a priority value that determines when the reader is tried relative to other readers. Built-in readers range from 0 to 100 but any priority value is valid. Lower values are evaluated before larger values. Generally readers for more complex syntaxes should precede simpler ones. E.g. Headers have a lower priority value because they are easy to match by their leading `#` characters. Paragraphs have a priority of 100 because they are the fallback when no other format matches.
+
+Block readers have a `readBlock` method that must be overriden. The method is passed an `MDState` object repeatedly, allowing the reader to check if a matching block is found at the current line pointer. An array of lines of markdown text are in `MDState.lines`, and the current line pointer is in `MDState.p`. If the reader does not detect a matching block starting at that line, the method should return `null` (preferably as soon as possible for good performance). If the line pointer does point to the beginning of a matching block, the `p` pointer should be positioned to the next line following the end of that block and an `MDBlock` subclass instance should be returned.
+
+A reader can also perform post-processing after the document has been parsed. This can be done by overriding the `postProcess` method. It will be passed an array of top-level document blocks. This array can be modified with `.splice` operations to add, remove, or replace top-level blocks. Blocks can also be recursed into by calling `MDBlock.visitChildren` with a function. The function will be called with every `MDBlock` or `MDSpan` by recursing into all child nodes. This gives the ability to manipulate specific nodes easily without walking the node tree manually.
+
+## Inline Reader
+
+Inline readers work differently. They extend from `MDInlineReader`. Inline parsing is done non-linearly by progressively swapping out elements of a `MDToken` array with `MDSpan` elements as patterns of tokens are found that match inline syntax structures.
+
+Inline parsing is done in two phases: tokenization and substitution. These two phases have separate priorities specified by each reader. For the substitution phase, readers can even specify more than one priority with an array so that it can be called multiple times during that phase. As with block readers, lower priority values will be evaluated before higher values. This should be used to match more complex tokens and more complex token patterns before simpler patterns that might lead to ambiguities with syntaxes that use the same characters.
+
+In the tokenize phase, each inline reader is given a chance to look for a relevant token at the beginning of a line. This is done by the `readFirstToken` method. It is passed a substring of a line of markdown, and the method should see if the string begins with a recognized token. Only tokens at the beginning of the string should be looked for. If no token is found the method should return `null`. If a token is found an `MDToken` should be returned.
+
+After a block of markdown content has been tokenized, the substitution phase begins. This phase repeatedly processes an array of `MDToken`s, allowing readers to swap out one or more tokens with `MDSpan` subclasses in place. E.g. an emphasis reader will look for an asterisk token, some number of intermediary tokens, and another closing asterisk token. It will swap all of those out with an `MDEmphasisSpan`. Once the substitution phase is complete, any remaining `MDToken`s in the array get converted to `MDTextSpan`.
+
+For inline readers with inner content (such as the previous emphasis example), the inner tokens can be converted to `MDSpan`s by calling `state.tokensToSpans()`. Alternately, if an inner markdown string needs to be converted to `MDSpan`s, call `state.inlineMarkdownToSpan` or `.inlineMarkdownToSpans` (plural).

markdown.md

@@ -0,0 +1,304 @@
+# Markdown Syntax
+
+(todo: include class names for enabling these features)
+
+## Block Formats
+
+Formats that apply to one or more lines.
+
+### Paragraph
+
+Any contiguous set of lines not formatted like one of the other formats below is treated as a paragraph. Paragraphs are separated by double blank lines.
+
+```markdown
+Lorem ipsum dolor
+sit amet.
+
+New paragraph begins.
+```
+
+### Headers
+
+Headers are marked with one or more leading hashes.
+
+```markdown
+# Header 1 has one hash
+
+## Header 2 has two hashes
+
+###### Up to header 6
+
+## Optional Matched Hashes At The End ##
+```
+
+Alternately, H1 and H2 can be marked with underlines.
+
+```markdown
+Header 1 underlined with equals
+===============================
+
+Header 2 with hyphens. Number of underline chars doesn't matter
+---
+```
+
+### Lists
+
+Unordered lists are bulleted with an asterisk, plus, or hyphen and space.
+
+```markdown
+* Item
++ Any of these
+- Work as bullets
+```
+
+Lists can be nested with one or more spaces below an item.
+
+```markdown
+* Item
+    * Sublist
+	* Sublist
+* Item
+```
+
+Ordered lists start with a number, period, and space.
+
+```markdown
+1. Item
+2. Item
+3. Item
+```
+
+Again, they can be nested.
+
+```markdown
+1. Item
+    1. Subitem
+	2. Subitem
+2. Item
+```
+
+The first number dictates where the numbering begins. The numbers on the other items are ignored and incremented by one.
+
+```markdown
+5. Rendered as a 5
+1. Rendered as a 6
+1. Rendered as a 7
+```
+
+### Blockquote
+
+Blockquotes enclose lengthy quoted content in an indented block.
+
+```markdown
+Lorem Ipsum said:
+
+> Dolor sit amet
+> adipiscing.
+```
+
+### Code Blocks
+
+Blocks of preformatted code can be enclosed in triple backticks.
+
+```markdown
+`​``
+function foo() {
+	return 'bar';
+}
+`​``
+```
+
+Alternately, lines indented by at least four spaces or a tab character will be interpreted as code blocks.
+
+```markdown
+    function foo() {
+		return 'bar';
+	}
+```
+
+### Horizontal Rule
+
+Horizontal divider lines are written as 3 or more hyphens or asterisks on a line by themselves, with or without interstitial whitespace.
+
+```markdown
+---
+
+***
+
+- - - -
+
+* * * * * * *
+```
+
+### Tables
+
+Tables consist of one header row and any number of body rows
+
+```markdown
+Header   | Row | Here
+---------|-----|-----
+Cell     | 123 |  xyz
+Next row | 543 |  abc
+```
+
+The pipe characters do not have to line up.
+
+Rows can optionally have leading and/or trailing pipes. This is required for a single column table.
+
+```markdown
+| One column |
+| --- |
+| 123 |
+| 234 |
+```
+
+Columns can be right, center, or left aligned with colons in the divider line.
+
+```markdown
+| Left | Center | Right |
+| :--- | :----: | ----: |
+| 1 | 2 | 3 |
+```
+
+### Definition List
+
+Definition lists show terms with definitions below them. Useful for glossaries.
+
+```markdown
+term
+: definition of term
+another
+: definition of another
+: alternate definition of another
+```
+
+### Abbreviation Definition
+
+Abbreviations can be defined anywhere in the document. Anywhere that abbreviation appears in the document will have a mouseover title showing the expanded definition. The definition is plaintext only (no markdown).
+
+```markdown
+*[ABC]: Always Be Closing
+```
+
+### CSS Modifiers
+
+Many block structures can be modified with CSS classes, IDs, or other simple HTML attributes inside curly braces.
+
+```markdown
+# Header {.mycssclass}
+
+--- {#mydividerid}
+
+| Table | {style=color:green;}
+|---|
+|123|
+
+# Multiple Modifiers {.linkclass #linkid lang=en}
+```
+
+## Inline Formats
+
+Formats that apply within a block to style runs of words or inject other content within text.
+
+### Strong
+
+Text can be marked as bold by enclosing it in double asterisks.
+
+```markdown
+Some **bold** text. Can also use __underscores__.
+```
+
+### Emphasis
+
+Text can be marked as italic by enclosing it in single underscores or single asterisks.
+
+```markdown
+Some _italic_ text. Can also use *asterisks*.
+```
+
+### Strikethrough
+
+Text can be stricken out using tildes, singly or in pairs.
+
+```markdown
+Not ~~this text~~. Not ~this text~ either.
+```
+
+### Code
+
+Words can be rendered in monospace font using single backticks.
+
+```markdown
+The name of the function is `foo()`.
+```
+
+### Link
+
+Linking to a document is done with marked text and a URL.
+
+```markdown
+Click [here](page.html).
+```
+
+An optional mouseover title can be added to the link after the URL.
+
+```markdown
+Click [here](page.html "Goes to a neat page").
+```
+
+Repetitive or lengthy URLs can be referenced out and defined elsewhere in the document.
+
+```markdown
+Click [here][foo] or [here][foo] or [even here][foo] to go to the same place.
+
+[foo]: page.html "Optional title"
+```
+
+Lastly, to make a link with the URL as the link text, you can use angle brackets.
+
+```markdown
+Go visit <page.html>.
+```
+
+### Image
+
+An image is similar to link syntax with an exclamation in front. Instead of clickable link text, the text is alt text for the image.
+
+```markdown
+![a test image](https://picsum.photos/100/75)
+```
+
+Images also support title attributes.
+
+```markdown
+![a test image](https://picsum.photos/100/75 "title text")
+```
+
+Images also support referenced URLs.
+
+```markdown
+![alt text][foo]
+
+[foo]: https://picsum.photos/100/75
+```
+
+Images can be made clickable by enclosing them in a link where the link text goes.
+
+```markdown
+[![alt text](image.jpg)](page.html)
+```
+
+### Footnote
+
+Footnotes can be inserted into text. The text of the footnotes is added to the bottom of the document, regardless of where they're defined.
+
+```markdown
+Lorem ipsum[^1] dolor sit[^2] amet.
+
+[^1]: Further information here
+[^2]: See _Interesting Book_, pg 213
+```
+
+### HTML Tags
+
+Currently all HTML tags and attributes are permitted, when markdown syntax doesn't do what you want.