summaryrefslogtreecommitdiff log msg author committer range
path: root/man/man5/pandoc_markdown.5
diff options
 context: 12345678910152025303540 space: includeignore mode: unifiedssdiffstat only
Diffstat (limited to 'man/man5/pandoc_markdown.5')
-rw-r--r--man/man5/pandoc_markdown.51726
1 files changed, 1726 insertions, 0 deletions
\f[]+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\[aq]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 \f[C]--strict\f[] option is+specified.+This behavior is consistent with the official markdown syntax+description, even though it is different from that of+\f[C]Markdown.pl\f[].)+.SS Ending a list+.PP+What if you want to put an indented code block after a list?+.IP+.nf+\f[C]+-\ \ \ item\ one+-\ \ \ item\ two++\ \ \ \ {\ my\ code\ block\ }+\f[]+.fi+.PP+Trouble! Here pandoc (like other markdown implementations) will treat+\f[C]{\ my\ code\ block\ }\f[] as the second paragraph of item two, and+not as a code block.+.PP+To "cut off" the list after item two, you can insert some non-indented+content, like an HTML comment, which won\[aq]t produce visible output in+any format:+.IP+.nf+\f[C]+-\ \ \ item\ one+-\ \ \ item\ two++++\ \ \ \ {\ my\ code\ block\ }+\f[]+.fi+.PP+You can use the same trick if you want two consecutive lists instead of+one big list:+.IP+.nf+\f[C]+1.\ \ one+2.\ \ two+3.\ \ three++++a.\ \ uno+b.\ \ dos+c.\ \ tres+\f[]+.fi+.SH HORIZONTAL RULES+.PP+A line containing a row of three or more \f[C]*\f[], \f[C]-\f[], or+\f[C]_\f[] characters (optionally separated by spaces) produces a+horizontal rule:+.IP+.nf+\f[C]+*\ \ *\ \ *\ \ *++---------------+\f[]+.fi+.SH TABLES+.PP+\f[I]Pandoc extension\f[].+.PP+Three kinds of tables may be used.+All three kinds presuppose the use of a fixed-width font, such as+Courier.+.PP+\f[B]Simple tables\f[] look like this:+.IP+.nf+\f[C]+\ \ Right\ \ \ \ \ Left\ \ \ \ \ Center\ \ \ \ \ Default+-------\ \ \ \ \ ------\ ----------\ \ \ -------+\ \ \ \ \ 12\ \ \ \ \ 12\ \ \ \ \ \ \ \ 12\ \ \ \ \ \ \ \ \ \ \ \ 12+\ \ \ \ 123\ \ \ \ \ 123\ \ \ \ \ \ \ 123\ \ \ \ \ \ \ \ \ \ 123+\ \ \ \ \ \ 1\ \ \ \ \ 1\ \ \ \ \ \ \ \ \ \ 1\ \ \ \ \ \ \ \ \ \ \ \ \ 1++Table:\ \ Demonstration\ of\ simple\ table\ syntax.+\f[]+.fi+.PP+The headers and table rows must each fit on one line.+Column alignments are determined by the position of the header text+relative to the dashed line below it:[3]+.IP \[bu] 2+If the dashed line is flush with the header text on the right side but+extends beyond it on the left, the column is right-aligned.+.IP \[bu] 2+If the dashed line is flush with the header text on the left side but+extends beyond it on the right, the column is left-aligned.+.IP \[bu] 2+If the dashed line extends beyond the header text on both sides, the+column is centered.+.IP \[bu] 2+If the dashed line is flush with the header text on both sides, the+default alignment is used (in most cases, this will be left).+.PP+The table must end with a blank line, or a line of dashes followed by a+blank line.+A caption may optionally be provided (as illustrated in the example+above).+A caption is a paragraph beginning with the string \f[C]Table:\f[] (or+just \f[C]:\f[]), which will be stripped off.+It may appear either before or after the table.+.PP+The column headers may be omitted, provided a dashed line is used to end+the table.+For example:+.IP+.nf+\f[C]+-------\ \ \ \ \ ------\ ----------\ \ \ -------+\ \ \ \ \ 12\ \ \ \ \ 12\ \ \ \ \ \ \ \ 12\ \ \ \ \ \ \ \ \ \ \ \ \ 12+\ \ \ \ 123\ \ \ \ \ 123\ \ \ \ \ \ \ 123\ \ \ \ \ \ \ \ \ \ \ 123+\ \ \ \ \ \ 1\ \ \ \ \ 1\ \ \ \ \ \ \ \ \ \ 1\ \ \ \ \ \ \ \ \ \ \ \ \ \ 1+-------\ \ \ \ \ ------\ ----------\ \ \ -------+\f[]+.fi+.PP+When headers are omitted, column alignments are determined on the basis+of the first line of the table body.+So, in the tables above, the columns would be right, left, center, and+right aligned, respectively.+.PP+\f[B]Multiline tables\f[] allow headers and table rows to span multiple+lines of text (but cells that span multiple columns or rows of the table+are not supported).+Here is an example:+.IP+.nf+\f[C]+-------------------------------------------------------------+\ Centered\ \ \ Default\ \ \ \ \ \ \ \ \ \ \ Right\ Left+\ \ Header\ \ \ \ Aligned\ \ \ \ \ \ \ \ \ Aligned\ Aligned+-----------\ -------\ ---------------\ -------------------------+\ \ \ First\ \ \ \ row\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 12.0\ Example\ of\ a\ row\ that+\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ spans\ multiple\ lines.++\ \ Second\ \ \ \ row\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 5.0\ Here\[aq]s\ another\ one.\ Note+\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ the\ blank\ line\ between+\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ rows.+-------------------------------------------------------------++Table:\ Here\[aq]s\ the\ caption.\ It,\ too,\ may\ span+multiple\ lines.+\f[]+.fi+.PP+These work like simple tables, but with the following differences:+.IP \[bu] 2+They must begin with a row of dashes, before the header text (unless the+headers are omitted).+.IP \[bu] 2+They must end with a row of dashes, then a blank line.+.IP \[bu] 2+The rows must be separated by blank lines.+.PP+In multiline tables, the table parser pays attention to the widths of+the columns, and the writers try to reproduce these relative widths in+the output.+So, if you find that one of the columns is too narrow in the output, try+widening it in the markdown source.+.PP+Headers may be omitted in multiline tables as well as simple tables:+.IP+.nf+\f[C]+-----------\ -------\ ---------------\ -------------------------+\ \ \ First\ \ \ \ row\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 12.0\ Example\ of\ a\ row\ that+\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ spans\ multiple\ lines.++\ \ Second\ \ \ \ row\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 5.0\ Here\[aq]s\ another\ one.\ Note+\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ the\ blank\ line\ between+\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ rows.+-------------------------------------------------------------++:\ Here\[aq]s\ a\ multiline\ table\ without\ headers.+\f[]+.fi+.PP+It is possible for a multiline table to have just one row, but the row+should be followed by a blank line (and then the row of dashes that ends+the table), or the table may be interpreted as a simple table.+.PP+\f[B]Grid tables\f[] look like this:+.IP+.nf+\f[C]+:\ Sample\ grid\ table.+++---------------+---------------+--------------------++|\ Fruit\ \ \ \ \ \ \ \ \ |\ Price\ \ \ \ \ \ \ \ \ |\ Advantages\ \ \ \ \ \ \ \ \ |++===============+===============+====================++|\ Bananas\ \ \ \ \ \ \ |\ $1.34\ \ \ \ \ \ \ \ \ |\ -\ built-in\ wrapper\ |+|\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ |\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ |\ -\ bright\ color\ \ \ \ \ |++---------------+---------------+--------------------++|\ Oranges\ \ \ \ \ \ \ |\$2.10\ \ \ \ \ \ \ \ \ |\ -\ cures\ scurvy\ \ \ \ \ |+|\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ |\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ |\ -\ tasty\ \ \ \ \ \ \ \ \ \ \ \ |++---------------+---------------+--------------------++\f[]+.fi+.PP+The row of \f[C]=\f[]s separates the header from the table body, and can+be omitted for a headerless table.+The cells of grid tables may contain arbitrary block elements (multiple+paragraphs, code blocks, lists, etc.)+\&.+Alignments are not supported, nor are cells that span multiple columns+or rows.+Grid tables can be created easily using Emacs table mode.+.SH TITLE BLOCK+.PP+\f[I]Pandoc extension\f[].+.PP+If the file begins with a title block+.IP+.nf+\f[C]+%\ title+%\ author(s)\ (separated\ by\ semicolons)+%\ date+\f[]+.fi+.PP+it will be parsed as bibliographic information, not regular text.+(It will be used, for example, in the title of standalone LaTeX or HTML+output.)+ The block may contain just a title, a title and an author, or all three+elements.+If you want to include an author but no title, or a title and a date but+no author, you need a blank line:+.IP+.nf+\f[C]+%+%\ Author++%\ My\ title+%+%\ June\ 15,\ 2006+\f[]+.fi+.PP+The title may occupy multiple lines, but continuation lines must begin+with leading space, thus:+.IP+.nf+\f[C]+%\ My\ title+\ \ on\ multiple\ lines+\f[]+.fi+.PP+If a document has multiple authors, the authors may be put on separate+lines with leading space, or separated by semicolons, or both.+So, all of the following are equivalent:+.IP+.nf+\f[C]+%\ Author\ One+\ \ Author\ Two++%\ Author\ One;\ Author\ Two++%\ Author\ One;+\ \ Author\ Two+\f[]+.fi+.PP+The date must fit on one line.+.PP+All three metadata fields may contain standard inline formatting+(italics, links, footnotes, etc.)+\&.+.PP+Title blocks will always be parsed, but they will affect the output only+when the \f[C]--standalone\f[] (\f[C]-s\f[]) option is chosen.+In HTML output, titles will appear twice: once in the document head --+this is the title that will appear at the top of the window in a browser+-- and once at the beginning of the document body.+The title in the document head can have an optional prefix attached+(\f[C]--title-prefix\f[] or \f[C]-T\f[] option).+The title in the body appears as an H1 element with class "title", so it+can be suppressed or reformatted with CSS.+If a title prefix is specified with \f[C]-T\f[] and no title block+appears in the document, the title prefix will be used by itself as the+HTML title.+.PP+The man page writer extracts a title, man page section number, and other+header and footer information from the title line.+The title is assumed to be the first word on the title line, which may+optionally end with a (single-digit) section number in parentheses.+(There should be no space between the title and the parentheses.)+ Anything after this is assumed to be additional footer and header text.+A single pipe character (\f[C]|\f[]) should be used to separate the+footer text from the header text.+Thus,+.IP+.nf+\f[C]+%\ PANDOC(1)+\f[]+.fi+.PP+will yield a man page with the title \f[C]PANDOC\f[] and section 1.+.IP+.nf+\f[C]+%\ PANDOC(1)\ Pandoc\ User\ Manuals+\f[]+.fi+.PP+will also have "Pandoc User Manuals" in the footer.+.IP+.nf+\f[C]+%\ PANDOC(1)\ Pandoc\ User\ Manuals\ |\ Version\ 4.0+\f[]+.fi+.PP+will also have "Version 4.0" in the header.+.SH BACKSLASH ESCAPES+.PP+Except inside a code block or inline code, any punctuation or space+character preceded by a backslash will be treated literally, even if it+would normally indicate formatting.+Thus, for example, if one writes+.IP+.nf+\f[C]+*\\*hello\\**+\f[]+.fi+.PP+one will get+.IP+.nf+\f[C]+*hello*+\f[]+.fi+.PP+instead of+.IP+.nf+\f[C]+hello+\f[]+.fi+.PP+This rule is easier to remember than standard markdown\[aq]s rule, which+allows only the following characters to be backslash-escaped:+.IP+.nf+\f[C]+\\*_{}[]()>#+-.!+\f[]+.fi+.PP+(However, if the \f[C]--strict\f[] option is supplied, the standard+markdown rule will be used.)+.PP+A backslash-escaped space is parsed as a nonbreaking space.+It will appear in TeX output as \f[C]~\f[] and in HTML and XML as+\f[C]\\ \f[] or \f[C]\\ \f[].+.PP+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 \f[C]\\\\\f[] and in HTML as+\f[C]\f[].+This is a nice alternative to markdown\[aq]s "invisible" way of+indicating hard line breaks using two trailing spaces on a line.+.PP+Backslash escapes do not work in verbatim contexts.+.SH SMART PUNCTUATION+.PP+If the \f[C]--smart\f[] option is specified, pandoc will produce+typographically correct output, converting straight quotes to curly+quotes, \f[C]---\f[] and \f[C]--\f[] to Em-dashes, and \f[C]...\f[] to+ellipses.+Nonbreaking spaces are inserted after certain abbreviations, such as+"Mr."+.PP+Note: if your LaTeX template uses the \f[C]csquotes\f[] package, pandoc+will detect automatically this and use \f[C]\\enquote{...}\f[] for+quoted text.+.SH INLINE FORMATTING+.SS Emphasis+.PP+To \f[I]emphasize\f[] some text, surround it with \f[C]*\f[]s or+\f[C]_\f[], like this:+.IP+.nf+\f[C]+This\ text\ is\ _emphasized\ with\ underscores_,\ and\ this+is\ *emphasized\ with\ asterisks*.+\f[]+.fi+.PP+Double \f[C]*\f[] or \f[C]_\f[] produces \f[B]strong emphasis\f[]:+.IP+.nf+\f[C]+This\ is\ **strong\ emphasis**\ and\ __with\ underscores__.+\f[]+.fi+.PP+A \f[C]*\f[] or \f[C]_\f[] character surrounded by spaces, or+backslash-escaped, will not trigger emphasis:+.IP+.nf+\f[C]+This\ is\ *\ not\ emphasized\ *,\ and\ \\*neither\ is\ this\\*.+\f[]+.fi+.PP+Because \f[C]_\f[] is sometimes used inside words and identifiers,+pandoc does not interpret a \f[C]_\f[] surrounded by alphanumeric+characters as an emphasis marker.+If you want to emphasize just part of a word, use \f[C]*\f[]:+.IP+.nf+\f[C]+feas*ible*,\ not\ feas*able*.+\f[]+.fi+.SS Strikeout+.PP+\f[I]Pandoc extension\f[].+.PP+To strikeout a section of text with a horizontal line, begin and end it+with \f[C]~~\f[].+Thus, for example,+.IP+.nf+\f[C]+This\ ~~is\ deleted\ text.~~+\f[]+.fi+.SS Superscripts and subscripts+.PP+\f[I]Pandoc extension\f[].+.PP+Superscripts may be written by surrounding the superscripted text by+\f[C]^\f[] characters; subscripts may be written by surrounding the+subscripted text by \f[C]~\f[] characters.+Thus, for example,+.IP+.nf+\f[C]+H~2~O\ is\ a\ liquid.\ \ 2^10^\ is\ 1024.+\f[]+.fi+.PP+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 \f[C]~\f[] and \f[C]^\f[].)+ Thus, if you want the letter P with \[aq]a cat\[aq] in subscripts, use+\f[C]P~a\\\ cat~\f[], not \f[C]P~a\ cat~\f[].+.SS Verbatim+.PP+To make a short span of text verbatim, put it inside backticks:+.IP+.nf+\f[C]+What\ is\ the\ difference\ between\ >>=\ and\ >>?+\f[]+.fi+.PP+If the verbatim text includes a backtick, use double backticks:+.IP+.nf+\f[C]+Here\ is\ a\ literal\ backtick\ \ \ .+\f[]+.fi+.PP+(The spaces after the opening backticks and before the closing backticks+will be ignored.)+.PP+The general rule is that a verbatim span starts with a string of+consecutive backticks (optionally followed by a space) and ends with a+string of the same number of backticks (optionally preceded by a space).+.PP+Note that backslash-escapes (and other markdown constructs) do not work+in verbatim contexts:+.IP+.nf+\f[C]+This\ is\ a\ backslash\ followed\ by\ an\ asterisk:\ \\*.+\f[]+.fi+.SH MATH+.PP+\f[I]Pandoc extension\f[].+.PP+Anything between two \f[C]$\f[] characters will be treated as TeX math.+The opening \f[C]$\f[] must have a character immediately to its right,+while the closing \f[C]$\f[] must have a character immediately to its+left.+Thus, \f[C]$20,000\ and\ $30,000\f[] won\[aq]t parse as math.+If for some reason you need to enclose text in literal \f[C]$\f[]+characters, backslash-escape them and they won\[aq]t be treated as math+delimiters.+.PP+TeX math will be printed in all output formats.+How it is rendered depends on the output format:+.TP+.B Markdown, reStructuredText, LaTeX, Org-Mode, ConTeXt+It will appear verbatim between \f[C]$\f[] characters.+.RS+.RE+.TP+.B reStructuredText+It will be rendered using an interpreted text role \f[C]:math:\f[], as+described here.+.RS+.RE+.TP+.B Texinfo+It will be rendered inside a \f[C]\@math\f[] command.+.RS+.RE+.TP+.B groff man+It will be rendered verbatim without \f[C]$\f[]\[aq]s.+.RS+.RE+.TP+.B MediaWiki+It will be rendered inside \f[C][itex]\f[] tags.+.RS+.RE+.TP+.B Textile+It will be rendered inside \f[C]\f[] tags.+.RS+.RE+.TP+.B RTF, Docbook, OpenDocument, ODT+It will be rendered, if possible, using unicode characters, and will+otherwise appear verbatim.+.RS+.RE+.TP+.B HTML, Slidy, DZSlides, S5, EPUB+The way math is rendered in HTML will depend on the command-line options+selected:+.RS+.IP "1." 3+The default is to render TeX math as far as possible using unicode+characters, as with RTF, Docbook, and OpenDocument output.+Formulas are put inside a \f[C]span\f[] with \f[C]class="math"\f[], so+that they may be styled differently from the surrounding text if needed.+.IP "2." 3+If the \f[C]--latexmathml\f[] option is used, TeX math will be displayed+between $or$$characters and put in \f[C]\f[] tags with class+\f[C]LaTeX\f[].+The LaTeXMathML script will be used to render it as formulas.+(This trick does not work in all browsers, but it works in Firefox.+In browsers that do not support LaTeXMathML, TeX math will appear+verbatim between$ characters.)+.IP "3." 3+If the \f[C]--jsmath\f[] option is used, TeX math will be put inside+\f[C]\f[] tags (for inline math) or \f[C]