@@ -597,40 +597,6 @@ These work like simple tables, but with the following differences:
597 - They must end with a row of dashes, then a blank line.
597 - They must end with a row of dashes, then a blank line.
598 - The rows must be separated by blank lines.
598 - The rows must be separated by blank lines.
603−Pandoc treats embedded HTML in markdown a bit differently than
604−Markdown 1.0. While Markdown 1.0 leaves HTML blocks exactly as they
605−are, Pandoc treats text between HTML tags as markdown. Thus, for
606−example, Pandoc will turn
611− <td>[a link](http://google.com)</td>
619− <td><em>one</em></td>
620− <td><a href="http://google.com">a link</a></td>
624−whereas `Markdown.pl` will preserve it as is.
626−There is one exception to this rule: text between `<script>` and
627−`</script>` tags is not interpreted as markdown.
629−This departure from standard markdown should make it easier to mix
630−markdown with HTML block elements. For example, one can surround
631−a block of markdown text with `<div>` tags without preventing it
632−from being interpreted as markdown.
634Title blocks
600Title blocks
635------------
601------------
@@ -675,6 +641,75 @@ For example,
676The middle of the man page footer is used for the date.
642The middle of the man page footer is used for the date.
644+Markdown in HTML blocks
645+-----------------------
647+While standard markdown leaves HTML blocks exactly as they are, Pandoc
648+treats text between HTML tags as markdown. Thus, for example, Pandoc
654+ <td>[a link](http://google.com)</td>
662+ <td><em>one</em></td>
663+ <td><a href="http://google.com">a link</a></td>
667+whereas `Markdown.pl` will preserve it as is.
669+There is one exception to this rule: text between `<script>` and
670+`</script>` tags is not interpreted as markdown.
672+This departure from standard markdown should make it easier to mix
673+markdown with HTML block elements. For example, one can surround
674+a block of markdown text with `<div>` tags without preventing it
675+from being interpreted as markdown.
677+Header identifiers in HTML
678+--------------------------
680+Each header element in pandoc's HTML output is given a unique
681+identifier. This identifier is based on the text of the header. To
682+derive the identifier from the header text,
684+ - Remove all formatting, links, etc.
685+ - Remove all punctuation, except dashes and hyphens.
686+ - Replace all spaces, dashes, newlines, and hyphens with hyphens.
687+ - Convert all alphabetic characters to lowercase.
691+ Header text Identifier
692+ --------------------------------- --- ----------------------------
693+ Header identifiers in HTML → `header-identifiers-in-html`
694+ *Dogs*?--in *my* house? → `dogs--in-my-house`
695+ [HTML], [S5], or [RTF]? → `html-s5-or-rtf`
697+These rules should, in most cases, allow one to determine the identifier
698+from the header text. The exception is when several headers have the
699+same text; in this case, the first will get an identifier as described
700+above; the second will get the same identifier with `-1` appended; the
701+third with `-2`; and so on.
703+These identifiers are used to provide link targets in the table of
704+contents generated by the `--toc|--table-of-contents` option. They
705+also make it easy to provide links from one section of a document to
706+another. A link to this section, for example, might look like this:
708+ See the section on [header identifiers](#header-identifiers-in-html).
710+Note, however, that this method of providing links to sections works
678Box-style blockquotes
713Box-style blockquotes
679---------------------
714---------------------