Documentation updates

custom.md

@@ -1,25 +1,152 @@
 # 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.
+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. Inline syntax cannot span multiple blocks.
 
-## Block Reader
+## Readers
 
-Block readers extend from `MDBlockReader`.
+A reader is a subclass of `MDReader` and handles the parsing of one kind of
+syntax. E.g. `MDUnorderedListReader` handles bulleted lists and their items,
+`MDStrongReader` handles bold text, etc.
 
-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.
+A reader can parse block syntax, inline syntax, or both.
 
-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.
+## Parsing process
 
-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.
+Parsing occurs in three phases.
 
-## Inline Reader
+1. **Blocks:** Readers are consulted line-by-line to see if their supported
+block syntax is found starting at the given line pointer. If so, it returns an
+`MDNode` object encoding the block, otherwise it returns `null` and the next
+reader is checked. See `MDReader.readBlock()`.
 
-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.
+2. **Tokenizing:** Readers are asked to see if a supported token is located at
+the beginning of a given string. If so, an `MDToken` is returned, otherwise
+it returns `null` and then next reader is checked. See `MDReader.readToken()`.
 
-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.
+3. **Substitution:** Readers are given a mixed array of `MDToken`s (from the
+previous step) and `MDNode`s. The goal of substitution is to eventually convert
+all tokens into nodes, with any left over at the end being converted to
+`MDTextNode`s. If a reader can make one substitution it returns `true`, otherwise
+`false` and the next reader is checked. See `MDReader.substituteTokens()`.
 
-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.
+## Parsing Blocks
 
