converts files from one markup format into another.
| MANUAL.txt (pandoc-2.17.1.1) | : | MANUAL.txt (pandoc-2.18) |
|---|
| --- | | --- |
| title: Pandoc User's Guide | | title: Pandoc User's Guide |
| author: John MacFarlane | | author: John MacFarlane |
|
| date: January 30, 2022 | | date: April 4, 2022 |
| --- | | --- |
| | |
| # Synopsis | | # Synopsis |
| | |
| `pandoc` [*options*] [*input-file*]... | | `pandoc` [*options*] [*input-file*]... |
| | |
| # Description | | # Description |
| | |
| Pandoc is a [Haskell] library for converting from one markup format to | | Pandoc is a [Haskell] library for converting from one markup format to |
| another, and a command-line tool that uses this library. | | another, and a command-line tool that uses this library. |
| | |
| skipping to change at line 236 | | skipping to change at line 236 |
|---|
| - `bibtex` ([BibTeX] bibliography) | | - `bibtex` ([BibTeX] bibliography) |
| - `biblatex` ([BibLaTeX] bibliography) | | - `biblatex` ([BibLaTeX] bibliography) |
| - `commonmark` ([CommonMark] Markdown) | | - `commonmark` ([CommonMark] Markdown) |
| - `commonmark_x` ([CommonMark] Markdown with extensions) | | - `commonmark_x` ([CommonMark] Markdown with extensions) |
| - `creole` ([Creole 1.0]) | | - `creole` ([Creole 1.0]) |
| - `csljson` ([CSL JSON] bibliography) | | - `csljson` ([CSL JSON] bibliography) |
| - `csv` ([CSV] table) | | - `csv` ([CSV] table) |
| - `docbook` ([DocBook]) | | - `docbook` ([DocBook]) |
| - `docx` ([Word docx]) | | - `docx` ([Word docx]) |
| - `dokuwiki` ([DokuWiki markup]) | | - `dokuwiki` ([DokuWiki markup]) |
|
| | - `endnotexml` ([EndNote XML bibliography]) |
| - `epub` ([EPUB]) | | - `epub` ([EPUB]) |
| - `fb2` ([FictionBook2] e-book) | | - `fb2` ([FictionBook2] e-book) |
| - `gfm` ([GitHub-Flavored Markdown]), | | - `gfm` ([GitHub-Flavored Markdown]), |
| or the deprecated and less accurate `markdown_github`; | | or the deprecated and less accurate `markdown_github`; |
| use [`markdown_github`](#markdown-variants) only | | use [`markdown_github`](#markdown-variants) only |
| if you need extensions not supported in [`gfm`](#markdown-variants). | | if you need extensions not supported in [`gfm`](#markdown-variants). |
| - `haddock` ([Haddock markup]) | | - `haddock` ([Haddock markup]) |
| - `html` ([HTML]) | | - `html` ([HTML]) |
| - `ipynb` ([Jupyter notebook]) | | - `ipynb` ([Jupyter notebook]) |
| - `jats` ([JATS] XML) | | - `jats` ([JATS] XML) |
| | |
| skipping to change at line 260 | | skipping to change at line 261 |
|---|
| - `markdown_mmd` ([MultiMarkdown]) | | - `markdown_mmd` ([MultiMarkdown]) |
| - `markdown_phpextra` ([PHP Markdown Extra]) | | - `markdown_phpextra` ([PHP Markdown Extra]) |
| - `markdown_strict` (original unextended [Markdown]) | | - `markdown_strict` (original unextended [Markdown]) |
| - `mediawiki` ([MediaWiki markup]) | | - `mediawiki` ([MediaWiki markup]) |
| - `man` ([roff man]) | | - `man` ([roff man]) |
| - `muse` ([Muse]) | | - `muse` ([Muse]) |
| - `native` (native Haskell) | | - `native` (native Haskell) |
| - `odt` ([ODT]) | | - `odt` ([ODT]) |
| - `opml` ([OPML]) | | - `opml` ([OPML]) |
| - `org` ([Emacs Org mode]) | | - `org` ([Emacs Org mode]) |
|
| | - `ris` ([RIS] bibliography) |
| - `rtf` ([Rich Text Format]) | | - `rtf` ([Rich Text Format]) |
| - `rst` ([reStructuredText]) | | - `rst` ([reStructuredText]) |
| - `t2t` ([txt2tags]) | | - `t2t` ([txt2tags]) |
| - `textile` ([Textile]) | | - `textile` ([Textile]) |
| - `tikiwiki` ([TikiWiki markup]) | | - `tikiwiki` ([TikiWiki markup]) |
| - `twiki` ([TWiki markup]) | | - `twiki` ([TWiki markup]) |
| - `vimwiki` ([Vimwiki]) | | - `vimwiki` ([Vimwiki]) |
| - the path of a custom Lua reader, see [Custom readers and writers] below | | - the path of a custom Lua reader, see [Custom readers and writers] below |
| ::: | | ::: |
| | |
| | |
| skipping to change at line 487 | | skipping to change at line 489 |
|---|
| [XWiki markup]: https://www.xwiki.org/xwiki/bin/view/Documentation/UserGuide/Fea
tures/XWikiSyntax/ | | [XWiki markup]: https://www.xwiki.org/xwiki/bin/view/Documentation/UserGuide/Fea
tures/XWikiSyntax/ |
| [TWiki markup]: https://twiki.org/cgi-bin/view/TWiki/TextFormattingRules | | [TWiki markup]: https://twiki.org/cgi-bin/view/TWiki/TextFormattingRules |
| [TikiWiki markup]: https://doc.tiki.org/Wiki-Syntax-Text#The_Markup_Language_Wik
i-Syntax | | [TikiWiki markup]: https://doc.tiki.org/Wiki-Syntax-Text#The_Markup_Language_Wik
i-Syntax |
| [Haddock markup]: https://www.haskell.org/haddock/doc/html/ch03s08.html | | [Haddock markup]: https://www.haskell.org/haddock/doc/html/ch03s08.html |
| [Creole 1.0]: http://www.wikicreole.org/wiki/Creole1.0 | | [Creole 1.0]: http://www.wikicreole.org/wiki/Creole1.0 |
| [CSV]: https://tools.ietf.org/html/rfc4180 | | [CSV]: https://tools.ietf.org/html/rfc4180 |
| [roff man]: https://man.cx/groff_man(7) | | [roff man]: https://man.cx/groff_man(7) |
| [roff ms]: https://man.cx/groff_ms(7) | | [roff ms]: https://man.cx/groff_ms(7) |
| [Haskell]: https://www.haskell.org | | [Haskell]: https://www.haskell.org |
| [GNU Texinfo]: https://www.gnu.org/software/texinfo/ | | [GNU Texinfo]: https://www.gnu.org/software/texinfo/ |
|
| | [RIS]: https://en.wikipedia.org/wiki/RIS_(file_format) |
| [Emacs Org mode]: https://orgmode.org | | [Emacs Org mode]: https://orgmode.org |
| [AsciiDoc]: https://www.methods.co.nz/asciidoc/ | | [AsciiDoc]: https://www.methods.co.nz/asciidoc/ |
| [AsciiDoctor]: https://asciidoctor.org/ | | [AsciiDoctor]: https://asciidoctor.org/ |
| [DZSlides]: https://paulrouget.com/dzslides/ | | [DZSlides]: https://paulrouget.com/dzslides/ |
| [Word docx]: https://en.wikipedia.org/wiki/Office_Open_XML | | [Word docx]: https://en.wikipedia.org/wiki/Office_Open_XML |
| [PDF]: https://www.adobe.com/pdf/ | | [PDF]: https://www.adobe.com/pdf/ |
| [reveal.js]: https://revealjs.com/ | | [reveal.js]: https://revealjs.com/ |
| [FictionBook2]: http://www.fictionbook.org/index.php/Eng:XML_Schema_Fictionbook_
2.1 | | [FictionBook2]: http://www.fictionbook.org/index.php/Eng:XML_Schema_Fictionbook_
2.1 |
| [Jupyter notebook]: https://nbformat.readthedocs.io/en/latest/ | | [Jupyter notebook]: https://nbformat.readthedocs.io/en/latest/ |
| [InDesign ICML]: https://wwwimages.adobe.com/www.adobe.com/content/dam/acom/en/d
evnet/indesign/sdk/cs6/idml/idml-cookbook.pdf | | [InDesign ICML]: https://wwwimages.adobe.com/www.adobe.com/content/dam/acom/en/d
evnet/indesign/sdk/cs6/idml/idml-cookbook.pdf |
| [TEI Simple]: https://github.com/TEIC/TEI-Simple | | [TEI Simple]: https://github.com/TEIC/TEI-Simple |
| [Muse]: https://amusewiki.org/library/manual | | [Muse]: https://amusewiki.org/library/manual |
| [PowerPoint]: https://en.wikipedia.org/wiki/Microsoft_PowerPoint | | [PowerPoint]: https://en.wikipedia.org/wiki/Microsoft_PowerPoint |
| [Vimwiki]: https://vimwiki.github.io | | [Vimwiki]: https://vimwiki.github.io |
| [CSL JSON]: https://citeproc-js.readthedocs.io/en/latest/csl-json/markup.html | | [CSL JSON]: https://citeproc-js.readthedocs.io/en/latest/csl-json/markup.html |
| [BibTeX]: https://ctan.org/pkg/bibtex | | [BibTeX]: https://ctan.org/pkg/bibtex |
| [BibLaTeX]: https://ctan.org/pkg/biblatex | | [BibLaTeX]: https://ctan.org/pkg/biblatex |
| [Markua]: https://leanpub.com/markua/read | | [Markua]: https://leanpub.com/markua/read |
|
| | [EndNote XML bibliography]: https://support.clarivate.com/Endnote/s/article/EndN
ote-XML-Document-Type-Definition |
| | |
| ## Reader options {.options} | | ## Reader options {.options} |
| | |
| `--shift-heading-level-by=`*NUMBER* | | `--shift-heading-level-by=`*NUMBER* |
| | |
| : Shift heading levels by a positive or negative integer. | | : Shift heading levels by a positive or negative integer. |
| For example, with `--shift-heading-level-by=-1`, level 2 | | For example, with `--shift-heading-level-by=-1`, level 2 |
| headings become level 1 headings, and level 3 headings | | headings become level 1 headings, and level 3 headings |
| become level 2 headings. Headings cannot have a level | | become level 2 headings. Headings cannot have a level |
| less than 1, so a heading that would be shifted below level 1 | | less than 1, so a heading that would be shifted below level 1 |
| | |
| skipping to change at line 638 | | skipping to change at line 642 |
|---|
| `--variable`, `--metadata` causes template variables to be set. | | `--variable`, `--metadata` causes template variables to be set. |
| But unlike `--variable`, `--metadata` affects the metadata of the | | But unlike `--variable`, `--metadata` affects the metadata of the |
| underlying document (which is accessible from filters and may be | | underlying document (which is accessible from filters and may be |
| printed in some output formats) and metadata values will be escaped | | printed in some output formats) and metadata values will be escaped |
| when inserted into the template. | | when inserted into the template. |
| | |
| `--metadata-file=`*FILE* | | `--metadata-file=`*FILE* |
| | |
| : Read metadata from the supplied YAML (or JSON) file. This | | : Read metadata from the supplied YAML (or JSON) file. This |
| option can be used with every input format, but string scalars | | option can be used with every input format, but string scalars |
|
| in the YAML file will always be parsed as Markdown. Generally, | | in the YAML file will always be parsed as Markdown. (If the |
| the input will be handled the same as in [YAML metadata | | input format is Markdown or a Markdown variant, then the |
| blocks][Extension: `yaml_metadata_block`]. This option can be | | same variant will be used to parse the metadata file; |
| used repeatedly to include multiple metadata files; values in | | if it is a non-Markdown format, pandoc's default Markdown |
| | extensions will be used.) This option can be used |
| | repeatedly to include multiple metadata files; values in |
| files specified later on the command line will be preferred | | files specified later on the command line will be preferred |
| over those specified in earlier files. Metadata values | | over those specified in earlier files. Metadata values |
| specified inside the document, or by using `-M`, overwrite | | specified inside the document, or by using `-M`, overwrite |
| values specified with this option. The file will be searched | | values specified with this option. The file will be searched |
| for first in the working directory, and then in the `metadata` | | for first in the working directory, and then in the `metadata` |
| subdirectory of the user data directory (see `--data-dir`). | | subdirectory of the user data directory (see `--data-dir`). |
| | |
| `-p`, `--preserve-tabs` | | `-p`, `--preserve-tabs` |
| | |
| : Preserve tabs instead of converting them to spaces. (By default, pandoc | | : Preserve tabs instead of converting them to spaces. (By default, pandoc |
| | |
| skipping to change at line 951 | | skipping to change at line 957 |
|---|
| access to be displayed properly by a browser. This option works only with | | access to be displayed properly by a browser. This option works only with |
| HTML output formats, including `html4`, `html5`, `html+lhs`, `html5+lhs`, | | HTML output formats, including `html4`, `html5`, `html+lhs`, `html5+lhs`, |
| `s5`, `slidy`, `slideous`, `dzslides`, and `revealjs`. Scripts, images, | | `s5`, `slidy`, `slideous`, `dzslides`, and `revealjs`. Scripts, images, |
| and stylesheets at absolute URLs will be downloaded; those at relative | | and stylesheets at absolute URLs will be downloaded; those at relative |
| URLs will be sought relative to the working directory (if the first source | | URLs will be sought relative to the working directory (if the first source |
| file is local) or relative to the base URL (if the first source | | file is local) or relative to the base URL (if the first source |
| file is remote). Elements with the attribute | | file is remote). Elements with the attribute |
| `data-external="1"` will be left alone; the documents they | | `data-external="1"` will be left alone; the documents they |
| link to will not be incorporated in the document. | | link to will not be incorporated in the document. |
| Limitation: resources that are loaded dynamically through | | Limitation: resources that are loaded dynamically through |
|
| JavaScript cannot be incorporated; as a result, | | JavaScript cannot be incorporated; as a result, some |
| `--self-contained` does not work with `--mathjax`, and some | | |
| advanced features (e.g. zoom or speaker notes) may not work | | advanced features (e.g. zoom or speaker notes) may not work |
| in an offline "self-contained" `reveal.js` slide show. | | in an offline "self-contained" `reveal.js` slide show. |
| | |
| `--html-q-tags` | | `--html-q-tags` |
| | |
| : Use `<q>` tags for quotes in HTML. (This option only has an | | : Use `<q>` tags for quotes in HTML. (This option only has an |
| effect if the `smart` extension is enabled for the input | | effect if the `smart` extension is enabled for the input |
| format used.) | | format used.) |
| | |
| `--ascii` | | `--ascii` |
| | |
| skipping to change at line 3161 | | skipping to change at line 3166 |
|---|
| | |
| #### Extension: `smart` #### | | #### Extension: `smart` #### |
| | |
| Interpret straight quotes as curly quotes, `---` as em-dashes, | | Interpret straight quotes as curly quotes, `---` as em-dashes, |
| `--` as en-dashes, and `...` as ellipses. Nonbreaking spaces are | | `--` as en-dashes, and `...` as ellipses. Nonbreaking spaces are |
| inserted after certain abbreviations, such as "Mr." | | inserted after certain abbreviations, such as "Mr." |
| | |
| This extension can be enabled/disabled for the following formats: | | This extension can be enabled/disabled for the following formats: |
| | |
| input formats | | input formats |
|
| : `markdown`, `commonmark`, `latex`, `mediawiki`, `org`, `rst`, `twiki` | | : `markdown`, `commonmark`, `latex`, `mediawiki`, `org`, `rst`, `twiki`, |
| | `html` |
| | |
| output formats | | output formats |
| : `markdown`, `latex`, `context`, `rst` | | : `markdown`, `latex`, `context`, `rst` |
| | |
| enabled by default in | | enabled by default in |
| : `markdown`, `latex`, `context` (both input and output) | | : `markdown`, `latex`, `context` (both input and output) |
| | |
| Note: If you are *writing* Markdown, then the `smart` extension | | Note: If you are *writing* Markdown, then the `smart` extension |
| has the reverse effect: what would have been curly quotes comes | | has the reverse effect: what would have been curly quotes comes |
| out straight. | | out straight. |
| | |
| skipping to change at line 3464 | | skipping to change at line 3470 |
|---|
| #### Extension: `raw_markdown` #### | | #### Extension: `raw_markdown` #### |
| | |
| In the `ipynb` input format, this causes Markdown cells | | In the `ipynb` input format, this causes Markdown cells |
| to be included as raw Markdown blocks (allowing lossless | | to be included as raw Markdown blocks (allowing lossless |
| round-tripping) rather than being parsed. Use this only | | round-tripping) rather than being parsed. Use this only |
| when you are targeting `ipynb` or a markdown-based | | when you are targeting `ipynb` or a markdown-based |
| output format. | | output format. |
| | |
| #### Extension: `citations` {#org-citations} | | #### Extension: `citations` {#org-citations} |
| | |
|
| Some aspects of [Pandoc's Markdown citation syntax](#citations) | | When the `citations` extension is enabled in `org`, |
| are also accepted in `org` input. | | org-cite and org-ref style citations will be parsed as |
| | native pandoc citations. |
| | |
| | [org-cite]: https://orgmode.org/manual/Citations.html |
| | [org-ref]: https://github.com/jkitchin/org-ref |
| | |
| | When `citations` is enabled in `docx`, citations inserted |
| | by Zotero or Mendeley or EndNote plugins will be parsed as native |
| | pandoc citations. (Otherwise, the formatted citations generated |
| | by the bibliographic software will be parsed as regular text.) |
| | |
| #### Extension: `fancy_lists` {#org-fancy-lists} | | #### Extension: `fancy_lists` {#org-fancy-lists} |
| | |
| Some aspects of [Pandoc's Markdown fancy lists](#extension-fancy_lists) are also | | Some aspects of [Pandoc's Markdown fancy lists](#extension-fancy_lists) are also |
| accepted in `org` input, mimicking the option `org-list-allow-alphabetical` in | | accepted in `org` input, mimicking the option `org-list-allow-alphabetical` in |
| Emacs. As in Org Mode, enabling this extension allows lowercase and uppercase | | Emacs. As in Org Mode, enabling this extension allows lowercase and uppercase |
| alphabetical markers for ordered lists to be parsed in addition to arabic ones. | | alphabetical markers for ordered lists to be parsed in addition to arabic ones. |
| Note that for Org, this does not include roman numerals or the `#` placeholder | | Note that for Org, this does not include roman numerals or the `#` placeholder |
| that are enabled by the extension in Pandoc's Markdown. | | that are enabled by the extension in Pandoc's Markdown. |
| | |
| | |
| skipping to change at line 4773 | | skipping to change at line 4788 |
|---|
| Anything between two `$` characters will be treated as TeX math. The | | Anything between two `$` characters will be treated as TeX math. The |
| opening `$` must have a non-space character immediately to its right, | | opening `$` must have a non-space character immediately to its right, |
| while the closing `$` must have a non-space character immediately to its | | while the closing `$` must have a non-space character immediately to its |
| left, and must not be followed immediately by a digit. Thus, | | left, and must not be followed immediately by a digit. 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. |
| | |
| For display math, use `$$` delimiters. (In this case, the delimiters | | For display math, use `$$` delimiters. (In this case, the delimiters |
| may be separated from the formula by whitespace. However, there can be | | may be separated from the formula by whitespace. However, there can be |
|
| no blank lines betwen the opening and closing `$$` delimiters.) | | no blank lines between the opening and closing `$$` delimiters.) |
| | |
| TeX math will be printed in all output formats. How it is rendered | | TeX math will be printed in all output formats. How it is rendered |
| depends on the output format: | | depends on the output format: |
| | |
| LaTeX | | LaTeX |
| ~ It will appear verbatim surrounded by `\(...\)` (for inline | | ~ It will appear verbatim surrounded by `\(...\)` (for inline |
| math) or `\[...\]` (for display math). | | math) or `\[...\]` (for display math). |
| | |
| Markdown, Emacs Org mode, ConTeXt, ZimWiki | | Markdown, Emacs Org mode, ConTeXt, ZimWiki |
| ~ It will appear verbatim surrounded by `$...$` (for inline | | ~ It will appear verbatim surrounded by `$...$` (for inline |
| | |
| skipping to change at line 5705 | | skipping to change at line 5720 |
|---|
| multiple bibliography files, you can supply multiple | | multiple bibliography files, you can supply multiple |
| `--bibliography` arguments or set `bibliography` metadata field | | `--bibliography` arguments or set `bibliography` metadata field |
| to YAML array. A bibliography may have any of these formats: | | to YAML array. A bibliography may have any of these formats: |
| | |
| Format File extension | | Format File extension |
| ------------ -------------- | | ------------ -------------- |
| BibLaTeX .bib | | BibLaTeX .bib |
| BibTeX .bibtex | | BibTeX .bibtex |
| CSL JSON .json | | CSL JSON .json |
| CSL YAML .yaml | | CSL YAML .yaml |
|
| | RIS .ris |
| | |
| Note that `.bib` can be used with both BibTeX and BibLaTeX files; | | Note that `.bib` can be used with both BibTeX and BibLaTeX files; |
| use the extension `.bibtex` to force interpretation as BibTeX. | | use the extension `.bibtex` to force interpretation as BibTeX. |
| | |
| In BibTeX and BibLaTeX databases, pandoc parses LaTeX markup | | In BibTeX and BibLaTeX databases, pandoc parses LaTeX markup |
| inside fields such as `title`; in CSL YAML databases, pandoc | | inside fields such as `title`; in CSL YAML databases, pandoc |
| Markdown; and in CSL JSON databases, an [HTML-like markup][CSL | | Markdown; and in CSL JSON databases, an [HTML-like markup][CSL |
| markup specs]: | | markup specs]: |
| | |
| `<i>...</i>` | | `<i>...</i>` |
| | |
| skipping to change at line 5942 | | skipping to change at line 5958 |
|---|
| or at the end of your document: | | or at the end of your document: |
| | |
| last paragraph... | | last paragraph... |
| | |
| # References | | # References |
| | |
| The bibliography will be inserted after this heading. Note that | | The bibliography will be inserted after this heading. Note that |
| the `unnumbered` class will be added to this heading, so that the | | the `unnumbered` class will be added to this heading, so that the |
| section will not be numbered. | | section will not be numbered. |
| | |
|
| | If you want to put the bibliography into a variable in your |
| | template, one way to do that is to put the div with id `refs` |
| | into a metadata field, e.g. |
| | |
| | --- |
| | refs: | |
| | ::: {#refs} |
| | ::: |
| | ... |
| | |
| | You can then put the variable `$refs$` into your template where |
| | you want the bibliography to be placed. |
| | |
| ## Including uncited items in the bibliography | | ## Including uncited items in the bibliography |
| | |
| If you want to include items in the bibliography without actually | | If you want to include items in the bibliography without actually |
| citing them in the body text, you can define a dummy `nocite` metadata | | citing them in the body text, you can define a dummy `nocite` metadata |
| field and put the citations there: | | field and put the citations there: |
| | |
| --- | | --- |
| nocite: | | | nocite: | |
| @item1, @item2 | | @item1, @item2 |
| ... | | ... |
| | |
| skipping to change at line 6223 | | skipping to change at line 6252 |
|---|
| will depart from the document default (that is, it will display | | will depart from the document default (that is, it will display |
| incrementally without the `-i` option and all at once with the `-i` | | incrementally without the `-i` option and all at once with the `-i` |
| option): | | option): |
| | |
| > - Eat spaghetti | | > - Eat spaghetti |
| > - Drink wine | | > - Drink wine |
| | |
| Both methods allow incremental and nonincremental lists to be mixed | | Both methods allow incremental and nonincremental lists to be mixed |
| in a single document. | | in a single document. |
| | |
|
| | If you want to include a block-quoted list, you can work around |
| | this behavior by putting the list inside a fenced div, so that |
| | it is not the direct child of the block quote: |
| | |
| | > ::: wrapper |
| | > - a |
| | > - list in a quote |
| | > ::: |
| | |
| ## Inserting pauses | | ## Inserting pauses |
| | |
| You can add "pauses" within a slide by including a paragraph containing | | You can add "pauses" within a slide by including a paragraph containing |
| three dots, separated by spaces: | | three dots, separated by spaces: |
| | |
| # Slide with a pause | | # Slide with a pause |
| | |
| content before the pause | | content before the pause |
| | |
| . . . | | . . . |
| | |
| skipping to change at line 6956 | | skipping to change at line 6994 |
|---|
| be taken from it instead of the current time. | | be taken from it instead of the current time. |
| `SOURCE_DATE_EPOCH` should contain an integer unix timestamp | | `SOURCE_DATE_EPOCH` should contain an integer unix timestamp |
| (specifying the number of second since midnight UTC January 1, 1970). | | (specifying the number of second since midnight UTC January 1, 1970). |
| | |
| Some document formats also include a unique identifier. For | | Some document formats also include a unique identifier. For |
| EPUB, this can be set explicitly by setting the `identifier` | | EPUB, this can be set explicitly by setting the `identifier` |
| metadata field (see [EPUB Metadata], above). | | metadata field (see [EPUB Metadata], above). |
| | |
| # A note on security | | # A note on security |
| | |
|
| If you use pandoc to convert user-contributed content in a web | | |
| application, here are some things to keep in mind: | | |
| | | |
| 1. Although pandoc itself will not create or modify any files other | | 1. Although pandoc itself will not create or modify any files other |
| than those you explicitly ask it create (with the exception | | than those you explicitly ask it create (with the exception |
| of temporary files used in producing PDFs), a filter or custom | | of temporary files used in producing PDFs), a filter or custom |
| writer could in principle do anything on your file system. Please | | writer could in principle do anything on your file system. Please |
| audit filters and custom writers very carefully before using them. | | audit filters and custom writers very carefully before using them. |
| | |
| 2. Several input formats (including HTML, Org, and RST) support `include` | | 2. Several input formats (including HTML, Org, and RST) support `include` |
| directives that allow the contents of a file to be included in the | | directives that allow the contents of a file to be included in the |
| output. An untrusted attacker could use these to view the contents of | | output. An untrusted attacker could use these to view the contents of |
| files on the file system. (Using the `--sandbox` option can | | files on the file system. (Using the `--sandbox` option can |
| | |
| skipping to change at line 6984 | | skipping to change at line 7019 |
|---|
| could exploit this to view the contents of non-image files on the | | could exploit this to view the contents of non-image files on the |
| file system. (Using the `--sandbox` option can protect | | file system. (Using the `--sandbox` option can protect |
| against this threat, but will also prevent including images in | | against this threat, but will also prevent including images in |
| these formats.) | | these formats.) |
| | |
| 4. If your application uses pandoc as a Haskell library (rather than | | 4. If your application uses pandoc as a Haskell library (rather than |
| shelling out to the executable), it is possible to use it in a mode | | shelling out to the executable), it is possible to use it in a mode |
| that fully isolates pandoc from your file system, by running the | | that fully isolates pandoc from your file system, by running the |
| pandoc operations in the `PandocPure` monad. See the document | | pandoc operations in the `PandocPure` monad. See the document |
| [Using the pandoc API](https://pandoc.org/using-the-pandoc-api.html) | | [Using the pandoc API](https://pandoc.org/using-the-pandoc-api.html) |
|
| for more details. | | for more details. (This corresponds to the use of the `--sandbox` |
| | option on the command line.) |
| | |
| 5. Pandoc's parsers can exhibit pathological performance on some | | 5. Pandoc's parsers can exhibit pathological performance on some |
| corner cases. It is wise to put any pandoc operations under | | corner cases. It is wise to put any pandoc operations under |
| a timeout, to avoid DOS attacks that exploit these issues. | | a timeout, to avoid DOS attacks that exploit these issues. |
| If you are using the pandoc executable, you can add the | | If you are using the pandoc executable, you can add the |
| command line options `+RTS -M512M -RTS` (for example) to limit | | command line options `+RTS -M512M -RTS` (for example) to limit |
| the heap size to 512MB. Note that the `commonmark` parser | | the heap size to 512MB. Note that the `commonmark` parser |
| (including `commonmark_x` and `gfm`) is much less vulnerable | | (including `commonmark_x` and `gfm`) is much less vulnerable |
| to pathological performance than the `markdown` parser, so | | to pathological performance than the `markdown` parser, so |
| it is a better choice when processing untrusted input. | | it is a better choice when processing untrusted input. |
| | |
| 6. The HTML generated by pandoc is not guaranteed to be safe. | | 6. The HTML generated by pandoc is not guaranteed to be safe. |
| If `raw_html` is enabled for the Markdown input, users can | | If `raw_html` is enabled for the Markdown input, users can |
| inject arbitrary HTML. Even if `raw_html` is disabled, | | inject arbitrary HTML. Even if `raw_html` is disabled, |
| users can include dangerous content in URLs and attributes. | | users can include dangerous content in URLs and attributes. |
|
| To be safe, you should run all the generated HTML through | | To be safe, you should run all HTML generated from untrusted |
| an HTML sanitizer. | | user input through an HTML sanitizer. |
| | |
| # Authors | | # Authors |
| | |
| Copyright 2006--2022 John MacFarlane (jgm@berkeley.edu). Released | | Copyright 2006--2022 John MacFarlane (jgm@berkeley.edu). Released |
| under the [GPL], version 2 or greater. This software carries no | | under the [GPL], version 2 or greater. This software carries no |
| warranty of any kind. (See COPYRIGHT for full copyright and | | warranty of any kind. (See COPYRIGHT for full copyright and |
| warranty notices.) For a full list of contributors, see the file | | warranty notices.) For a full list of contributors, see the file |
| AUTHORS.md in the pandoc source code. | | AUTHORS.md in the pandoc source code. |
| | |
| [GPL]: https://www.gnu.org/copyleft/gpl.html "GNU General Public License" | | [GPL]: https://www.gnu.org/copyleft/gpl.html "GNU General Public License" |
| | | |
| End of changes. 16 change blocks. |
|---|
| 17 lines changed or deleted | | 53 lines changed or added |
|---|
"Fossies" - the Fresh Open Source Software Archive 