Tissevert/pandoc
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions 1

Partial restructuring of README.

Browse source 
Aim is to provide a complete markdown syntax description,
including pandoc differences.
This commit is contained in:
John MacFarlane 2011-01-28 18:33:42 -08:00
parent 7f5130709b
commit 2837ad46fe
1 changed files with 466 additions and 281 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

747
README
View file

@ -558,88 +558,235 @@ noting differences from standard markdown. Except where noted, these
differences can be suppressed by specifying the `--strict` command-line differences can be suppressed by specifying the `--strict` command-line
option. option.
Backslash escapes Gruber designed markdown to be easy to write, and, even more importantly,
----------------- easy to read:
Except inside a code block or inline code, any punctuation or space > A Markdown-formatted document should be publishable as-is, as plain
character preceded by a backslash will be treated literally, even if it > text, without looking like it's been marked up with tags or formatting
would normally indicate formatting. Thus, for example, if one writes > instructions.
> -- [John Gruber](http://daringfireball.net/projects/markdown/syntax#philosophy)
*\*hello\** This principle has guided pandoc's decisions in finding syntax for
tables, footnotes, and other extensions.
one will get There is, however, one respect in which pandoc's aims are different
from the original aims of markdown. Whereas markdown was originally
designed with HTML generation in mind, pandoc is designed for multiple
output formats. Thus, while pandoc allows the embedding of raw HTML,
it discourages it, and provides other, non-HTMLish ways of representing
important document elements like definition lists, tables, mathematics, and
footnotes.
<em>*hello*</em> Paragraphs
----------
instead of A paragraph is one or more lines of text followed by one or more blank line.
Newlines are treated as spaces, so you can reflow your paragraphs as you like.
If you need a hard line break, put two or more spaces at the end of a line,
or or type a backslash followed by a newline.
<strong>hello</strong> Headers
-------
This rule is easier to remember than standard markdown's rule, There are two kinds of headers, Setext and atx.
which allows only the following characters to be backslash-escaped:
\`*_{}[]()>#+-.! ### Setext-style headers ###
A backslash-escaped space is parsed as a nonbreaking space. It will A setext-style header is a line of text "underlined" with a row of `=` signs
appear in TeX output as `~` and in HTML and XML as `\&#160;` or (for a level one header) of `-` signs (for a level two header):
`\&nbsp;`.
A backslash-escaped newline (i.e. a backslash occurring at the end of A level-one header
a line) is parsed as a hard line break. It will appear in TeX output as ==================
`\\` and in HTML as `<br />`. This is a nice alternative to
markdown's "invisible" way of indicating hard line breaks using
two trailing spaces on a line.
Subscripts and superscripts A level-two header
--------------------------- ------------------
Superscripts may be written by surrounding the superscripted text by `^` The header text can contain inline formatting, such as emphasis (see
characters; subscripts may be written by surrounding the subscripted [Inline formatting](#inline-formatting), below).
text by `~` characters. Thus, for example,
H~2~O is a liquid. 2^10^ is 1024.
If the superscripted or subscripted text contains spaces, these spaces ### Atx-style headers ###
must be escaped with backslashes. (This is to prevent accidental
superscripting and subscripting through the ordinary use of `~` and `^`.)
Thus, if you want the letter P with 'a cat' in subscripts, use
`P~a\ cat~`, not `P~a cat~`.
Strikeout An Atx-style header consists of one to six `#` signs and a line of
--------- text, optionally followed by any number of `#` signs. The number of
`#` signs at the beginning of the line is the header level:
To strikeout a section of text with a horizontal line, begin and end it ## A level-two header
with `~~`. Thus, for example,
This ~~is deleted text.~~ ### A level-three header ###
Nested Lists As with setext-style headers, the header text can contain formatting:
------------
Pandoc behaves differently from standard markdown on some "edge # A level-one header with a [link](/url) and *emphasis*
cases" involving lists. Consider this source:
1. First
2. Second:
- Fee
- Fie
- Foe
3. Third ### Header identifiers in HTML ###
Pandoc transforms this into a "compact list" (with no `<p>` tags around *Pandoc extension*.
"First", "Second", or "Third"), while markdown puts `<p>` tags around
"Second" and "Third" (but not "First"), because of the blank space
around "Third". Pandoc follows a simple rule: if the text is followed by
a blank line, it is treated as a paragraph. Since "Second" is followed
by a list, and not a blank line, it isn't treated as a paragraph. The
fact that the list is followed by a blank line is irrelevant. (Note:
Pandoc works this way even when the `--strict` option is specified. This
behavior is consistent with the official markdown syntax description,
even though it is different from that of `Markdown.pl`.)
Ordered Lists Each header element in pandoc's HTML output is given a unique
------------- identifier. This identifier is based on the text of the header. To
derive the identifier from the header text,
- Remove all formatting, links, etc.
- Remove all punctuation, except underscores, hyphens, and periods.
- Replace all spaces and newlines with hyphens.
- Convert all alphabetic characters to lowercase.
- Remove everything up to the first letter (identifiers may
not begin with a number or punctuation mark).
- If nothing is left after this, use the identifier `section`.
Thus, for example,
Header Identifier
------------------------------- ----------------------------
Header identifiers in HTML `header-identifiers-in-html`
*Dogs*?--in *my* house? `dogs--in-my-house`
[HTML], [S5], or [RTF]? `html-s5-or-rtf`
3. Applications `applications`
33 `section`
These rules should, in most cases, allow one to determine the identifier
from the header text. The exception is when several headers have the
same text; in this case, the first will get an identifier as described
above; the second will get the same identifier with `-1` appended; the
third with `-2`; and so on.
These identifiers are used to provide link targets in the table of
contents generated by the `--toc|--table-of-contents` option. They
also make it easy to provide links from one section of a document to
another. A link to this section, for example, might look like this:
See the section on [header identifiers](#header-identifiers-in-html).
Note, however, that this method of providing links to sections works
only in HTML.
If the `--section-divs` option is specified, then each section will
be wrapped in a `div` (or a `section`, if `--html5` was specified),
and the identifier will be attached to the enclosing `<div>`
(or `<section>`) tag rather than the header itself. This allows entire
sections to be manipulated using javascript or treated differently in
CSS.
Block quotations
----------------
Markdown uses email conventions for quoting blocks of text.
A block quotation is one or more paragraphs or other block elements
(such as lists or headers), with each line preceded by a `>` character
and a space. (The `>` need not start at the left margin, but it should
not be indented more than three spaces.)
> This is a block quote. This
> paragraph has two lines.
>
> 1. This is a list inside a block quote.
> 2. Second item.
A "lazy" form, which requires the `>` character only on the first
line of each block, is also allowed:
> This is a block quote. This
paragraph has two lines.
> 1. This is a list inside a block quote.
2. Second item.
Among the block elements that can be contained in a block quote are
other block quotes. That is, block quotes can be nested:
> This is a block quote.
>
> > A block quote within a block quote.
*** TODO: decide whether pandoc should require a blank
line btw nested ***
Standard markdown syntax does not require a blank line before a header
or blockquote. Pandoc does require this (except, of course, at the
beginning of the document). The reason for the requirement is that
it is all too easy for a `>` or `#` to end up at the beginning of a
line by accident (perhaps through line wrapping). Consider, for
example:
I like several of their flavors of ice cream:
#22, for example, and #5.
Verbatim (code) blocks
----------------------
### Indented code blocks ###
TODO
### Delimited code blocks ###
*Pandoc extension*.
In addition to standard indented code blocks, Pandoc supports
*delimited* code blocks. These begin with a row of three or more
tildes (`~`) and end with a row of tildes that must be at least
as long as the starting row. Everything between the tilde-lines
is treated as code. No indentation is necessary:
~~~~~~~
{code here}
~~~~~~~
Like regular code blocks, delimited code blocks must be separated
from surrounding text by blank lines.
If the code itself contains a row of tildes, just use a longer
row of tildes at the start and end:
~~~~~~~~~~~~~~~~
~~~~~~~~~~
code including tildes
~~~~~~~~~~
~~~~~~~~~~~~~~~~
Optionally, you may specify the language of the code block using
this syntax:
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ {.haskell .numberLines}
qsort [] = []
qsort (x:xs) = qsort (filter (< x) xs) ++ [x] ++
qsort (filter (>= x) xs)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Some output formats can use this information to do syntax highlighting.
Currently, the only output format that uses this information is HTML.
If pandoc has been compiled with syntax highlighting support, then the
code block above will appear highlighted, with numbered lines. (To see
which languages are supported, do `pandoc --version`.)
If pandoc has not been compiled with syntax highlighting support, the
code block above will appear as follows:
<pre class="haskell">
<code>
...
</code>
</pre>
Lists
-----
### Bullet lists ###
TODO
### Ordered lists ###
TODO - basic description
Unlike standard markdown, Pandoc allows ordered list items to be marked Unlike standard markdown, Pandoc allows ordered list items to be marked
with uppercase and lowercase letters and roman numerals, in addition to with uppercase and lowercase letters and roman numerals, in addition to
@ -692,34 +839,10 @@ If default list markers are desired, use `#.`:
#. two #. two
#. three #. three
Numbered examples
-----------------
The special list marker `@` can be used for sequentially numbered ### Definition lists ###
examples. The first list item with a `@` marker will be numbered '1',
the next '2', and so on, throughout the document. The numbered examples
need not occur in a single list; each new list using `@` will take up
where the last stopped. So, for example:
(@) My first example will be numbered (1). *Pandoc extension*.
(@) My second example will be numbered (2).
Explanation of examples.
(@) My third example will be numbered (3).
Numbered examples can be labeled and referred to elsewhere in the
document:
(@good) This is a good example.
As (@good) illustrates, ...
The label can be any string of alphanumeric characters, underscores,
or hyphens.
Definition lists
----------------
Pandoc supports definition lists, using a syntax inspired by Pandoc supports definition lists, using a syntax inspired by
[PHP Markdown Extra] and [reStructuredText]:[^3] [PHP Markdown Extra] and [reStructuredText]:[^3]
@ -759,63 +882,71 @@ definition and the next term:
[PHP Markdown Extra]: http://www.michelf.com/projects/php-markdown/extra/ [PHP Markdown Extra]: http://www.michelf.com/projects/php-markdown/extra/
Reference links
---------------
Pandoc allows implicit reference links with just a single set of ### Numbered example lists ###
brackets. So, the following links are equivalent:
1. Here's my [link] *Pandoc extension*.
2. Here's my [link][]
[link]: linky.com The special list marker `@` can be used for sequentially numbered
examples. The first list item with a `@` marker will be numbered '1',
the next '2', and so on, throughout the document. The numbered examples
need not occur in a single list; each new list using `@` will take up
where the last stopped. So, for example:
(Note: Pandoc works this way even if `--strict` is specified, because (@) My first example will be numbered (1).
`Markdown.pl` 1.0.2b7 allows single-bracket links.) (@) My second example will be numbered (2).
Footnotes Explanation of examples.
---------
Pandoc's markdown allows footnotes, using the following syntax: (@) My third example will be numbered (3).
Here is a footnote reference,[^1] and another.[^longnote] Numbered examples can be labeled and referred to elsewhere in the
document:
[^1]: Here is the footnote. (@good) This is a good example.
[^longnote]: Here's one with multiple blocks. As (@good) illustrates, ...
Subsequent paragraphs are indented to show that they The label can be any string of alphanumeric characters, underscores,
belong to the previous footnote. or hyphens.
{ some.code }
The whole paragraph can be indented, or just the first ### Nested lists ###
line. In this way, multi-paragraph footnotes work like
multi-paragraph list items.
This paragraph won't be part of the note, because it isn't indented. Pandoc behaves differently from standard markdown on some "edge
cases" involving lists. Consider this source:
The identifiers in footnote references may not contain spaces, tabs, 1. First
or newlines. These identifiers are used only to correlate the 2. Second:
footnote reference with the note itself; in the output, footnotes - Fee
will be numbered sequentially. - Fie
- Foe
The footnotes themselves need not be placed at the end of the 3. Third
document. They may appear anywhere except inside other block elements
(lists, block quotes, tables, etc.).
Inline footnotes are also allowed (though, unlike regular notes, Pandoc transforms this into a "compact list" (with no `<p>` tags around
they cannot contain multiple paragraphs). The syntax is as follows: "First", "Second", or "Third"), while markdown puts `<p>` tags around
"Second" and "Third" (but not "First"), because of the blank space
around "Third". Pandoc follows a simple rule: if the text is followed by
a blank line, it is treated as a paragraph. Since "Second" is followed
by a list, and not a blank line, it isn't treated as a paragraph. The
fact that the list is followed by a blank line is irrelevant. (Note:
Pandoc works this way even when the `--strict` option is specified. This
behavior is consistent with the official markdown syntax description,
even though it is different from that of `Markdown.pl`.)
Here is an inline note.^[Inlines notes are easier to write, since
you don't have to pick an identifier and move down to type the
note.]
Inline and regular footnotes may be mixed freely. Horizontal rules
----------------
TODO
Tables Tables
------ ------
*Pandoc extension*.
Three kinds of tables may be used. All three kinds presuppose the use of Three kinds of tables may be used. All three kinds presuppose the use of
a fixed-width font, such as Courier. a fixed-width font, such as Courier.
@ -934,79 +1065,11 @@ columns or rows. Grid tables can be created easily using [Emacs table mode].
[Emacs table mode]: http://table.sourceforge.net/ [Emacs table mode]: http://table.sourceforge.net/
Delimited Code blocks
---------------------
In addition to standard indented code blocks, Pandoc supports Title block
*delimited* code blocks. These begin with a row of three or more -----------
tildes (`~`) and end with a row of tildes that must be at least
as long as the starting row. Everything between the tilde-lines
is treated as code. No indentation is necessary:
~~~~~~~ *Pandoc extension*.
{code here}
~~~~~~~
Like regular code blocks, delimited code blocks must be separated
from surrounding text by blank lines.
If the code itself contains a row of tildes, just use a longer
row of tildes at the start and end:
~~~~~~~~~~~~~~~~
~~~~~~~~~~
code including tildes
~~~~~~~~~~
~~~~~~~~~~~~~~~~
Optionally, you may specify the language of the code block using
this syntax:
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ {.haskell .numberLines}
qsort [] = []
qsort (x:xs) = qsort (filter (< x) xs) ++ [x] ++
qsort (filter (>= x) xs)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Some output formats can use this information to do syntax highlighting.
Currently, the only output format that uses this information is HTML.
If pandoc has been compiled with syntax highlighting support, then the
code block above will appear highlighted, with numbered lines. (To see
which languages are supported, do `pandoc --version`.)
If pandoc has not been compiled with syntax highlighting support, the
code block above will appear as follows:
<pre class="haskell">
<code>
...
</code>
</pre>
Images with captions
--------------------
An image occurring by itself in a paragraph will be rendered as
a figure with a caption.[^5] (In LaTeX, a figure environment will be
used; in HTML, the image will be placed in a `div` with class
`figure`, together with a caption in a `p` with class `caption`.)
The image's alt text will be used as the caption.
![This is the caption](/url/of/image.png)
[^5]: This feature is not yet implemented for RTF, OpenDocument, or
ODT. In those formats, you'll just get an image in a paragraph by
itself, with no caption.
If you just want a regular inline image, just make sure it is not
the only thing in the paragraph. One way to do this is to insert a
nonbreaking space after the image:
![This image won't be a figure](/url/of/image.png)\
Title blocks
------------
If the file begins with a title block If the file begins with a title block
@ -1082,113 +1145,108 @@ will also have "Pandoc User Manuals" in the footer.
will also have "Version 4.0" in the header. will also have "Version 4.0" in the header.
Markdown in HTML blocks
-----------------------
While standard markdown leaves HTML blocks exactly as they are, Pandoc Backslash escapes
treats text between HTML tags as markdown. Thus, for example, Pandoc -----------------
will turn
<table> Except inside a code block or inline code, any punctuation or space
<tr> character preceded by a backslash will be treated literally, even if it
<td>*one*</td> would normally indicate formatting. Thus, for example, if one writes
<td>[a link](http://google.com)</td>
</tr>
</table>
into *\*hello\**
<table> one will get
<tr>
<td><em>one</em></td>
<td><a href="http://google.com">a link</a></td>
</tr>
</table>
whereas `Markdown.pl` will preserve it as is. <em>*hello*</em>
There is one exception to this rule: text between `<script>` and instead of
`</script>` tags is not interpreted as markdown.
This departure from standard markdown should make it easier to mix <strong>hello</strong>
markdown with HTML block elements. For example, one can surround
a block of markdown text with `<div>` tags without preventing it
from being interpreted as markdown.
Header identifiers in HTML This rule is easier to remember than standard markdown's rule,
-------------------------- which allows only the following characters to be backslash-escaped:
Each header element in pandoc's HTML output is given a unique \`*_{}[]()>#+-.!
identifier. This identifier is based on the text of the header. To
derive the identifier from the header text,
- Remove all formatting, links, etc. (However, if the `--strict` option is supplied, the standard
- Remove all punctuation, except underscores, hyphens, and periods. markdown rule will be used.)
- Replace all spaces and newlines with hyphens.
- Convert all alphabetic characters to lowercase.
- Remove everything up to the first letter (identifiers may
not begin with a number or punctuation mark).
- If nothing is left after this, use the identifier `section`.
Thus, for example, A backslash-escaped space is parsed as a nonbreaking space. It will
appear in TeX output as `~` and in HTML and XML as `\&#160;` or
`\&nbsp;`.
Header Identifier A backslash-escaped newline (i.e. a backslash occurring at the end of
------------------------------------- ---------------------------- a line) is parsed as a hard line break. It will appear in TeX output as
Header identifiers in HTML `header-identifiers-in-html` `\\` and in HTML as `<br />`. This is a nice alternative to
*Dogs*?--in *my* house? `dogs--in-my-house` markdown's "invisible" way of indicating hard line breaks using
[HTML], [S5], or [RTF]? `html-s5-or-rtf` two trailing spaces on a line.
3. Applications `applications`
33 `section`
These rules should, in most cases, allow one to determine the identifier Smart punctuation
from the header text. The exception is when several headers have the -----------------
same text; in this case, the first will get an identifier as described
above; the second will get the same identifier with `-1` appended; the
third with `-2`; and so on.
These identifiers are used to provide link targets in the table of If the `--smart` option is specified, pandoc will produce typographically
contents generated by the `--toc|--table-of-contents` option. They correct output, converting straight quotes to curly quotes, `---` and `--`
also make it easy to provide links from one section of a document to to Em-dashes, and `...` to ellipses. Nonbreaking spaces are inserted after
another. A link to this section, for example, might look like this: certain abbreviations, such as "Mr."
See the section on [header identifiers](#header-identifiers-in-html). Inline formatting
-----------------
Note, however, that this method of providing links to sections works ### Emphasis ###
only in HTML.
If the `--section-divs` option is specified, then each section will TODO
be wrapped in a `div` (or a `section`, if `--html5` was specified),
and the identifier will be attached to the enclosing `<div>`
(or `<section>`) tag rather than the header itself. This allows entire
sections to be manipulated using javascript or treated differently in
CSS.
Blank lines before headers and blockquotes inc strong
------------------------------------------
Standard markdown syntax does not require a blank line before a header
or blockquote. Pandoc does require this (except, of course, at the
beginning of the document). The reason for the requirement is that
it is all too easy for a `>` or `#` to end up at the beginning of a
line by accident (perhaps through line wrapping). Consider, for
example:
I like several of their flavors of ice cream: ### Strikeout ###
#22, for example, and #5.
*Pandoc extension*.
To strikeout a section of text with a horizontal line, begin and end it
with `~~`. Thus, for example,
This ~~is deleted text.~~
### Superscripts and subscripts ###
*Pandoc extension*.
Superscripts may be written by surrounding the superscripted text by `^`
characters; subscripts may be written by surrounding the subscripted
text by `~` characters. Thus, for example,
H~2~O is a liquid. 2^10^ is 1024.
If the superscripted or subscripted text contains spaces, these spaces
must be escaped with backslashes. (This is to prevent accidental
superscripting and subscripting through the ordinary use of `~` and `^`.)
Thus, if you want the letter P with 'a cat' in subscripts, use
`P~a\ cat~`, not `P~a cat~`.
### Verbatim ###
TODO
(w/ attrs)
Math Math
---- ----
Anything between two $ characters will be treated as TeX math. The *Pandoc extension*.
opening $ must have a character immediately to its right, while the
closing $ must have a character immediately to its left. Thus, Anything between two `$` characters will be treated as TeX math. The
opening `$` must have a character immediately to its right, while the
closing `$` must have a character immediately to its left. Thus,
`$20,000 and $30,000` won't parse as math. If for some reason `$20,000 and $30,000` won't parse as math. If for some reason
you need to enclose text in literal $ characters, backslash-escape you need to enclose text in literal `$` characters, backslash-escape
them and they won't be treated as math delimiters. them and they won't be treated as math delimiters.
TeX math will be printed in all output formats. In Markdown, TeX math will be printed in all output formats. In Markdown,
reStructuredText, LaTeX, Org-Mode, and ConTeXt output, it will appear reStructuredText, LaTeX, Org-Mode, and ConTeXt output, it will appear
verbatim between $ characters. verbatim between `$` characters.
In reStructuredText output, it will be rendered using an interpreted In reStructuredText output, it will be rendered using an interpreted
text role `:math:`, as described text role `:math:`, as described
@ -1196,7 +1254,7 @@ text role `:math:`, as described
In Texinfo output, it will be rendered inside a `@math` command. In Texinfo output, it will be rendered inside a `@math` command.
In groff man output, it will be rendered verbatim without $'s. In groff man output, it will be rendered verbatim without `$`'s.
In MediaWiki output, it will be rendered inside `<math>` tags. In MediaWiki output, it will be rendered inside `<math>` tags.
@ -1250,20 +1308,13 @@ command-line options selected:
with the URL provided. If no URL is specified, the Google Chart with the URL provided. If no URL is specified, the Google Chart
API will be used (`http://chart.apis.google.com/chart?cht=tx&chl=`). API will be used (`http://chart.apis.google.com/chart?cht=tx&chl=`).
LaTeX Macros
------------
For output formats other than LaTeX, pandoc will parse LaTeX `\newcommand` and Raw TeX
`\renewcommand` definitions and apply the resulting macros to all LaTeX -------
math. So, for example, the following will work in all output formats,
not just LaTeX:
\newcommand{\tuple}[1]{\langle #1 \rangle} TODO
$\tuple{a, b, c}$ (raw tex is extension)
Inline TeX
----------
Inline TeX commands will be preserved and passed unchanged to the Inline TeX commands will be preserved and passed unchanged to the
LaTeX and ConTeXt writers. Thus, for example, you can use LaTeX to LaTeX and ConTeXt writers. Thus, for example, you can use LaTeX to
@ -1286,9 +1337,142 @@ LaTeX, not as markdown.
Inline LaTeX is ignored in output formats other than Markdown, LaTeX, Inline LaTeX is ignored in output formats other than Markdown, LaTeX,
and ConTeXt. and ConTeXt.
For output formats other than LaTeX, pandoc will parse LaTeX `\newcommand` and
`\renewcommand` definitions and apply the resulting macros to all LaTeX
math. So, for example, the following will work in all output formats,
not just LaTeX:
\newcommand{\tuple}[1]{\langle #1 \rangle}
$\tuple{a, b, c}$
Raw HTML
--------
TODO
While standard markdown leaves HTML blocks exactly as they are, Pandoc
treats text between HTML tags as markdown. Thus, for example, Pandoc
will turn
<table>
<tr>
<td>*one*</td>
<td>[a link](http://google.com)</td>
</tr>
</table>
into
<table>
<tr>
<td><em>one</em></td>
<td><a href="http://google.com">a link</a></td>
</tr>
</table>
whereas `Markdown.pl` will preserve it as is.
There is one exception to this rule: text between `<script>` and
`</script>` tags is not interpreted as markdown.
This departure from standard markdown should make it easier to mix
markdown with HTML block elements. For example, one can surround
a block of markdown text with `<div>` tags without preventing it
from being interpreted as markdown.
Links
-----
TODO
Pandoc allows implicit reference links with just a single set of
brackets. So, the following links are equivalent:
1. Here's my [link]
2. Here's my [link][]
[link]: linky.com
(Note: Pandoc works this way even if `--strict` is specified, because
`Markdown.pl` 1.0.2b7 allows single-bracket links.)
Images
------
TODO
An image occurring by itself in a paragraph will be rendered as
a figure with a caption.[^5] (In LaTeX, a figure environment will be
used; in HTML, the image will be placed in a `div` with class
`figure`, together with a caption in a `p` with class `caption`.)
The image's alt text will be used as the caption.
![This is the caption](/url/of/image.png)
[^5]: This feature is not yet implemented for RTF, OpenDocument, or
ODT. In those formats, you'll just get an image in a paragraph by
itself, with no caption.
If you just want a regular inline image, just make sure it is not
the only thing in the paragraph. One way to do this is to insert a
nonbreaking space after the image:
![This image won't be a figure](/url/of/image.png)\
Footnotes
---------
*Pandoc extension*.
Pandoc's markdown allows footnotes, using the following syntax:
Here is a footnote reference,[^1] and another.[^longnote]
[^1]: Here is the footnote.
[^longnote]: Here's one with multiple blocks.
Subsequent paragraphs are indented to show that they
belong to the previous footnote.
{ some.code }
The whole paragraph can be indented, or just the first
line. In this way, multi-paragraph footnotes work like
multi-paragraph list items.
This paragraph won't be part of the note, because it isn't indented.
The identifiers in footnote references may not contain spaces, tabs,
or newlines. These identifiers are used only to correlate the
footnote reference with the note itself; in the output, footnotes
will be numbered sequentially.
The footnotes themselves need not be placed at the end of the
document. They may appear anywhere except inside other block elements
(lists, block quotes, tables, etc.).
Inline footnotes are also allowed (though, unlike regular notes,
they cannot contain multiple paragraphs). The syntax is as follows:
Here is an inline note.^[Inlines notes are easier to write, since
you don't have to pick an identifier and move down to type the
note.]
Inline and regular footnotes may be mixed freely.
Citations Citations
--------- ---------
*Pandoc extension*.
Pandoc can automatically generate citations and a bibliography in a number of Pandoc can automatically generate citations and a bibliography in a number of
styles (using Andrea Rossato's `hs-citeproc`). In order to use this feature, styles (using Andrea Rossato's `hs-citeproc`). In order to use this feature,
you will need a bibliographic database in one of the following formats: you will need a bibliographic database in one of the following formats:
@ -1351,6 +1535,7 @@ document with an appropriate header:
The bibliography will be inserted after this header. The bibliography will be inserted after this header.
Producing HTML slide shows with Pandoc Producing HTML slide shows with Pandoc
====================================== ======================================