-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`.
+To parse a block format, override the `readBlock` method in a subclass of
+`MDReader`. It will be passed an `MDState` instance. The two state properties of
+importance here are `lines` and `p`. `lines` is an array of the lines of markdown,
+and `p` is the current line pointer index. The job of `readBlock` is to check
+if the block syntax of interest is located at line `p`. Most of the time it won't
+be, in which case the method should just return `null`, preferably as early as
+possible for good performance.
 
-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).
+If the format is detected at line `p` then the reader should look ahead and see
+how many subsequent lines are also part of the block, process them as necessary,
+and return an appropriate `MDNode` subclass with their contents. Before returning,
+the reader _must_ set the state's `p` to the line index just after the last line
+of the detected block.
+
+Most blocks will have inner content. This can be processed into one or more
+`MDNode`s by calling `state.inlineMarkdownToNode` or `state.inlineMarkdownToNodes`
+for inline content. If the content may have nested block structures, create a
+subarray from `state.lines` and create a sub-state with `state.copy(lines)`.
+This creates a child state for the sub-document within the block structure. You
+can then call `substate.readBlocks()` to get an array of `MDBlockNode` to use
+as content. Note: if your block syntax has some kind of indentation or marker
+at the beginning of every line, those should be stripped from the lines passed
+to the copied sub-state.
+
+> **A note about sub-states.** States can have parent states. You can store any
+> needed state info on an `MDState` instance, but you will usually want to do
+> so on `state.root`, not `state` itself. This ensures those properties are
+> accessed on the original state, not a disposable substate.
+
+## Parsing Inline Syntax
+
+Inline parsing is usually done by overriding both the `readToken` and
+`substituteTokens` methods.
+
+The `readToken` method is passed an `MDState` and a tail portion of a line of
+markdown. The method should check if the line begins with a supported token.
+This will generally be some punctuation symbol or sometimes a more complex
+sequence. For inline syntax consisting of pairs of double symbols (e.g. `**strong**`), each symbol should usually be tokenized individually rather than
+as pairs, just in case another syntax recognizes single symbols. If no token
+is found at the start of the string, return `null`. Do _not_ match tokens
+anywhere but at the start of the given string.
+
+Substitution is done by the `substituteTokens` method. This one is trickier.
+It is called with a mixed array of tokens (`MDToken`) and nodes (`MDNode`).
+The goal is for readers to keep doing one search-and-replace when possible.
+Only the first match should be performed, then return `true` if a substitution
+was made or `false` if not.
+
+There are helper methods for performing substitution. `MDToken` has static methods
+`findFirstTokens` and `findPairedTokens`. They work like crude regexes that
+operate on tokens instead of characters. For syntax consisting of text enclosed
+between symbols (e.g. `**strong**`, `_emphasis_`, `~~strike~~`), you can
+subclass `MDSimplePairInlineReader` and use its `attemptPair` method to make
+substitution easy.
+
+## Priority
+
+Many markdown syntaxes use the same characters and similar syntax. This can
+cause problems depending on which reader is run first. This can be resolved by
+prioritization. Each parsing phase has its own priority order, and each reader
+can dictate what readers it wants to be ahead of or behind by overriding the
+`compareBlockOrdering`, `compareTokenizeOrdering`, or `compareSubstituteOrdering`
+methods. Each is called with another reader instance, and the method should
+return a `-1` if it wants to be run before the given reader, `1` if it wants to
+be run after the given reader, or `0` as a "don't care" value. The method should
+only return `-1` or `1` when it's necessary to resolve a specific conflict;
+most of the time it should return `0`. The default implementation always returns
+`0`.
+
+Prioritization can be further refined for the substitution phase using multiple
+passes. Passes are good for especially ambiguous constructs, like `***strong** emphasis*`. In this example, a naive `MDEmphasisReader` might grab the first asterisk as the start of the sequence and the one immediately following "strong",
+stealing the second and third asterisk as part of the inner text and leaving the
+second asterisk after "strong" and the one after "emphasis" alone.
+
+> `[*]**strong[*]* emphasis*`<br>
+> An incorrect, naive substitution (start and end tokens shown in brackets)
+
+By using mulitiple passes, the reader can use early passes to be more
+conservative and hold out for a better match first, or let other readers find
+a better match, then on a later pass it can grab whatever's left over.
+
+> 1. `MDStrongReader` finds a match on the first pass because there are no inner
+> asterisks to cause ambiguities<br>
+> `*[**]strong[**] emphasis*`
+>
+> 2. Then, `MDEmphasisReader` finds the outer pair on a later pass<br>
+> `*<MDStrongNode> emphasis*`
+
+## Pre- and Post-Processing
+
+Readers have the option of performing tasks before and after the document has
+been parsed by overriding the `preProcess` and/or `postProcess` methods.
+
+Pre-processing is mostly useful for initializing `MDState` in some way.
+
+Post-processing can be used to manipulate the `MDNode` tree after it has been
+constructed by the parsing phases. For example, finding all the footnotes in a
+document in the order they appear for proper numbering. `postProcess` is passed
+an array of top-level `MDNode`s in the parsed document. This array can be
+altered using `.splice` operations if desired to add additional structures,
+such as a list of all the footnote content at the bottom of the document, to
+reuse the same example.
+
+One useful utility for post-processing is `MDNode.visitChildren`. This will
+recursively visit every node in the tree and call a callback function with each
+one. The node tree cannot be restructured, but each node can be inspected or
+altered.
+
+To perform substitution, `MDUtils.replaceNodes` can be called. It will call a
+replacer function with every node in the tree recursively. If the function
+returns `null`, no change is made. If the function returns a new `MDNode`
+instance it will replace that node in the tree. When a replacement is made,
+neither the original nor the replacement is recursed into. To replace a node
+with multiple other nodes, wrap those multiple nodes in a generic `MDNode` as
+its children. To remove a node without a replacement, return an `MDNode` with
+no children. It will be rendered as nothing when converted to HTML.

js/markdown.js

@@ -1135,16 +1135,16 @@ class MDReader {
 }
 
 /**
- * Reads markdown blocks for headers denoted with the underline syntax.
+ * Reads markdown blocks for headings denoted with the underline syntax.
  * 
  * Example:
  * 
  * > ```markdown
- * > Header 1
+ * > Heading 1
  * > ========
  * > ```
  */
-class MDUnderlinedHeaderReader extends MDReader {
+class MDUnderlinedHeadingReader extends MDReader {
 	readBlock(state) {
 		var p = state.p;
 		if (!state.hasLines(2)) return null;
@@ -1155,13 +1155,13 @@ class MDUnderlinedHeaderReader extends MDReader {
 		if (contentLine == '') return null;
 		if (/^=+$/.exec(underLine)) {
 			state.p = p;
-			let block = new MDHeaderNode(1, state.inlineMarkdownToNodes(contentLine));
+			let block = new MDHeadingNode(1, state.inlineMarkdownToNodes(contentLine));
 			if (modifier) modifier.applyTo(block);
 			return block;
 		}
 		if (/^\-+$/.exec(underLine)) {
 			state.p = p;
-			let block = new MDHeaderNode(2, state.inlineMarkdownToNodes(contentLine));
+			let block = new MDHeadingNode(2, state.inlineMarkdownToNodes(contentLine));
 			if (modifier) modifier.applyTo(block);
 			return block;
 		}
@@ -1170,35 +1170,35 @@ class MDUnderlinedHeaderReader extends MDReader {
 }
 
 /**
- * Reads markdown blocks for headers denoted with hash marks. Header levels 1 to
+ * Reads markdown blocks for headings denoted with hash marks. Heading levels 1 to
  * 6 are supported.
  * 
  * Examples:
  * 
  * > ```markdown
- * > # Header 1
+ * > # Heading 1
  * >
- * > ## Header 2
+ * > ## Heading 2
  * >
  * > # Enclosing Hashes Are Optional #
  * >
  * > ## Trailing Hashes Don't Have to Match in Number ####
  * > ```
  */
-class MDHashHeaderReader extends MDReader {
-	static #hashHeaderRegex = /^(#{1,6})\s*([^#].*?)\s*\#*\s*$/;  // 1=hashes, 2=content
+class MDHashHeadingReader extends MDReader {
+	static #hashHeadingRegex = /^(#{1,6})\s*([^#].*?)\s*\#*\s*$/;  // 1=hashes, 2=content
 
 	readBlock(state) {
 		var p = state.p;
 		let line = state.lines[p++];
 		var modifier;
 		[line, modifier] = MDTagModifier.fromLine(line);
-		var groups = MDHashHeaderReader.#hashHeaderRegex.exec(line);
+		var groups = MDHashHeadingReader.#hashHeadingRegex.exec(line);
 		if (groups === null) return null;
 		state.p = p;
 		const level = groups[1].length;
 		const content = groups[2];
-		let block = new MDHeaderNode(level, state.inlineMarkdownToNodes(content));
+		let block = new MDHeadingNode(level, state.inlineMarkdownToNodes(content));
 		if (modifier) modifier.applyTo(block);
 		return block;
 	}
@@ -2492,14 +2492,14 @@ class MDParagraphNode extends MDBlockNode {
 	}
 }
 
-class MDHeaderNode extends MDBlockNode {
+class MDHeadingNode extends MDBlockNode {
 	/** @type {number} */
 	level;
 
 	constructor(level, children) {
 		super(children);
 		if (typeof level !== 'number' || (level < 1 || level > 6)) {
-			throw new Error(`${this.constructor.name} requires header level 1 to 6`);
+			throw new Error(`${this.constructor.name} requires heading level 1 to 6`);
 		}
 		this.level = level;
 	}
@@ -3379,8 +3379,8 @@ class Markdown {
 	 * @type {MDReader[]}
 	 */
 	static standardReaders = [
-		new MDUnderlinedHeaderReader(),
-		new MDHashHeaderReader(),
+		new MDUnderlinedHeadingReader(),
+		new MDHashHeadingReader(),
 		new MDBlockQuoteReader(),
 		new MDHorizontalRuleReader(),
 		new MDUnorderedListReader(),

markdown.md

@@ -1,14 +1,13 @@
 # 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.
+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
@@ -17,6 +16,13 @@ sit amet.
 New paragraph begins.
 ```
 
+> <p>Lorem ipsum dolor sit amet.</p>
+>
+> <p>New paragraph begins.</p>
+
+Class:
+* `MDParagraphReader`
+
 ### Headers
 
 Headers are marked with one or more leading hashes.
@@ -31,6 +37,14 @@ Headers are marked with one or more leading hashes.
 ## Optional Matched Hashes At The End ##
 ```
 
+> <h1>Header 1 has one hash</h1>
+>
+> <h2>Header 2 has two hashes</h2>
+>
+> <h6>Up to header 6</h6>
+>
+> <h2>Optional Matched Hashes At The End</h2>
+
 Alternately, H1 and H2 can be marked with underlines.
 
 ```markdown
@@ -41,6 +55,14 @@ Header 2 with hyphens. Number of underline chars doesn't matter
 ---
 ```
 
+> <h1>Header 1 underlined with equals</h1>
+>
+> <h2>Header 2 with hyphens. Number of underline chars doesn't matter</h2>
+
+Classes:
+* `MDUnderlinedHeadingReader`
+* `MDHashHeadingReader`
+
 ### Lists
 
 Unordered lists are bulleted with an asterisk, plus, or hyphen and space.
@@ -51,6 +73,12 @@ Unordered lists are bulleted with an asterisk, plus, or hyphen and space.
 - Work as bullets
 ```
 
+> <ul>
+> <li>Item</li>
+> <li>Any of these</li>
+> <li>Work as bullets</li>
+> </ul>
+
 Lists can be nested with one or more spaces below an item.
 
 ```markdown
@@ -60,6 +88,14 @@ Lists can be nested with one or more spaces below an item.
 * Item
 ```
 
+> <ul>
+> <li>Item<ul>
+> <li>Sublist</li>
+> <li>Sublist</li>
+> </ul></li>
+> <li>Item</li>
+> </ul>
+
 Ordered lists start with a number, period, and space.
 
 ```markdown
@@ -68,6 +104,12 @@ Ordered lists start with a number, period, and space.
 3. Item
 ```
 
+> <ol>
+> <li>Item</li>
+> <li>Item</li>
+> <li>Item</li>
+> </ol>
+
 Again, they can be nested.
 
 ```markdown
@@ -77,7 +119,16 @@ Again, they can be nested.
 2. Item
 ```
 
-The first number dictates where the numbering begins. The numbers on the other items are ignored and incremented by one.
+> <ol>
+> <li>Item<ol>
+> <li>Subitem</li>
+> <li>Subitem</li>
+> </ol></li>
+> <li>Item</li>
+> </ol>
+
+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
@@ -85,6 +136,19 @@ The first number dictates where the numbering begins. The numbers on the other i
 1. Rendered as a 7
 ```
 
+> <ol start="5">
+> <li>Rendered as a 5</li>
+> <li>Rendered as a 6</li>
+> <li>Rendered as a 7</li>
+> </ol>
+
+Numbering every item with `1.` can
+save you the hassle of renumbering items when reordering them.
+
+Classes:
+* `MDUnorderedListReader`
+* `MDOrderedListReader`
+
 ### Blockquote
 
 Blockquotes enclose lengthy quoted content in an indented block.
@@ -96,6 +160,13 @@ Lorem Ipsum said:
 > adipiscing.
 ```
 
+> Lorem Ipsum said:
+>
+> <blockquote>Dolor sit amet adipiscing.</blockquote>
+
+Class:
+* `MDBlockQuoteReader`
+
 ### Code Blocks
 
 Blocks of preformatted code can be enclosed in triple backticks.
@@ -108,7 +179,14 @@ function foo() {
 `​``
 ```
 
-Alternately, lines indented by at least four spaces or a tab character will be interpreted as code blocks.
+> <pre><code>
+> function foo() {
+>     return 'bar';
+> }
+> </code></pre>
+
+Alternately, lines indented by at least four spaces or a tab character will be
+interpreted as code blocks.
 
 ```markdown
     function foo() {
@@ -116,9 +194,20 @@ Alternately, lines indented by at least four spaces or a tab character will be i
 	}
 ```
 
+> <pre><code>
+> function foo() {
+>     return 'bar';
+> }
+> </code></pre>
+
+Classes:
+* `MDFencedCodeBlockReader`
+* `MDIndentedCodeBlockReader`
+
 ### Horizontal Rule
 
-Horizontal divider lines are written as 3 or more hyphens or asterisks on a line by themselves, with or without interstitial whitespace.
+Horizontal divider lines are written as 3 or more hyphens or asterisks on a line
+by themselves, with or without interstitial whitespace.
 
 ```markdown
 ---
@@ -130,6 +219,17 @@ Horizontal divider lines are written as 3 or more hyphens or asterisks on a line
 * * * * * * *
 ```
 
+> <hr>
+>
+> <hr>
+>
+> <hr>
+>
+> <hr>
+
+Class:
+* `MDHorizontalRuleReader`
+
 ### Tables
 
 Tables consist of one header row and any number of body rows
@@ -141,9 +241,20 @@ Cell     | 123 |  xyz
 Next row | 543 |  abc
 ```
 
+> <table>
+> <thead>
+> <tr><th>Header</th><th>Row</th><th>Here</th></tr>
+> </thead>
+> <tbody>
+> <tr><td>Cell</td><td>123</td><td>xyz</td></tr>
+> <tr><td>Next row</td><td>543</td><td>abc</td></tr>
+> </tbody>
+> </table>
+
 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.
+Rows can optionally have leading and/or trailing pipes. This is required for a
+single column table.
 
 ```markdown
 | One column |
@@ -152,6 +263,16 @@ Rows can optionally have leading and/or trailing pipes. This is required for a s
 | 234 |
 ```
 
+> <table>
+> <thead>
+> <tr><th>One column</th></tr>
+> </thead>
+> <tbody>
+> <tr><td>123</td></tr>
+> <tr><td>234</td></tr>
+> </tbody>
+> </table>
+
 Columns can be right, center, or left aligned with colons in the divider line.
 
 ```markdown
@@ -160,7 +281,21 @@ Columns can be right, center, or left aligned with colons in the divider line.
 | 1 | 2 | 3 |
 ```
 
-Tables can optionally support simple [spreadsheet expressions](spreadsheet.md) by adding the spreadsheet block reader when configuring a parser.
+> <table>
+> <thead>
+> <tr><th style="text-align: left;">Left</th><th style="text-align: center;">Center</th><th style="text-align: right;">Right</th></tr>
+> </thead>
+> <tbody>
+> <tr><td style="text-align: left;">1</td><td style="text-align: center;">2</td><td style="text-align: right;">3</td></tr>
+> </tbody>
+> </table>
+
+Tables can optionally support simple [spreadsheet expressions](spreadsheet.md)
+by adding the spreadsheet block reader when configuring a parser.
+
+Classes:
+* `MDTableReader`
+* `MDSpreadsheetReader`
 
 ### Definition List
 
@@ -174,20 +309,41 @@ another
 : alternate definition of another
 ```
 
+> <dl>
+> <dt>term</dt>
+> <dd>definition of term</dd>
+> <dt>another</dt>
+> <dd>definition of another</dd>
+> <dd>alternate definition of another</dd>
+> </dl>
+
+Class:
+* `MDDefinitionListReader`
+
 ### 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).
+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
+Always remember, ABC.
+
 *[ABC]: Always Be Closing
 ```
 
+> Always remember, <abbr title="Always Be Closing">ABC</abbr>.
+
+Class:
+* `MDAbbreviationReader`
+
 ### CSS Modifiers
 
-Many block structures can be modified with CSS classes, IDs, or other simple HTML attributes inside curly braces.
+Many block structures can be modified with CSS classes, IDs, or other simple
+HTML attributes inside curly braces.
 
 ```markdown
-# Header {.mycssclass}
+## Header with a CSS class {.mycssclass}
 
 --- {#mydividerid}
 
@@ -195,9 +351,23 @@ Many block structures can be modified with CSS classes, IDs, or other simple HTM
 |---|
 |123|
 
-# Multiple Modifiers {.linkclass #linkid lang=en}
+## Header with multiple modifiers {.linkclass #linkid lang=en}
 ```
 
+> <h2 class="mycssclass">Header with a CSS class</h2>
+>
+> <hr id="mydividerid">
+>
+> <table style="color: green;">
+> <thead><tr><th>Table</th></tr></thead>
+> <tbody><tr><td>123</td></tr></tbody>
+> </table>
+>
+> <h2 class="linkclass" id="linkid" lang="en">Header with multiple modifiers</h2>
+
+Class:
+* `MDModifierReader`
+
 ## Inline Formats
 
 Formats that apply within a block to style runs of words or inject other content within text.
@@ -207,9 +377,14 @@ Formats that apply within a block to style runs of words or inject other content
 Text can be marked as bold by enclosing it in double asterisks.
 
 ```markdown
-Some **bold** text. Can also use __underscores__.
+Some **bold** text. Can also use __underscores__ (unless underlining is enabled).
 ```
 
+> Some <strong>bold</strong> text. Can also use <strong>underscores</strong> (unless underlining is enabled).
+
+Class:
+* `MDStrongReader`
+
 ### Emphasis
 
 Text can be marked as italic by enclosing it in single underscores or single asterisks.
@@ -218,14 +393,52 @@ Text can be marked as italic by enclosing it in single underscores or single ast
 Some _italic_ text. Can also use *asterisks*.
 ```
 
+> Some <em>italic</em> text. Can also use <em>asterisks</em>.
+
+Class:
+* `MDEmphasisReader`
+
 ### Strikethrough
 
-Text can be stricken out using tildes, singly or in pairs.
+Text can be stricken out using tildes, singly or in pairs. If subscript is
+enabled then only double tildes can be used.
 
 ```markdown
 Not ~~this text~~. Not ~this text~ either.
 ```
 
+> Not <s>this text</s>. Not <s>this text</s> either.
+
+Class:
+* `MDStrikethroughReader`
+
+### Underline
+
+Underline is denoted with double underscores. If this reader is in use,
+"strong" styling can only be done with double asterisks.
+
+```markdown
+Some __underlined__ text.
+```
+
+> Some <u>underlined</u> text.
+
+Class:
+* `MDUnderlineReader`
+
+### Highlighting
+
+Highlighting is done with pairs of equals around text.
+
+```markdown
+Some ==highlighted== text.
+```
+
+> Some <mark>highlighted</mark> text.
+
+Class:
+* `MDHighlightReader`
+
 ### Code
 
 Words can be rendered in monospace font using single backticks.
@@ -234,6 +447,37 @@ Words can be rendered in monospace font using single backticks.
 The name of the function is `foo()`.
 ```
 
+> The name of the function is <code>foo()</code>.
+
+Class:
+* `MDCodeSpanReader`
+
+### Subscript
+
+Subscript is denoted with single tildes around the text.
+
+```markdown
+The formula for water is H~2~O.
+```
+
+> The formula for water is H<sup>2</sup>O.
+
+Class:
+* `MDSubscriptReader`
+
+### Superscript
+
+Superscript is represented with caret characters around the text.
+
+```markdown
+Einstein's equation E=mc^2^.
+```
+
+> Einstein's equation is E=mc<sup>2</sup>.
+
+Class:
+* `MDSuperscriptReader`
+
 ### Link
 
 Linking to a document is done with marked text and a URL.
@@ -242,12 +486,16 @@ Linking to a document is done with marked text and a URL.
 Click [here](page.html).
 ```
 
+> Click <a href="page.html">here</a>.
+
 An optional mouseover title can be added to the link after the URL.
 
 ```markdown
 Click [here](page.html "Goes to a neat page").
 ```
 
+> Click <a href="page.html" title="Goes to a neat page">here</a>.
+
 Repetitive or lengthy URLs can be referenced out and defined elsewhere in the document.
 
 ```markdown
@@ -256,12 +504,22 @@ Click [here][foo] or [here][foo] or [even here][foo] to go to the same place.
 [foo]: page.html "Optional title"
 ```
 
+> Click <a href="page.html" title="Optional title">here</a> or
+> <a href="page.html" title="Optional title">here</a> or
+> <a href="page.html" title="Optional title">even here</a> to go to the same place.
+
 Lastly, to make a link with the URL as the link text, you can use angle brackets.
 
 ```markdown
 Go visit <page.html>.
 ```
 
+> Go visit <a href="page.html">page.html</a>.
+
+Classes:
+* `MDLinkReader`
+* `MDReferencedLinkReader`
+
 ### 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.
@@ -270,12 +528,16 @@ An image is similar to link syntax with an exclamation in front. Instead of clic
 ![a test image](https://picsum.photos/100/75)
 ```
 
+> <img src="https://picsum.photos/100/75" alt="a test image">
+
 Images also support title attributes.
 
 ```markdown
 ![a test image](https://picsum.photos/100/75 "title text")
 ```
 
+> <img src="https://picsum.photos/100/75" alt="a test image" title="title text">
+
 Images also support referenced URLs.
 
 ```markdown
@@ -284,12 +546,20 @@ Images also support referenced URLs.
 [foo]: https://picsum.photos/100/75
 ```
 
+> <img src="https://picsum.photos/100/75" alt="alt text">
+
 Images can be made clickable by enclosing them in a link where the link text goes.
 
 ```markdown
-[![alt text](image.jpg)](page.html)
+[![alt text](https://picsum.photos/100/75)](page.html)
 ```
 
+> <a href="page.html"><img src="https://picsum.photos/100/75" alt="alt text"></a>
+
+Classes:
+* `MDImageReader`
+* `MDReferencedImageReader`
+
 ### 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.
@@ -301,6 +571,20 @@ Lorem ipsum[^1] dolor sit[^2] amet.
 [^2]: See _Interesting Book_, pg 213
 ```
 
+> <p>Lorem ipsum<sup><a href="#footnote1" id="footnote_ref1">1</a></sup> dolor sit<sup><a href="#footnote2" id="footnote_ref2">2</a></sup> amet.</p>
+>
+> <hr>
+> <ol>
+> <li>Further information here <a href="#footnote_ref1">↩︎</a></li>
+> <li>See <em>Interesting Book</em>, pg 213 <a href="#footnote_ref2">↩︎</a></li>
+> </ol>
+
+Class:
+* `MDFootnoteReader`
+
 ### HTML Tags
 
 Currently all HTML tags and attributes are permitted, when markdown syntax doesn't do what you want.
+
+Class:
+* `MDHTMLTagReader`

spreadsheet.md

@@ -1,6 +1,6 @@
 # Spreadsheet Expressions
 
-Spreadsheet expressions are an optional feature not enabled in the default parser configurations. To enable it, include `spreadsheet.js` and create a `Markdown` instance with a `MDSpreadsheetBlockReader`.
+Spreadsheet expressions are an optional feature not enabled in the default parser configurations. To enable it, include `spreadsheet.js` and create a `Markdown` instance with a `MDSpreadsheetReader`.
 
 ## Expressions