## File: README.md # Pandoc [![github release](https://img.shields.io/github/release/jgm/pandoc.svg?label=current+release)](https://github.com/jgm/pandoc/releases) [![hackage release](https://img.shields.io/hackage/v/pandoc.svg?label=hackage)](https://hackage.haskell.org/package/pandoc) [](https://formulae.brew.sh/formula/pandoc) [![stackage LTS package](https://stackage.org/package/pandoc/badge/lts)](https://www.stackage.org/lts/package/pandoc) [![CI tests](https://github.com/jgm/pandoc/workflows/CI%20tests/badge.svg)](https://github.com/jgm/pandoc/actions) [](https://www.gnu.org/licenses/gpl.html) [![pandoc-discuss on google groups](https://img.shields.io/badge/pandoc-discuss-red.svg?style=social)](https://groups.google.com/forum/#!forum/pandoc-discuss) ## The universal markup converter Pandoc is a [Haskell](https://haskell.org) library for converting from one markup format to another, and a command-line tool that uses this library. It can convert *from* - `asciidoc` ([AsciiDoc](https://asciidoc.org/) markup) - `bibtex` ([BibTeX](https://ctan.org/pkg/bibtex) bibliography) - `biblatex` ([BibLaTeX](https://ctan.org/pkg/biblatex) bibliography) - `bits` ([BITS](https://jats.nlm.nih.gov/extensions/bits/) XML, alias for `jats`) - `commonmark` ([CommonMark](https://commonmark.org) Markdown) - `commonmark_x` ([CommonMark](https://commonmark.org) Markdown with extensions) - `creole` ([Creole 1.0](http://www.wikicreole.org/wiki/Creole1.0)) - `csljson` ([CSL JSON](https://citeproc-js.readthedocs.io/en/latest/csl-json/markup.html) bibliography) - `csv` ([CSV](https://tools.ietf.org/html/rfc4180) table) - `tsv` ([TSV](https://www.iana.org/assignments/media-types/text/tab-separated-values) table) - `djot` ([Djot markup](https://djot.net)) - `docbook` ([DocBook](https://docbook.org)) - `docx` ([Word docx](https://en.wikipedia.org/wiki/Office_Open_XML)) - `dokuwiki` ([DokuWiki markup](https://www.dokuwiki.org/dokuwiki)) - `endnotexml` ([EndNote XML bibliography](https://support.clarivate.com/Endnote/s/article/EndNote-XML-Document-Type-Definition)) - `epub` ([EPUB](http://idpf.org/epub)) - `fb2` ([FictionBook2](http://www.fictionbook.org/index.php/Eng:XML_Schema_Fictionbook_2.1) e-book) - `gfm` ([GitHub-Flavored Markdown](https://help.github.com/articles/github-flavored-markdown/)), or the deprecated and less accurate `markdown_github`; use [`markdown_github`](https://pandoc.org/MANUAL.html#markdown-variants) only if you need extensions not supported in [`gfm`](https://pandoc.org/MANUAL.html#markdown-variants). - `haddock` ([Haddock markup](https://www.haskell.org/haddock/doc/html/ch03s08.html)) - `html` ([HTML](https://www.w3.org/html/)) - `ipynb` ([Jupyter notebook](https://nbformat.readthedocs.io/en/latest/)) - `jats` ([JATS](https://jats.nlm.nih.gov) XML) - `jira` ([Jira](https://jira.atlassian.com/secure/WikiRendererHelpAction.jspa?section=all)/Confluence wiki markup) - `json` (JSON version of native AST) - `latex` ([LaTeX](https://www.latex-project.org/)) - `markdown` ([Pandoc’s Markdown](https://pandoc.org/MANUAL.html#pandocs-markdown)) - `markdown_mmd` ([MultiMarkdown](https://fletcherpenney.net/multimarkdown/)) - `markdown_phpextra` ([PHP Markdown Extra](https://michelf.ca/projects/php-markdown/extra/)) - `markdown_strict` (original unextended [Markdown](https://daringfireball.net/projects/markdown/)) - `mediawiki` ([MediaWiki markup](https://www.mediawiki.org/wiki/Help:Formatting)) - `man` ([roff man](https://man.cx/groff_man(7))) - `mdoc` ([mdoc](https://mandoc.bsd.lv/man/mdoc.7.html) manual page markup) - `muse` ([Muse](https://amusewiki.org/library/manual)) - `native` (native Haskell) - `odt` ([OpenDocument text document](https://en.wikipedia.org/wiki/OpenDocument)) - `opml` ([OPML](https://opml.org/spec2.opml)) - `org` ([Emacs Org mode](https://orgmode.org)) - `pod` (Perl’s [Plain Old Documentation](https://perldoc.perl.org/perlpod)) - `pptx` ([PowerPoint](https://en.wikipedia.org/wiki/Microsoft_PowerPoint)) - `ris` ([RIS](https://en.wikipedia.org/wiki/RIS_(file_format)) bibliography) - `rtf` ([Rich Text Format](https://en.wikipedia.org/wiki/Rich_Text_Format)) - `rst` ([reStructuredText](https://docutils.sourceforge.io/docs/ref/rst/introduction.html)) - `t2t` ([txt2tags](https://txt2tags.org)) - `textile` ([Textile](https://textile-lang.com)) - `tikiwiki` ([TikiWiki markup](https://doc.tiki.org/Wiki-Syntax-Text#The_Markup_Language_Wiki-Syntax)) - `twiki` ([TWiki markup](https://twiki.org/cgi-bin/view/TWiki/TextFormattingRules)) - `typst` ([typst](https://typst.app)) - `vimwiki` ([Vimwiki](https://vimwiki.github.io)) - `xlsx` ([Excel spreadsheet](https://en.wikipedia.org/wiki/Microsoft_Excel#File_formats)) - `xml` (XML version of native AST) - the path of a custom Lua reader, see [Custom readers and writers](https://pandoc.org/MANUAL.html#custom-readers-and-writers) below It can convert *to* - `ansi` (text with [ANSI escape codes](https://en.wikipedia.org/wiki/ANSI_escape_code), for terminal viewing) - `asciidoc` (modern [AsciiDoc](https://asciidoc.org/) as interpreted by [Asciidoctor](https://asciidoctor.org/)) - `asciidoc_legacy` ([AsciiDoc](https://asciidoc.org/) as interpreted by [`asciidoc-py`](https://github.com/asciidoc-py/asciidoc-py)). - `asciidoctor` (deprecated synonym for `asciidoc`) - `bbcode` [BBCode](https://www.bbcode.org/reference.php) - `bbcode_fluxbb` [BBCode (FluxBB)](https://web.archive.org/web/20210623155046/https://fluxbb.org/forums/help.php#bbcode) - `bbcode_phpbb` [BBCode (phpBB)](https://www.phpbb.com/community/help/bbcode) - `bbcode_steam` [BBCode (Steam)](https://steamcommunity.com/comment/ForumTopic/formattinghelp) - `bbcode_hubzilla` [BBCode (Hubzilla)](https://hubzilla.org/help/member/bbcode) - `bbcode_xenforo` [BBCode (xenForo)](https://www.xenfocus.com/community/help/bb-codes/) - `beamer` ([LaTeX beamer](https://ctan.org/pkg/beamer) slide show) - `bibtex` ([BibTeX](https://ctan.org/pkg/bibtex) bibliography) - `biblatex` ([BibLaTeX](https://ctan.org/pkg/biblatex) bibliography) - `chunkedhtml` (zip archive of multiple linked HTML files) - `commonmark` ([CommonMark](https://commonmark.org) Markdown) - `commonmark_x` ([CommonMark](https://commonmark.org) Markdown with extensions) - `context` ([ConTeXt](https://www.contextgarden.net/)) - `csljson` ([CSL JSON](https://citeproc-js.readthedocs.io/en/latest/csl-json/markup.html) bibliography) - `djot` ([Djot markup](https://djot.net)) - `docbook` or `docbook4` ([DocBook](https://docbook.org) 4) - `docbook5` (DocBook 5) - `docx` ([Word docx](https://en.wikipedia.org/wiki/Office_Open_XML)) - `dokuwiki` ([DokuWiki markup](https://www.dokuwiki.org/dokuwiki)) - `epub` or `epub3` ([EPUB](http://idpf.org/epub) v3 book) - `epub2` (EPUB v2) - `fb2` ([FictionBook2](http://www.fictionbook.org/index.php/Eng:XML_Schema_Fictionbook_2.1) e-book) - `gfm` ([GitHub-Flavored Markdown](https://help.github.com/articles/github-flavored-markdown/)), or the deprecated and less accurate `markdown_github`; use [`markdown_github`](https://pandoc.org/MANUAL.html#markdown-variants) only if you need extensions not supported in [`gfm`](https://pandoc.org/MANUAL.html#markdown-variants). - `haddock` ([Haddock markup](https://www.haskell.org/haddock/doc/html/ch03s08.html)) - `html` or `html5` ([HTML](https://www.w3.org/html/), i.e. [HTML5](https://html.spec.whatwg.org/)/XHTML [polyglot markup](https://www.w3.org/TR/html-polyglot/)) - `html4` ([XHTML](https://www.w3.org/TR/xhtml1/) 1.0 Transitional) - `icml` ([InDesign ICML](https://web.archive.org/web/20211006210211/https://wwwimages.adobe.com/www.adobe.com/content/dam/acom/en/devnet/indesign/sdk/cs6/idml/idml-cookbook.pdf)) - `ipynb` ([Jupyter notebook](https://nbformat.readthedocs.io/en/latest/)) - `jats_archiving` ([JATS](https://jats.nlm.nih.gov) XML, Archiving and Interchange Tag Set) - `jats_articleauthoring` ([JATS](https://jats.nlm.nih.gov) XML, Article Authoring Tag Set) - `jats_publishing` ([JATS](https://jats.nlm.nih.gov) XML, Journal Publishing Tag Set) - `jats` (alias for `jats_archiving`) - `jira` ([Jira](https://jira.atlassian.com/secure/WikiRendererHelpAction.jspa?section=all)/Confluence wiki markup) - `json` (JSON version of native AST) - `latex` ([LaTeX](https://www.latex-project.org/)) - `man` ([roff man](https://man.cx/groff_man(7))) - `markdown` ([Pandoc’s Markdown](https://pandoc.org/MANUAL.html#pandocs-markdown)) - `markdown_mmd` ([MultiMarkdown](https://fletcherpenney.net/multimarkdown/)) - `markdown_phpextra` ([PHP Markdown Extra](https://michelf.ca/projects/php-markdown/extra/)) - `markdown_strict` (original unextended [Markdown](https://daringfireball.net/projects/markdown/)) - `markua` ([Markua](https://leanpub.com/markua/read)) - `mediawiki` ([MediaWiki markup](https://www.mediawiki.org/wiki/Help:Formatting)) - `ms` ([roff ms](https://man.cx/groff_ms(7))) - `muse` ([Muse](https://amusewiki.org/library/manual)) - `native` (native Haskell) - `odt` ([OpenDocument text document](https://en.wikipedia.org/wiki/OpenDocument)) - `opml` ([OPML](https://opml.org/spec2.opml)) - `opendocument` ([OpenDocument XML](https://www.oasis-open.org/2021/06/16/opendocument-v1-3-oasis-standard-published/)) - `org` ([Emacs Org mode](https://orgmode.org)) - `pdf` ([PDF](https://www.adobe.com/pdf/)) - `plain` (plain text) - `pptx` ([PowerPoint](https://en.wikipedia.org/wiki/Microsoft_PowerPoint) slide show) - `rst` ([reStructuredText](https://docutils.sourceforge.io/docs/ref/rst/introduction.html)) - `rtf` ([Rich Text Format](https://en.wikipedia.org/wiki/Rich_Text_Format)) - `texinfo` ([GNU Texinfo](https://www.gnu.org/software/texinfo/)) - `textile` ([Textile](https://textile-lang.com)) - `t2t` ([txt2tags](https://txt2tags.org)) - `slideous` ([Slideous](https://goessner.net/articles/slideous/) HTML and JavaScript slide show) - `slidy` ([Slidy](https://www.w3.org/Talks/Tools/Slidy2/) HTML and JavaScript slide show) - `dzslides` ([DZSlides](https://paulrouget.com/dzslides/) HTML5 + JavaScript slide show) - `revealjs` ([reveal.js](https://revealjs.com/) HTML5 + JavaScript slide show) - `s5` ([S5](https://meyerweb.com/eric/tools/s5/) HTML and JavaScript slide show) - `tei` ([TEI Simple](https://github.com/TEIC/TEI-Simple)) - `typst` ([typst](https://typst.app)) - `vimdoc` ([Vimdoc](https://vimhelp.org/helphelp.txt.html#help-writing)) - `xml` (XML version of native AST) - `xwiki` ([XWiki markup](https://www.xwiki.org/xwiki/bin/view/Documentation/UserGuide/Features/XWikiSyntax/)) - `zimwiki` ([ZimWiki markup](https://zim-wiki.org/manual/Help/Wiki_Syntax.html)) - the path of a custom Lua writer, see [Custom readers and writers](https://pandoc.org/MANUAL.html#custom-readers-and-writers) below Pandoc can also produce PDF output via LaTeX, Groff ms, or HTML. Pandoc’s enhanced version of Markdown includes syntax for tables, definition lists, metadata blocks, footnotes, citations, math, and much more. See the User’s Manual below under [Pandoc’s Markdown](https://pandoc.org/MANUAL.html#pandocs-markdown). Pandoc has a modular design: it consists of a set of readers, which parse text in a given format and produce a native representation of the document (an *abstract syntax tree* or AST), and a set of writers, which convert this native representation into a target format. Thus, adding an input or output format requires only adding a reader or writer. Users can also run custom pandoc filters to modify the intermediate AST (see the documentation for [filters](https://pandoc.org/filters.html) and [Lua filters](https://pandoc.org/lua-filters.html)). Because pandoc’s intermediate representation of a document is less expressive than many of the formats it converts between, one should not expect perfect conversions between every format and every other. Pandoc attempts to preserve the structural elements of a document, but not formatting details such as margin size. And some document elements, such as complex tables, may not fit into pandoc’s simple document model. While conversions from pandoc’s Markdown to all formats aspire to be perfect, conversions from formats more expressive than pandoc’s Markdown can be expected to be lossy. ## Installing Here’s [how to install pandoc](INSTALL.md). ## Documentation Pandoc’s website contains a full [User’s Guide](https://pandoc.org/MANUAL.html). It is also available [here](MANUAL.txt) as pandoc-flavored Markdown. The website also contains some [examples of the use of pandoc](https://pandoc.org/demos.html), a limited [online demo](https://pandoc.org/try), and a [WebAssembly-based online demo](https://pandoc.org/app). ## Contributing Pull requests, bug reports, and feature requests are welcome. Please make sure to read [the contributor guidelines](CONTRIBUTING.md) before opening a new issue. ## License © 2006-2024 John MacFarlane (jgm@berkeley.edu). Released under the [GPL](https://www.gnu.org/licenses/old-licenses/gpl-2.0.html "GNU General Public License"), version 2 or greater. This software carries no warranty of any kind. (See COPYRIGHT for full copyright and warranty notices.) --- ## File: doc/custom-readers.md --- author: - John MacFarlane date: 'November 18, 2021' title: Creating Custom Pandoc Readers in Lua --- # Introduction If you need to parse a format not already handled by pandoc, you can create a custom reader using the [Lua] language. Pandoc has a built-in Lua interpreter, so you needn't install any additional software to do this. [Lua]: https://www.lua.org A custom reader is a Lua file that defines a function called `Reader`, which takes two arguments: - the raw input to be parsed, as a list of sources - optionally, a table of reader options, e.g. `{ columns = 62, standalone = true }`. The `Reader` function should return a `Pandoc` AST. This can be created using functions in the [`pandoc` module], which is automatically in scope. (Indeed, all of the utility functions that are available for [Lua filters] are available in custom readers, too.) Each source item corresponds to a file or stream passed to pandoc containing its text and name. E.g., if a single file `input.txt` is passed to pandoc, then the list of sources will contain just a single element `s`, where `s.name == 'input.txt'` and `s.text` contains the file contents as a string. The sources list, as well as each of its elements, can be converted to a string via the Lua standard library function `tostring`. [Lua filters]: https://pandoc.org/lua-filters.html [`pandoc` module]: https://pandoc.org/lua-filters.html#module-pandoc A minimal example would be ```lua function Reader(input) return pandoc.Pandoc({ pandoc.CodeBlock(tostring(input)) }) end ``` This just returns a document containing a big code block with all of the input. Or, to create a separate code block for each input file, one might write ``` lua function Reader(input) return pandoc.Pandoc(input:map( function (s) return pandoc.CodeBlock(s.text) end)) end ``` In a nontrivial reader, you'll want to parse the input. You can do this using standard Lua library functions (for example, the [patterns] library), or with the powerful and fast [lpeg] parsing library, which is automatically in scope. You can also use external Lua libraries (for example, an XML parser). A previous pandoc version passed a raw string instead of a list of sources to the Reader function. Reader functions that rely on this are obsolete, but still supported: Pandoc analyzes any script error, detecting when code assumed the old behavior. The code is rerun with raw string input in this case, thereby ensuring backwards compatibility. [patterns]: http://lua-users.org/wiki/PatternsTutorial [lpeg]: http://www.inf.puc-rio.br/~roberto/lpeg/ # Bytestring readers In order to read binary formats, including docx, odt, and epub, pandoc supports the `ByteStringReader` function. A `ByteStringReader` function is similar to the `Reader` function that processes text input. Instead of a list of sources, the ByteStringReader function is passed a bytestring, i.e., a string that contains the binary input. ``` lua -- read input as epub function ByteStringReader (input) return pandoc.read(input, 'epub') end ``` # Format extensions Custom readers can be built such that their behavior is controllable through format extensions, such as `smart`, `citations`, or `hard-line-breaks`. Supported extensions are those that are present as a key in the global `Extensions` table. Fields of extensions that are enabled default have the value `true` or `enable`, while those that are supported but disabled have value `false` or `disable`. Example: A reader with the following global table supports the extensions `smart`, `citations`, and `foobar`, with `smart` enabled and the other two disabled by default: ``` lua Extensions = { smart = 'enable', citations = 'disable', foobar = true } ``` The users control extensions as usual, e.g., `pandoc -f my-reader.lua+citations`. The extensions are accessible through the reader options' `extensions` field, e.g.: ``` lua function Reader (input, opts) print( 'The citations extension is', opts.extensions:includes 'citations' and 'enabled' or 'disabled' ) -- ... end ``` Extensions that are neither enabled nor disabled in the `Extensions` field are treated as unsupported by the reader. Trying to modify such an extension via the command line will lead to an error. # Example: plain text reader This is a simple example using [lpeg] to parse the input into space-separated strings and blankline-separated paragraphs. ```lua -- A sample custom reader that just parses text into blankline-separated -- paragraphs with space-separated words. -- For better performance we put these functions in local variables: local P, S, R, Cf, Cc, Ct, V, Cs, Cg, Cb, B, C, Cmt = lpeg.P, lpeg.S, lpeg.R, lpeg.Cf, lpeg.Cc, lpeg.Ct, lpeg.V, lpeg.Cs, lpeg.Cg, lpeg.Cb, lpeg.B, lpeg.C, lpeg.Cmt local whitespacechar = S(" \t\r\n") local wordchar = (1 - whitespacechar) local spacechar = S(" \t") local newline = P"\r"^-1 * P"\n" local blanklines = newline * (spacechar^0 * newline)^1 local endline = newline - blanklines -- Grammar G = P{ "Pandoc", Pandoc = Ct(V"Block"^0) / pandoc.Pandoc; Block = blanklines^0 * V"Para" ; Para = Ct(V"Inline"^1) / pandoc.Para; Inline = V"Str" + V"Space" + V"SoftBreak" ; Str = wordchar^1 / pandoc.Str; Space = spacechar^1 / pandoc.Space; SoftBreak = endline / pandoc.SoftBreak; } function Reader(input) return lpeg.match(G, tostring(input)) end ``` Example of use: ``` % pandoc -f plain.lua -t native *Hello there*, this is plain text with no formatting except paragraph breaks. - Like this one. ^D [ Para [ Str "*Hello" , Space , Str "there*," , Space , Str "this" , Space , Str "is" , Space , Str "plain" , Space , Str "text" , Space , Str "with" , Space , Str "no" , Space , Str "formatting" , SoftBreak , Str "except" , Space , Str "paragraph" , Space , Str "breaks." ] , Para [ Str "-" , Space , Str "Like" , Space , Str "this" , Space , Str "one." ] ] ``` # Example: a wiki Creole reader This is a parser for [Creole common wiki markup]. It uses an [lpeg] grammar. Fun fact: this custom reader is faster than pandoc's built-in creole reader! This shows that high-performance readers can be designed in this way. [Creole common wiki markup]: http://www.wikicreole.org/wiki/CheatSheet ``` /* Detailed source-code truncated for AI context efficiency. */ ``` Example of use: ``` % pandoc -f creole.lua -t markdown == Wiki Creole You can make things **bold** or //italic// or **//both//** or //**both**//. Character formatting extends across line breaks: **bold, this is still bold. This line deliberately does not end in star-star. Not bold. Character formatting does not cross paragraph boundaries. You can use [[internal links]] or [[http://www.wikicreole.org|external links]], give the link a [[internal links|different]] name. ^D ## Wiki Creole You can make things **bold** or *italic* or ***both*** or ***both***. Character formatting extends across line breaks: \*\*bold, this is still bold. This line deliberately does not end in star-star. Not bold. Character formatting does not cross paragraph boundaries. You can use [internal links](internal links) or [external links](http://www.wikicreole.org), give the link a [different](internal links) name. ``` # Example: parsing JSON from an API This custom reader consumes the JSON output of and produces a document containing the current top articles on the Haskell subreddit. It assumes that the `pandoc.json` library is available, which ships with pandoc versions after (not including) 3.1. It's still possible to use this with older pandoc version by using a different JSON library. E.g., `luajson` can be installed using `luarocks install luajson`---but be sure you are installing it for Lua 5.4, which is the version packaged with pandoc. ```lua -- consumes the output of https://www.reddit.com/r/haskell.json local json = require 'pandoc.json' local function read_inlines(raw) local doc = pandoc.read(raw, "commonmark") return pandoc.utils.blocks_to_inlines(doc.blocks) end local function read_blocks(raw) local doc = pandoc.read(raw, "commonmark") return doc.blocks end function Reader(input) local parsed = json.decode(tostring(input)) local blocks = {} for _,entry in ipairs(parsed.data.children) do local d = entry.data table.insert(blocks, pandoc.Header(2, pandoc.Link(read_inlines(d.title), d.url))) for _,block in ipairs(read_blocks(d.selftext)) do table.insert(blocks, block) end end return pandoc.Pandoc(blocks) end ``` Similar code can be used to consume JSON output from other APIs. Note that the content of the text fields is markdown, so we convert it using `pandoc.read()`. # Example: syntax-highlighted code files This is a reader that puts the content of each input file into a code block, sets the file's extension as the block's class to enable code highlighting, and places the filename as a header above each code block. ``` lua function to_code_block (source) local _, lang = pandoc.path.split_extension(source.name) return pandoc.Div{ pandoc.Header(1, source.name == '' and '' or source.name), pandoc.CodeBlock(source.text, {class=lang}), } end function Reader (input, opts) return pandoc.Pandoc(input:map(to_code_block)) end ``` # Example: extracting the content from web pages This reader uses the command-line program `readable` (install via `npm install readability-cli`) to clean out parts of HTML input that have to do with navigation, leaving only the content. ``` /* Detailed source-code truncated for AI context efficiency. */ ``` Example of use: ``` pandoc -f readable.lua -t markdown https://pandoc.org ``` and compare the output to ``` pandoc -f html -t markdown https://pandoc.org ``` --- ## File: doc/custom-writers.md --- author: - John MacFarlane date: 'November 21, 2021' title: Creating Custom Pandoc Writers in Lua --- # Introduction If you need to render a format not already handled by pandoc, or you want to change how pandoc renders a format, you can create a custom writer using the [Lua] language. Pandoc has a built-in Lua interpreter, so you needn't install any additional software to do this. [Lua]: https://www.lua.org A custom writer is a Lua file that defines how to render the document. Writers must define just a single function, named either `Writer` or `ByteStringWriter`, which gets passed the document and writer options, and then handles the conversion of the document, rendering it into a string. This interface was introduced in pandoc 2.17.2, with ByteString writers becoming available in pandoc 3.0. Pandoc also supports "classic" custom writers, where a Lua function must be defined for each AST element type. Classic style writers are *deprecated* and should be replaced with new-style writers if possible. # Writers Custom writers using the new style must contain a global function named `Writer` or `ByteStringWriter`. Pandoc calls this function with the document and writer options as arguments, and expects the function to return a UTF-8 encoded string. ``` lua function Writer (doc, opts) -- ... end ``` Writers that do not return text but binary data should define a function with name `ByteStringWriter` instead. The function must still return a string, but it does not have to be UTF-8 encoded and can contain arbitrary binary data. If both `Writer` and `ByteStringWriter` functions are defined, then only the `Writer` function will be used. ## Format extensions Writers can be customized through format extensions, such as `smart`, `citations`, or `hard_line_breaks`. The global `Extensions` table indicates supported extensions with a key. Extensions enabled by default are assigned a true value, while those that are supported but disabled are assigned a false value. Example: A writer with the following global table supports the extensions `smart`, `citations`, and `foobar`, with `smart` enabled and the others disabled by default: ``` lua Extensions = { smart = true, citations = false, foobar = false } ``` The users control extensions as usual, e.g., `pandoc -t my-writer.lua+citations`. The extensions are accessible through the writer options' `extensions` field, e.g.: ``` lua function Writer (doc, opts) print( 'The citations extension is', opts.extensions:includes 'citations' and 'enabled' or 'disabled' ) -- ... end ``` ## Default template The default template of a custom writer is defined by the return value of the global function `Template`. Pandoc uses the default template for rendering when the user has not specified a template, but invoked with the `-s`/`--standalone` flag. The `Template` global can be left undefined, in which case pandoc will throw an error when it would otherwise use the default template. ## Example: modified Markdown writer Writers have access to all modules described in the [Lua filters documentation][]. This includes `pandoc.write`, which can be used to render a document in a format already supported by pandoc. The document can be modified before this conversion, as demonstrated in the following short example. It renders a document as GitHub Flavored Markdown, but always uses fenced code blocks, never indented code. ``` lua function Writer (doc, opts) local filter = { CodeBlock = function (cb) -- only modify if code block has no attributes if cb.attr == pandoc.Attr() then local delimited = '```\n' .. cb.text .. '\n```' return pandoc.RawBlock('markdown', delimited) end end } return pandoc.write(doc:walk(filter), 'gfm', opts) end Template = pandoc.template.default 'gfm' ``` [Lua filters documentation]: https://pandoc.org/lua-filters.html ## Reducing boilerplate with `pandoc.scaffolding.Writer` The `pandoc.scaffolding.Writer` structure is a custom writer scaffold that serves to avoid common boilerplate code when defining a custom writer. The object can be used as a function and allows to skip details like metadata and template handling, requiring only the render functions for each AST element type. The value of `pandoc.scaffolding.Writer` is a function that should usually be assigned to the global `Writer`: ``` lua Writer = pandoc.scaffolding.Writer ``` The render functions for Block and Inline values can then be added to `Writer.Block` and `Writer.Inline`, respectively. The functions are passed the element and the WriterOptions. ``` lua Writer.Inline.Str = function (str) return str.text end Writer.Inline.SoftBreak = function (_, opts) return opts.wrap_text == "wrap-preserve" and cr or space end Writer.Inline.LineBreak = cr Writer.Block.Para = function (para) return {Writer.Inlines(para.content), pandoc.layout.blankline} end ``` The render functions must return a string, a pandoc.layout *Doc* element, or a list of such elements. In the latter case, the values are concatenated as if they were passed to `pandoc.layout.concat`. If the value does not depend on the input, a constant can be used as well. The tables `Writer.Block` and `Writer.Inline` can be used as functions; they apply the right render function for an element of the respective type. E.g., `Writer.Block(pandoc.Para 'x')` will delegate to the `Writer.Para` render function and will return the result of that call. Similarly, the functions `Writer.Blocks` and `Writer.Inlines` can be used to render lists of elements, and `Writer.Pandoc` renders the document's blocks. The function `Writer.Blocks` can take a separator as an optional second argument, e.g., `Writer.Blocks(blks, pandoc.layout.cr)`; the default block separator is `pandoc.layout.blankline`. All predefined functions can be overwritten when needed. The resulting Writer uses the render functions to handle metadata values and converts them to template variables. The template is applied automatically if one is given. # Classic style A writer using the classic style defines rendering functions for each element of the pandoc AST. Note that this style is *deprecated* and may be removed in later versions. For example, ``` lua function Para(s) return "" .. s .. "" end ``` ## Template variables New template variables can be added, or existing ones modified, by returning a second value from function `Doc`. For example, the following will add the current date in variable `date`, unless `date` is already defined as either a metadata value or a variable: ``` lua function Doc (body, meta, vars) vars.date = vars.date or meta.date or os.date '%B %e, %Y' return body, vars end ``` ## Changes in pandoc 3.0 Custom writers were reworked in pandoc 3.0. For technical reasons, the global variables `PANDOC_DOCUMENT` and `PANDOC_WRITER_OPTIONS` are set to the empty document and default values, respectively. The old behavior can be restored by adding the following snippet, which turns a classic into a new style writer. ``` lua function Writer (doc, opts) PANDOC_DOCUMENT = doc PANDOC_WRITER_OPTIONS = opts loadfile(PANDOC_SCRIPT_FILE)() return pandoc.write_classic(doc, opts) end ``` --- ## File: doc/customizing-pandoc.md --- author: - Mauro Bieg - John MacFarlane title: Customizing Pandoc --- This document provides a quick overview over the various ways to customize pandoc's output, with links to fuller documentation and some examples. ## Templates When the `-s`/`--standalone` option is used, pandoc will generate a standalone document rather than a fragment. For example, in HTML output this will include the `` element; in LaTeX output, it will include the preamble. Pandoc comes with a default template for (almost) every output format. A template is a plain text file containing variables that are replaced by text generated by pandoc. For example, the variable `$body$` will be replaced by the document body, and `$title$` by the title from metadata. To look at the default template for an output format, you can do `pandoc -D FORMAT`, where `FORMAT` is replaced by the name of the format. For example `pandoc -D latex`. You can also use your own template instead, either by using the `--template` option or by putting the custom template in your user data directory (on Linux and macOS, `~/.pandoc/templates/`). Note that in many cases you can avoid the need for a custom template by including a file with the `--include-in-header`, `--include-before-body`, or `--include-after-body` option. Or you can set the corresponding template variable directly. ### Template variables There are several ways to set template variables: | | [`--variable`] | [`--metadata`] | [YAML metadata] and [`--metadata-file`] | |:---------------|:------------------|:------------------|:----------------------------| | values can be… | strings and bools | strings and bools | also YAML objects and lists | | strings are… | inserted verbatim | escaped | interpreted as markdown | | accessible by filters: | no | yes | yes | [`--variable`]: https://pandoc.org/MANUAL.html#option--variable [`--metadata`]: https://pandoc.org/MANUAL.html#option--metadata [YAML metadata]: https://pandoc.org/MANUAL.html#extension-yaml_metadata_block [`--metadata-file`]: https://pandoc.org/MANUAL.html#option--metadata-file For more information, see [Templates](https://pandoc.org/MANUAL.html#templates) in the pandoc manual. ### Example: adding structured author data to HTML TODO ### Example: generating documents from YAML metadata TODO ## Reference docx/pptx/odt For `docx`, `pptx` or `odt` documents, things are a bit more complicated. Instead of a single template file, you need to provide a customized `reference.docx/pptx/odt`. See the manual for the [`--reference-doc`](https://pandoc.org/MANUAL.html#option--reference-doc) option. ### Example: changing the font and line spacing in a Word docx TODO ## Filters Templates are very powerful, but they are only a sort of scaffold to place your document's body text in. You cannot directly change the body text using the template. If you need to affect the output of the actual body text, you can use a pandoc filter. A filter is a small program that transforms the document, between the parsing and the writing phase, while it is still in pandoc's native format. For example, a filter might find all the Header elements of a document and capitalize their text. Pandoc's native representation of a document is an abstract syntax tree (AST), not unlike the HTML DOM. It is documented [here](https://hackage.haskell.org/package/pandoc-types/docs/Text-Pandoc-Definition.html). A `Pandoc` document is a chunk of metadata (`Meta`) and a list of `Block`s. The `Block`s, in turn, are composed of other `Block`s and `Inline` elements. (`Block` elements are things like paragraphs, lists, headers, and code blocks. `Inline` elements are individual words, links, emphasis, and so on.) Filters operate on these elements. You can use `pandoc -t native` to learn about the AST's structure. There are two kinds of filters: JSON filters (which transform a JSON serialization of the pandoc AST, and may be written in any language that can parse and emit JSON), and Lua filters (which use an interface built directly into pandoc, and must be written in the Lua language). If you are writing your own filters, it is best to use Lua filters, which are more portable (they require only pandoc itself) and more efficient. See [Lua filters](https://pandoc.org/lua-filters.html) for documentation and examples. If you would prefer to write your filter in another language, see [Filters](https://pandoc.org/filters.html) for a gentle introduction to JSON filters. There's a repository of lua filters at [pandoc/lua-filters](https://github.com/pandoc/lua-filters) on GitHub. A number of pandoc filters, written in Haskell, are available on [Hackage](https://hackage.haskell.org/packages/search?terms=pandoc+filter) and can be installed using the `stack` or `cabal` tools. The wiki also lists [third party filters](https://github.com/jgm/pandoc/wiki/Pandoc-Filters). ### Example: capitalizing headers TODO ### Example: code extractor TODO ## Generic Divs and Spans TODO [Divs and Spans](https://pandoc.org/MANUAL.html#divs-and-spans): generic blocks that can be transformed with filters ### Example: colored text ### Example: custom styles in docx [Custom Styles in Docx](https://pandoc.org/MANUAL.html#custom-styles-in-docx) ## Raw attributes TODO [Generic raw attributes](https://pandoc.org/MANUAL.html#generic-raw-attribute): to include raw snippets ## Custom writers TODO [Custom writers](https://pandoc.org/MANUAL.html#custom-writers) ## Custom syntax highlighting TODO [Custom syntax highlighting](https://pandoc.org/MANUAL.html#syntax-highlighting), provided by the [skylighting library](https://github.com/jgm/skylighting) including highlighting styles --- ## File: doc/epub.md --- title: Creating an ebook with pandoc author: John MacFarlane --- Starting with version 1.6, pandoc can produce output in the [EPUB] electronic book format. EPUB books can be viewed on iPads, Nooks, and other electronic book readers, including many smart phones. (They can also be converted to Kindle books using the GUI only [KindlePreviewer] on Windows and Mac OSX. [KindleGen] – which offers a command line interface and supports [Linux][KindleGenLinux], [Mac OSX][KindleGenMacOSX] and [Windows][KindleGenWindows] – has been deprecated, but binaries can still be found on the internet.) This means that it's now very easy to produce an electronic book! Let's try it. # A toy example Use your text editor to create a file `mybook.txt`, with the following contents: % My Book % Sam Smith This is my book! # Chapter One Chapter one is over. # Chapter Two Chapter two has just begun. To make this into an ebook takes only one command: pandoc mybook.txt -o mybook.epub You can upload `mybook.epub` to your ebook reader and try it out. Note that if your markdown file contains links to local images, for example pandoc will automatically include the images in the generated epub. # A real book To see what this would look like for a real book, let's convert Scott Chacon's book [Pro Git], which he wrote using pandoc's markdown variant and released under a [Creative Commons] license. (If you use the book, please consider [buying a copy] to help support his excellent work.) You can find the markdown source for the book on its [github site]. Let's get a copy of the whole repository:[^1] git clone https://github.com/progit/progit.git [^1]: If you don't have [git], you can browse to the [github site] and click "Download Source" to get the same files in a zip or tar archive. This command will create a working directory called `progit` on your machine. The actual markdown sources for the English version of the book are in the `en` subdirectory, so start by changing to that directory: cd progit/en As you can see, each chapter is a single text file in its own directory. Chacon does some postprocessing on these files, for example, to insert images. This is a placeholder for Figure 1-1, for example: Insert 18333fig0101.png Figure 1-1. Local version control diagram. The actual image file is called `18333fig0101-tn.png` and lives in the `figures` subdirectory of the repository, as you can verify. For demonstration purposes, we want pure markdown files, so let's change this placeholder into a markdown image link. Pandoc will treat a paragraph containing a single image as a figure with a caption, which is what we want: We can make this change in all the files with a perl one-liner: perl -i -0pe \ 's/^Insert\s*(.*)\.png\s*\n([^\n]*)$/!\[\2](..\/figures\/\1-tn.png)/mg' \ */*.markdown This will modify the files in place. (We won't worry about backing them up; if we mess up, we can get the original files back with `git reset --hard`.) OK! Now we're almost ready to make an ebook. We have the chapters, each in its own file, but we still need a title. Create a file, `title.txt`, with a pandoc YAML metadata block: ``` --- title: Pro Git author: Scott Chacon rights: Creative Commons Non-Commercial Share Alike 3.0 language: en-US ... ``` See the [User's Guide](https://pandoc.org/MANUAL.html#epub-metadata) for more information about these fields. Now run pandoc to make the ebook, using our title page and modified chapter files as sources: pandoc -o progit.epub title.txt \ 01-introduction/01-chapter1.markdown \ 02-git-basics/01-chapter2.markdown \ 03-git-branching/01-chapter3.markdown \ 04-git-server/01-chapter4.markdown \ 05-distributed-git/01-chapter5.markdown \ 06-git-tools/01-chapter6.markdown \ 07-customizing-git/01-chapter7.markdown \ 08-git-and-other-scms/01-chapter8.markdown \ 09-git-internals/01-chapter9.markdown That's it! The ebook, `progit.epub`, is ready to be uploaded to your reader. ## Changing the format You can use the `--css` option to specify a CSS file for the book. The default CSS is minimal and can be found [on GitHub](https://github.com/jgm/pandoc/blob/main/data/epub.css) or in the `epub.css` file in your data directory (see `--data-dir` in the [User's Guide]). You can even embed fonts in the EPUB if you want; see the [User's Guide] under `--epub-embed-font` for instructions. ## Math Pandoc has an EPUB3 writer. It renders LaTeX math into MathML, which EPUB3 readers are supposed to support (but unfortunately few do). Of course, this isn't much help if you want EPUB2 output (`pandoc -t epub2`) or target readers that don't support MathML. Then you have two options: 1. Use the [`--webtex`](https://pandoc.org/MANUAL.html#option--webtex) option, which will use a web service to convert the TeX to an image. 2. Use the [`--gladtex`](https://pandoc.org/MANUAL.html#option--gladtex) option to convert maths into SVG images on your local machine. Both GladTeX and WebTeX add the LaTeX source of the formula as alternative text of the image, increasing accessibility for blind users. [KindlePreviewer]: https://www.amazon.com/Kindle-Previewer/b?node=21381691011 [KindleGen]: https://www.amazon.com/gp/feature.html?docId=1000765211 [KindleGenLinux]: https://archive.org/details/kindlegen2.9 [KindleGenMacOSX]: https://web.archive.org/web/20190905040839/https://www.amazon.com/gp/feature.html?ie=UTF8&docId=1000765211 [KindleGenWindows]: https://archive.org/details/kindlegen_win32_v2_9 [EPUB]: https://en.wikipedia.org/wiki/EPUB [Pro Git]: https://git-scm.com/book/en/v2 [Creative Commons]: https://creativecommons.org/ [buying a copy]: https://git-scm.com/book/en/v2 [github site]: https://github.com/progit/progit [git]: https://git-scm.com [Dublin Core metadata elements]: https://dublincore.org/documents/dces/ [User's Guide]: https://pandoc.org/MANUAL.html --- ## File: doc/extras.md --- title: Pandoc Extras author: John MacFarlane --- This is a curated list of some of the most useful third-party software that extends pandoc's capabilities. For a more complete list, see the [Pandoc Extras wiki page](https://github.com/jgm/pandoc/wiki/Pandoc-Extras). ### GUI - [PanWriter](https://github.com/mb21/panwriter/#panwriter) is a Markdown editor with live preview that can import and export using pandoc. - [Pandoc Mac OS X Services](https://github.com/mb21/Pandoc-Mac-OS-X-Services) allows you to invoke pandoc from any text editor with the opened file as input. ### Editor support - [pandoc-mode](http://joostkremers.github.io/pandoc-mode) for Emacs - [vim-pandoc](https://github.com/vim-pandoc) for Vim - [Panache](https://panache.bz/) is a language server, formatter, and linter for Pandoc markdown. ### CLI wrappers - [panzer](https://github.com/msprev/panzer) allows you to specify command-line options and styles in the Markdown file's YAML metadata. - [pandocomatic](https://heerdebeer.org/Software/markdown/pandocomatic/) is similar to panzer but also provides support for converting directory trees. - [panrun](https://github.com/mb21/panrun) is a more minimalistic alternative to panzer and pandocomatic. ### Editing/document changes - [pandiff](https://github.com/davidar/pandiff) creates prose diffs for any document format supported by pandoc. - [pancritic](https://github.com/ickc/pancritic) allows using [CriticMarkup](http://criticmarkup.com/spec.php#caveats) with pandoc. ### Charts and data - [R Markdown](https://rmarkdown.rstudio.com) allows you to process Markdown documents with integrated data and charts (integrates pandoc). - [pandoc-plot](https://github.com/LaurentRDC/pandoc-plot) allows you to integrate programmatically generated plots generated by various tools. ### Citations - [zotxt](https://github.com/egh/zotxt) is Zotero extension for working with pandoc ### Numbering and cross-references - [pandoc-crossref](https://github.com/lierdakil/pandoc-crossref) is a filter that adds support for figure, table, and equation numbers and cross-references. - [pandoc-xnos](https://github.com/tomduck/pandoc-xnos) is a suite of filters supporting numbering and cross-referencing figures, equations, tables, and sections. ### Academic publishing workflows - [Quarto](https://quarto.org/) is an open-source scientific and technical publishing system to make reproducible, production quality articles, presentations, websites, blogs, and books. It supports equations, citations, crossrefs, figure panels, callouts, advanced layout, etc. - [Manubot](https://manubot.org) is a workflow and set of tools for the next generation of scholarly publishing, including citation support and support for multiple output formats. It's especially suited for papers with a very large set of authors. - [pandoc-ext](https://github.com/pandoc-ext) includes goodies such as putting the Abstract into a section, multiple bibliographies, support the Citation Typing Ontology (CiTO), etc. - [Baseprinter](https://try.perm.pub/baseprinter/) is an open-source pandoc wrapper to generate Baseprint document snapshots and HTML/PDF previews. These snapshots can be self-published/archived as editions of a [Baseprint document succession](https://try.perm.pub/document_succession/). - [Pandoc Scholar](https://github.com/pandoc-scholar/pandoc-scholar) is a set of utilities to make publishing of scientific articles as simple and pleasant as possible. It simplifies setting authors' metadata in YAML blocks, allows to add semantic annotation to citations, and only requires the programs `pandoc` and `make`. Please note that it is no longer maintained and refers to `Quarto` and `pandoc-ext` ### Containers - [pandoc docker images](https://github.com/pandoc/dockerfiles) ### Lua filters (For a fuller list, see [the lua-filters repository](https://github.com/pandoc/lua-filters).) - [Spell checking](https://github.com/pandoc/lua-filters/tree/master/spellcheck). - [Word count](https://github.com/pandoc/lua-filters/tree/master/wordcount). - [Embed textually-specified diagrams](https://github.com/pandoc-ext/diagram) in Mermaid, Dot/GraphViz, PlantUML, Asymptote, CeTZ, and TikZ. - [Create subfigures in pandoc's Markdown](https://github.com/rnwst/pandoc-subfigs). - [Handle scholarly metadata](https://github.com/pandoc/lua-filters/tree/master/scholarly-metadata). - [Panda](http://christophe.delord.free.fr/panda/) provides conditionals, code file inclusion, string expansion, and diagrams from code blocks. ### Logo Here is a logo designed by pandoc contributor Albert Krewinkel: . --- ## File: doc/faqs.md % FAQs ::: faqs ## How can I convert a whole directory of files from Markdown to RTF? On linux or OSX: for f in *.txt; do pandoc "$f" -s -o "${f%.txt}.rtf"; done In Windows Powershell: gci -r -i *.txt |foreach{$rtf=$_.directoryname+"\"+$_.basename+".rtf";pandoc -f markdown -s $_.fullname -o $rtf} ## I used pandoc to convert a document to ICML (or OPML or RTF), and when I try to open it I'm told it's invalid. What have I done wrong? Be sure to use the `-s` or `--standalone` flag, or you just get a fragment, not a full document with the required header: pandoc -s -f markdown -t icml -o my.icml my.md ## I get a blank document when I try to convert a markdown document in Chinese to PDF. By default, pandoc uses pdflatex to generate the PDF, and pdflatex doesn't handle Chinese characters. But you can change the default to use xelatex instead. You should also make sure you're using a font with Chinese glyphs. For example: pandoc -o c.pdf --pdf-engine=xelatex -V mainfont='Adobe Ming Std' ## The Windows installer does a single user install, rather than installing pandoc for all users. How can I install pandoc for all users? Run the following command as admin: msiexec /i pandoc-VERSION.msi ALLUSERS=1 This will put pandoc in `C:\Program Files\Pandoc`. You can install Pandoc to a different directory by setting APPLICATIONFOLDER parameter, for example: msiexec /i pandoc-1.11.1.msi ALLUSERS=1 APPLICATIONFOLDER="C:\Pandoc" ## How do I change the margins in PDF output? The option -V geometry:margin=1in will set the margins to one inch on each side. If you don't want uniform margins, you can do something like -V geometry:"top=2cm, bottom=1.5cm, left=1cm, right=1cm" Or -V geometry:"left=3cm, width=10cm" For more options, see the documentation for the LaTeX [geometry package](https://www.ctan.org/pkg/geometry). ## How does pandoc compare to multimarkdown? Here is a [wiki page](https://github.com/jgm/pandoc/wiki/Pandoc-vs-Multimarkdown) comparing the two. ## When I specify an image width of 50% and convert to LaTeX, pandoc sets the height to textheight and the aspect ratio isn't preserved. How can I prevent this? For example, if you convert an image with `{width="50%"}`, the LaTeX produced will be `\includegraphics[width=0.5\textwidth,height=\textheight]`. This output presupposes the following code in pandoc's default latex template: ``` % Scale images if necessary, so that they will not overflow the page % margins by default, and it is still possible to overwrite the defaults % using explicit options in \includegraphics[width, height, ...]{} \setkeys{Gin}{width=\maxwidth,height=\maxheight,keepaspectratio} ``` If you don't have this in your custom template, you should add it. If we didn't set the `height` explicitly in this way, the image would not be resized correctly unless it was being resized to smaller than its original size. ## Pandoc sometimes uses too much memory. How can I limit the memory used by pandoc? `pandoc +RTS -M30m -RTS` will limit heap memory to 30MB. When converting a document requires more than this, an out of memory error will be issued. ## When using `--include-in-header` with PDF or LaTeX output, how do I reference tex declarations coming after `$header-includes$` in the default template? For various reasons, the `$header-includes$` are not at the very end of the LaTeX preamble. This poses a problem when the code you are inserting depends on declarations in the preamble coming after the `$header-includes$` location. For example, you might want to reference the `\author` and `\title` metadata values (set at the very bottom of the preamble) and present them in margins. In that case you can wrap your code in `etoolbox`'s `\AtEndPreamble`. The technique is demonstrated in [this gist](https://gist.github.com/JohnLukeBentley/9dda6166b9ee5c4127afd2b8cd16b70a). When using `\AtEndPreamble`, keep any `makeatletter` or `makeatother` outside of the `\AtEndPreamble`, as shown in the example. ## How can I convert PDFs to other formats using pandoc? You can't. You can try opening the PDF in Word or Google Docs and saving in a format from which pandoc can convert directly. ## Do I really need to install a 1 GB TeX installation to produce a PDF using pandoc? No. You can get by with a relatively small TeX installation, for example, by starting with MacTeX's Basic TeX distribution and using the `tlmgr` tool to install a few packages required by pandoc (see [the manual](https://pandoc.org/MANUAL.html#creating-a-pdf)). Or, you can produce PDFs via HTML and `wkhtmltopdf`, or via groff ms and `pdfroff`. (These don't produce as nice typography as TeX, particularly when it comes to math, but they may be fine for many purposes.) ## Converting to PDF on an M1 Mac, I get a "Cannot allocate memory" error. We are not sure why this happens, but we have found that fully specifying the `pdflatex` path avoids the error. For example, pandoc -o my.pdf --pdf-engine=/Library/TeX/texbin/pdflatex ## When I convert from ipynb, some visualizations aren't showing up. First, unless your target is a binary format (docx, odt, epub), you must use either `--extract-media` or (for HTML only) `--embed-resources` to make the images in the ipynb container available to your output file. Second, some Jupyter extensions, especially those that use JavaScript for visualizations, assume the presence of [`require.js`](https://github.com/requirejs/requirejs). To ensure that this script is available in your HTML output, you can use: ``` pandoc -s -o output.html input.ipynb \ -V header-includes='' ``` ## How can I get BibTeX references to work when converting from LaTeX? Use the `--citeproc` option. If it still doesn't work, you may need to tell pandoc where your bibliography file is using `--bibliography`. Your references may not be formatted the same as they are when you use `latex` and `bibtex`; you can change the format of the citations by specifying an appropriate CSL bibliography style using `--csl` (see [the manual](https://pandoc.org/MANUAL.html#specifying-a-citation-style)). ### How can I produce PDF/A with pandoc? The simplest approach is via ConTeXt: ``` pandoc --pdf-engine=context -V pdfa ``` Alternatively, `--pdf-engine=pdflatex` can be used with the following in `header-includes` in metadata (or included from a file using `--include-in-header`): ``` \usepackage[a-2u,mathxmp]{pdfx} \usepackage[pdfa]{hyperref} ``` Or `--pdf-engine=lualatex` can be used with the following: ``` \usepackage{hyperxmp} \hypersetup{pdfapart=3,pdfaconformance=B} \immediate\pdfobj stream attr{/N 3} file{sRGB.icc} \pdfcatalog{/OutputIntents [<< /Type /OutputIntent /S /GTS_PDFA1 /DestOutputProfile \the\pdflastobj\space 0 R /OutputConditionIdentifier (sRGB) /Info (sRGB) >>]} ``` ### Pandoc adds column widths to pipe tables when any line is wider than the setting for `--columns`. How can I prevent this? Save this filter as `nowidths.lua` and then pass `--lua-filter nowidths.lua` as an additional option to pandoc. (See [issue 8139](https://github.com/jgm/pandoc/issues/8139).) ``` lua -- Unset the width attribute of HTML colspecs in tables -- See https://github.com/jgm/pandoc/issues/8139 function Table (tbl) if PANDOC_VERSION[1] >= 2 and PANDOC_VERSION[2] >= 10 then tbl.colspecs = tbl.colspecs:map(function (colspec) local align = colspec[1] local width = nil -- default width return {align, width} end) else for i, w in ipairs(tbl.widths) do tbl.widths[i] = 0 end end return tbl end ``` ### How can I use pandoc to read Word files in the old .DOC format? Install `antiword` and use it to convert the doc to DocBook, which can be read by pandoc. ``` antiword -x db input.doc | pandoc -f docbook ``` ::: --- ## File: doc/filters.md % Pandoc filters % John MacFarlane # Summary Pandoc provides an interface for users to write programs (known as filters) which act on pandoc’s AST. Pandoc consists of a set of readers and writers. When converting a document from one format to another, text is parsed by a reader into pandoc’s intermediate representation of the document---an "abstract syntax tree" or AST---which is then converted by the writer into the target format. The pandoc AST format is defined in the module [`Text.Pandoc.Definition` in the `pandoc-types` package ](https://hackage.haskell.org/package/pandoc-types/docs/Text-Pandoc-Definition.html). A "filter" is a program that modifies the AST, between the reader and the writer. INPUT --reader--> AST --filter--> AST --writer--> OUTPUT Pandoc supports two kinds of filters: - **Lua filters** use the Lua language to define transformations on the pandoc AST. They are described in a [separate document](lua-filters.html). - **JSON filters**, described here, are pipes that read from standard input and write to standard output, consuming and producing a JSON representation of the pandoc AST: source format ↓ (pandoc) ↓ JSON-formatted AST ↓ (JSON filter) ↓ JSON-formatted AST ↓ (pandoc) ↓ target format Lua filters have a couple of advantages. They use a Lua interpreter that is embedded in pandoc, so you don't need to have any external software installed. And they are usually faster than JSON filters. But if you wish to write your filter in a language other than Lua, you may prefer to use a JSON filter. JSON filters may be written in any programming language. You can use a JSON filter directly in a pipeline: pandoc -s input.txt -t json | \ pandoc-citeproc | \ pandoc -s -f json -o output.html But it is more convenient to use the `--filter` option, which handles the plumbing automatically: pandoc -s input.txt --filter pandoc-citeproc -o output.html For a gentle introduction into writing your own filters, continue this guide. There’s also a [list of third party filters on the wiki](https://github.com/jgm/pandoc/wiki/Pandoc-Filters). # A simple example Suppose you wanted to replace all level 2+ headings in a markdown document with regular paragraphs, with text in italics. How would you go about doing this? A first thought would be to use regular expressions. Something like this: perl -pe 's/^##+ (.*)$/\*\1\*/' source.txt This should work most of the time. But don't forget that ATX style headings can end with a sequence of `#`s that is not part of the heading text: ## My heading ## And what if your document contains a line starting with `##` in an HTML comment or delimited code block? ~~~~ ### A third level heading in standard markdown ~~~~ We don't want to touch *these* lines. Moreover, what about Setext style second-level heading? A heading --------- We need to handle those too. Finally, can we be sure that adding asterisks to each side of our string will put it in italics? What if the string already contains asterisks around it? Then we'll end up with bold text, which is not what we want. And what if it contains a regular unescaped asterisk? How would you modify your regular expression to handle these cases? It would be hairy, to say the least. A better approach is to let pandoc handle the parsing, and then modify the AST before the document is written. For this, we can use a filter. To see what sort of AST is produced when pandoc parses our text, we can use pandoc's `native` output format: ~~~~ % cat test.txt ## my heading text with *italics* % pandoc -s -t native test.txt Pandoc (Meta {unMeta = fromList []}) [Header 2 ("my-heading",[],[]) [Str "My",Space,Str "heading"] , Para [Str "text",Space,Str "with",Space,Emph [Str "italics"]] ] ~~~~ A `Pandoc` document consists of a `Meta` block (containing metadata like title, authors, and date) and a list of `Block` elements. In this case, we have two `Block`s, a `Header` and a `Para`. Each has as its content a list of `Inline` elements. For more details on the pandoc AST, see the [haddock documentation for `Text.Pandoc.Definition`]. [haddock documentation for `Text.Pandoc.Definition`]: https://hackage.haskell.org/package/pandoc-types We can use Haskell to create a JSON filter that transforms this AST, replacing each `Header` block with level >= 2 with a `Para` with its contents wrapped inside an `Emph` inline: ~~~~ {.haskell} #!/usr/bin/env runhaskell -- behead.hs import Text.Pandoc.JSON main :: IO () main = toJSONFilter behead behead :: Block -> Block behead (Header n _ xs) | n >= 2 = Para [Emph xs] behead x = x ~~~~ The `toJSONFilter` function does two things. First, it lifts the `behead` function (which maps `Block -> Block`) onto a transformation of the entire `Pandoc` AST, walking the AST and transforming each block. Second, it wraps this `Pandoc -> Pandoc` transformation with the necessary JSON serialization and deserialization, producing an executable that consumes JSON from stdin and produces JSON to stdout. To use the filter, make it executable: chmod +x behead.hs and then pandoc -f SOURCEFORMAT -t TARGETFORMAT --filter ./behead.hs (It is also necessary that `pandoc-types` be installed in the local package repository. To do this using cabal-install, `cabal v2-update && cabal v2-install --lib pandoc-types --package-env .`.) Alternatively, we could compile the filter: ghc -package-env=default --make behead.hs pandoc -f SOURCEFORMAT -t TARGETFORMAT --filter ./behead Note that if the filter is placed in the system PATH, then the initial `./` is not needed. Note also that the command line can include multiple instances of `--filter`: the filters will be applied in sequence. # LaTeX for WordPress Another easy example. WordPress blogs require a special format for LaTeX math. Instead of `$e=mc^2$`, you need: `$LaTeX e=mc^2$`. How can we convert a markdown document accordingly? Again, it's difficult to do the job reliably with regexes. A `$` might be a regular currency indicator, or it might occur in a comment or code block or inline code span. We just want to find the `$`s that begin LaTeX math. If only we had a parser... We do. Pandoc already extracts LaTeX math, so: ~~~~ {.haskell} #!/usr/bin/env runhaskell -- wordpressify.hs import Text.Pandoc.JSON main = toJSONFilter wordpressify where wordpressify (Math x y) = Math x ("LaTeX " ++ y) wordpressify x = x ~~~~ Mission accomplished. (I've omitted type signatures here, just to show it can be done.) # But I don't want to learn Haskell! While it's easiest to write pandoc filters in Haskell, it is fairly easy to write them in python using the `pandocfilters` package. The package is in PyPI and can be installed using `pip install pandocfilters` or `easy_install pandocfilters`. Here's our "beheading" filter in python: ~~~ {.python} #!/usr/bin/env python """ Pandoc filter to convert all level 2+ headings to paragraphs with emphasized text. """ from pandocfilters import toJSONFilter, Emph, Para def behead(key, value, format, meta): if key == 'Header' and value[0] >= 2: return Para([Emph(value[2])]) if __name__ == "__main__": toJSONFilter(behead) ~~~ `toJSONFilter(behead)` walks the AST and applies the `behead` action to each element. If `behead` returns nothing, the node is unchanged; if it returns an object, the node is replaced; if it returns a list, the new list is spliced in. Note that, although these parameters are not used in this example, `format` provides access to the target format, and `meta` provides access to the document's metadata. There are many examples of python filters in [the pandocfilters repository](https://github.com/jgm/pandocfilters). For a more Pythonic alternative to pandocfilters, see the [panflute](https://pypi.org/project/panflute) library. Don't like Python? There are also ports of pandocfilters in - [PHP](https://github.com/vinai/pandocfilters-php), - [perl](https://metacpan.org/pod/Pandoc::Filter), - TypeScript/JavaScript via Node.js - [pandoc-filter](https://github.com/mvhenderson/pandoc-filter-node), - [node-pandoc-filter](https://github.com/mu-io/node-pandoc-filter), - [Groovy](https://github.com/dfrommi/groovy-pandoc), and - [Ruby](https://heerdebeer.org/Software/markdown/paru/). Starting with pandoc 2.0, pandoc includes built-in support for writing filters in lua. The lua interpreter is built in to pandoc, so a lua filter does not require any additional software to run. See the [documentation on lua filters](https://pandoc.org/lua-filters.html). # Include files So none of our transforms have involved IO. How about a script that reads a markdown document, finds all the inline code blocks with attribute `include`, and replaces their contents with the contents of the file given? ~~~~ {.haskell} #!/usr/bin/env runhaskell -- includes.hs import Text.Pandoc.JSON import qualified Data.Text.IO as TIO import qualified Data.Text as T doInclude :: Block -> IO Block doInclude cb@(CodeBlock (id, classes, namevals) contents) = case lookup (T.pack "include") namevals of Just f -> CodeBlock (id, classes, namevals) <$> TIO.readFile (T.unpack f) Nothing -> return cb doInclude x = return x main :: IO () main = toJSONFilter doInclude ~~~~ Try this on the following: Here's the pandoc README: ~~~~ {include="README"} this will be replaced by contents of README ~~~~ # Removing links What if we want to remove every link from a document, retaining the link's text? ~~~~ {.haskell} #!/usr/bin/env runhaskell -- delink.hs import Text.Pandoc.JSON main = toJSONFilter delink delink :: Inline -> [Inline] delink (Link _ txt _) = txt delink x = [x] ~~~~ Note that `delink` can't be a function of type `Inline -> Inline`, because the thing we want to replace the link with is not a single `Inline` element, but a list of them. So we make `delink` a function from an `Inline` element to a list of `Inline` elements. `toJSONFilter` can still lift this function to a transformation of type `Pandoc -> Pandoc`. # A filter for ruby text Finally, here's a nice real-world example, developed on the [pandoc-discuss](https://groups.google.com/group/pandoc-discuss/browse_thread/thread/7baea325565878c8) list. Qubyte wrote: > I'm interested in using pandoc to turn my markdown notes on Japanese > into nicely set HTML and (Xe)LaTeX. With HTML5, ruby (typically used to > phonetically read chinese characters by placing text above or to the > side) is standard, and support from browsers is emerging (Webkit based > browsers appear to fully support it). For those browsers that don't > support it yet (notably Firefox) the feature falls back in a nice way > by placing the phonetic reading inside brackets to the side of each > Chinese character, which is suitable for other output formats too. As > for (Xe)LaTeX, ruby is not an issue. > > At the moment, I use inline HTML to achieve the result when the > conversion is to HTML, but it's ugly and uses a lot of keystrokes, for > example > > ~~~ {.xml} > ご飯（はん） > ~~~ > > sets ご飯 "gohan" with "han" spelt phonetically above the second > character, or to the right of it in brackets if the browser does not > support ruby. I'd like to have something more like > > r[はん](飯) > > or any keystroke saving convention would be welcome. We came up with the following script, which uses the convention that a markdown link with a URL beginning with a hyphen is interpreted as ruby: [はん](-飯) ~~~ {.haskell} {-# LANGUAGE OverloadedStrings #-} -- handleruby.hs import Text.Pandoc.JSON import System.Environment (getArgs) import qualified Data.Text as T handleRuby :: Maybe Format -> Inline -> Inline handleRuby (Just format) x@(Link attr [Str ruby] (src,_)) = case T.uncons src of Just ('-',kanji) | format == Format "html" -> RawInline format $ "" <> kanji <> "(" <> ruby <> ")" | format == Format "latex" -> RawInline format $ "\\ruby{" <> kanji <> "}{" <> ruby <> "}" | otherwise -> Str ruby _ -> x handleRuby _ x = x main :: IO () main = toJSONFilter handleRuby ~~~ Note that, when a script is called using `--filter`, pandoc passes it the target format as the first argument. When a function's first argument is of type `Maybe Format`, `toJSONFilter` will automatically assign it `Just` the target format or `Nothing`. We compile our script: # first, make sure pandoc-types is installed: cabal install --lib pandoc-types --package-env . ghc --make handleRuby Then run it: % pandoc -F ./handleRuby -t html [はん](-飯) ^D 飯(はん) % pandoc -F ./handleRuby -t latex [はん](-飯) ^D \ruby{飯}{はん} Note: to use this to generate PDFs via LaTeX, you'll need to use `--pdf-engine=xelatex`, specify a `mainfont` that has the Japanese characters (e.g. "[Noto Sans CJK JP](https://fonts.google.com/noto/specimen/Noto+Sans+JP)"), and add `\usepackage{ruby}` to your template or header-includes. # Exercises 1. Put all the regular text in a markdown document in ALL CAPS (without touching text in URLs or link titles). 2. Remove all horizontal rules from a document. 3. Renumber all enumerated lists with roman numerals. 4. Replace each delimited code block with class `dot` with an image generated by running `dot -Tpng` (from graphviz) on the contents of the code block. 5. Find all code blocks with class `python` and run them using the python interpreter, printing the results to the console. # Technical details of JSON filters A JSON filter is any program which can consume and produce a valid pandoc JSON document representation. This section describes the technical details surrounding the invocation of filters. ## Arguments The program will always be called with the target format as the only argument. A pandoc invocation like pandoc --filter demo --to=html will cause pandoc to call the program `demo` with argument `html`. ## Environment variables Pandoc sets additional environment variables before calling a filter. `PANDOC_VERSION` : The version of the pandoc binary used to process the document. Example: `2.11.1`. `PANDOC_READER_OPTIONS` : JSON object representation of the options passed to the input parser. Object fields: `abbreviations` : set of known abbreviations (array of strings). `columns` : number of columns in terminal; an integer. `default-image-extension` : default extension for images; a string. `extensions` : integer representation of the syntax extensions bit field. `indented-code-classes` : default classes for indented code blocks; array of strings. `standalone` : whether the input was a standalone document with header; either `true` or `false`. `strip-comments` : HTML comments are stripped instead of parsed as raw HTML; either `true` or `false`. `tab-stop` : width (i.e. equivalent number of spaces) of tab stops; integer. `track-changes` : track changes setting for docx; one of `"accept-changes"`, `"reject-changes"`, and `"all-changes"`. ## Supported interpreters Files passed to the `--filter`/`-F` parameter are expected to be executable. However, if the executable bit is not set, then pandoc tries to guess a suitable interpreter from the file extension. file extension interpreter ---------------- -------------- .py `python` .hs `runhaskell` .pl `perl` .rb `ruby` .php `php` .js `node` .r `Rscript` --- ## File: doc/getting-started.md --- title: Getting started with pandoc author: John MacFarlane --- This document is for people who are unfamiliar with command line tools. Command-line experts can go straight to the [User's Guide](https://pandoc.org/MANUAL.html) or the pandoc man page. # Step 1: Install pandoc First, install pandoc, following the [instructions for your platform](https://pandoc.org/installing.html). # Step 2: Open a terminal Pandoc is a command-line tool. There is no graphic user interface. So, to use it, you'll need to open a terminal window: - On OS X, the Terminal application can be found in `/Applications/Utilities`. Open a Finder window and go to `Applications`, then `Utilities`. Then double click on `Terminal`. (Or, click the spotlight icon in the upper right hand corner of your screen and type `Terminal` -- you should see `Terminal` under `Applications`.) - On Windows, you can use either the classic command prompt or the more modern PowerShell terminal. If you use Windows in desktop mode, run the `cmd` or `powershell` command from the Start menu. If you use the Windows 8 start screen instead, simply type `cmd` or `powershell`, and then run either the "Command Prompt" or "Windows Powershell" application. If you are using `cmd`, type `chcp 65001` before using pandoc, to set the encoding to UTF-8. - On Linux, there are many possible configurations, depending on what desktop environment you're using: * In Unity, use the search function on the `Dash`, and search for `Terminal`. Or, use the keyboard shortcut `Ctrl-Alt-T`. * In Gnome, go to `Applications`, then `Accessories`, and select `Terminal`, or use `Ctrl-Alt-T`. * In XFCE, go to `Applications`, then `System`, then `Terminal`, or use `Super-T`. * In KDE, go to `KMenu`, then `System`, then `Terminal Program (Konsole)`. You should now see a rectangle with a "prompt" (possibly just a symbol like `%`, but probably including more information, such as your username and directory), and a blinking cursor. Let's verify that pandoc is installed. Type pandoc --version and hit enter. You should see a message telling you which version of pandoc is installed, and giving you some additional information. # Step 3: Changing directories First, let's see where we are. Type pwd on Linux or OSX, or echo %cd% on Windows, and hit enter. Your terminal should print your current working directory. (Guess what `pwd` stands for?) This should be your home directory. Let's navigate now to our `Documents` directory: type cd Documents and hit enter. Now type pwd (or `echo %cd%` on Windows) again. You should be in the `Documents` subdirectory of your home directory. To go back to your home directory, you could type cd .. The `..` means "one level up." Go back to your `Documents` directory if you're not there already. Let's try creating a subdirectory called `pandoc-test`: mkdir pandoc-test Now change to the `pandoc-test` directory: cd pandoc-test If the prompt doesn't tell you what directory you're in, you can confirm that you're there by doing pwd (or `echo %cd%`) again. OK, that's all you need to know for now about using the terminal. But here's a secret that will save you a lot of typing. You can always type the up-arrow key to go back through your history of commands. So if you want to use a command you typed earlier, you don't need to type it again: just use up-arrow until it comes up. Try this. (You can use down-arrow as well, to go the other direction.) Once you have the command, you can also use the left and right arrows and the backspace/delete key to edit it. Most terminals also support tab completion of directories and filenames. To try this, let's first go back up to our `Documents` directory: cd .. Now, type cd pandoc- and hit the tab key instead of enter. Your terminal should fill in the rest (`test`), and then you can hit enter. To review: - `pwd` (or `echo %cd%` on Windows) to see what the current working directory is. - `cd foo` to change to the `foo` subdirectory of your working directory. - `cd ..` to move up to the parent of the working directory. - `mkdir foo` to create a subdirectory called `foo` in the working directory. - up-arrow to go back through your command history. - tab to complete directories and file names. # Step 4: Using pandoc as a filter Type pandoc and hit enter. You should see the cursor just sitting there, waiting for you to type something. Type this: Hello *pandoc*! - one - two When you're finished (the cursor should be at the beginning of the line), type `Ctrl-D` on OS X or Linux, or `Ctrl-Z` followed by `Enter` on Windows. You should now see your text converted to HTML! Hello *pandoc*!
  • one
  • two
    • What just happened? When pandoc is invoked without specifying any input files, it operates as a "filter," taking input from the terminal and sending its output back to the terminal. You can use this feature to play around with pandoc. By default, input is interpreted as pandoc markdown, and output is HTML. But we can change that. Let's try converting *from* HTML *to* markdown: pandoc -f html -t markdown Now type: Hello *pandoc*! and hit `Ctrl-D` (or `Ctrl-Z` followed by `Enter` on Windows). You should see: Hello *pandoc*! Now try converting something from markdown to LaTeX. What command do you think you should use? # Step 5: Text editor basics You'll probably want to use pandoc to convert a file, not to read text from the terminal. That's easy, but first we need to create a text file in our `pandoc-test` subdirectory. **Important:** To create a text file, you'll need to use a text editor, *not* a word processor like Microsoft Word. On Windows, you can use Notepad (in `Accessories`). On OS X, you can use `TextEdit` (in `Applications`). On Linux, different platforms come with different text editors: Gnome has `GEdit`, and KDE has `Kate`. Start up your text editor. Type the following: --- title: Test ... # Test! This is a test of *pandoc*. - list one - list two Now save your file as `test1.md` in the directory `Documents/pandoc-test`. Note: If you use plain text a lot, you'll want a better editor than `Notepad` or `TextEdit`. You might want to look at [Visual Studio Code](https://code.visualstudio.com/) or [Sublime Text](https://www.sublimetext.com/) or (if you're willing to put in some time learning an unfamiliar interface) [Vim](https://www.vim.org) or [Emacs](https://www.gnu.org/software/emacs). # Step 6: Converting a file Go back to your terminal. We should still be in the `Documents/pandoc-test` directory. Verify that with `pwd`. Now type ls (or `dir` if you're on Windows). This will list the files in the current directory. You should see the file you created, `test1.md`. To convert it to HTML, use this command: pandoc test1.md -f markdown -t html -s -o test1.html The filename `test1.md` tells pandoc which file to convert. The `-s` option says to create a "standalone" file, with a header and footer, not just a fragment. And the `-o test1.html` says to put the output in the file `test1.html`. Note that we could have omitted `-f markdown` and `-t html`, since the default is to convert from markdown to HTML, but it doesn't hurt to include them. Check that the file was created by typing `ls` again. You should see `test1.html`. Now open this in a browser. On OS X, you can type open test1.html On Windows, type .\test1.html You should see a browser window with your document. To create a LaTeX document, you just need to change the command slightly: pandoc test1.md -f markdown -t latex -s -o test1.tex Try opening `test1.tex` in your text editor. Pandoc can often figure out the input and output formats from the filename extensions. So, you could have just used: pandoc test1.md -s -o test1.tex Pandoc knows you're trying to create a LaTeX document, because of the `.tex` extension. Now try creating a Word document (with extension `docx`). If you want to create a PDF, you'll need to have LaTeX installed. (See [MacTeX](https://tug.org/mactex/) on OS X, [MiKTeX](https://miktex.org) on Windows, or install the texlive package on Linux.) Then do pandoc test1.md -s -o test1.pdf # Step 7: Command-line options You now know the basics. Pandoc has a lot of options. At this point you can start to learn more about them by reading the [User's Guide](https://pandoc.org/MANUAL.html). Here's an example. The `--mathml` option causes pandoc to convert TeX math into MathML. Type pandoc --mathml then enter this text, followed by `Ctrl-D` (`Ctrl-Z` followed by `Enter` on Windows): $x = y^2$ Now try the same thing without `--mathml`. See the difference in output? If you forget an option, or forget which formats are supported, you can always do pandoc --help to get a list of all the supported options. On OS X or Linux systems, you can also do man pandoc to get the pandoc manual page. All of this information is also in the User's Guide. If you get stuck, you can always ask questions on the [discussion forum](https://github.com/jgm/pandoc/discussions). But be sure to check the [FAQs](https://pandoc.org/faqs.html) first, and search through the forum to see if your question has been answered before. --- ## File: doc/jats.md --- title: JATS author: Albert Krewinkel --- This document describes pandoc's handling of [JATS]. Metadata Values =============== `abstract` : Article summary. Added via the document's front matter via the [``][elem:abstract] element. `author` : list of article contributors. Each author should have a surname and a given name listed in the entry; if the author has no `surname` value, then the item will be used as the contributors [`string-name`][elem:string-name]. `orcid` : the contributor's ORCID identifier. `surname` : surname of the contributor. Usually the family name in western names. See [``][elem:surname]. `given-names` : personal names of the contributor; this includes middle names (if any) in western-style names. See [``][elem:given-names]. `name` : full name of the author; included only as a fallback if `author.surname` is not available. Tagged with [``][elem:string-name]. `email` : the contributor's email address. Used as the contents of the [``][elem:given-names] element. `affiliation` : either full affiliation entries as described in field `affiliation`, or a list of affiliation identifiers. The identifiers link to the organizations with which an author is affiliated. Each identifier in this list must also occur as the `id` of an affiliation listed in the top-level `affiliation` list. If the top-level `affiliation` field is set, then this entry assumed to be a list of identifiers, and a list of full entries if that field is unset. Full entries must be given if the articleauthoring tag set it used, as affiliation links are not allowed in that schema. `roles` : a list of dictionaries describing the author's role(s). Each role is added as an [``] element to the author's [``] element. The following examples illustrate: An ad-hoc role: ```yaml roles: - name: Dolphin Catcher ``` A role specified with CRediT. ```yaml roles: - credit: writing-review-editing ``` The `credit-name` is automatically looked up from the CRediT taxonomy, but you can also specify it yourself: ```yaml roles: - credit: writing-review-editing credit-name: Writing – review & editing ``` A role specified with CRediT, including an optional degree of contribution. Note that specifying the degree only is allowed when using CRediT roles and not ad-hoc roles. ```yaml roles: - credit: writing-review-editing degree: Lead ``` A role specified with CRediT with a label override, useful for internationalization: ```yaml roles: - credit: writing-review-editing name: Escrita – revisão e edição ``` The value for `credit` and `credit-name` must be from one of the 14 terms from the Contribution Role Taxonomy (CRediT): | `credit` | `credit-name` | |--------------------------|----------------------------| | `conceptualization` | Conceptualization | | `data-curation` | Data curation | | `formal-analysis` | Formal analysis | | `funding-acquisition` | Funding acquisition | | `investigation` | Investigation | | `methodology` | Methodology | | `project-administration` | Project administration | | `resources` | Resources | | `software` | Software | | `supervision` | Supervision | | `validation` | Validation | | `visualization` | Visualization | | `writing-original-draft` | Writing – original draft | | `writing-review-editing` | Writing – review & editing | JATS suggests in [``] to use one of the following three values when specifying the degree of contribution: 1. `Lead` 2. `Equal` 3. `Supporting` `equal-contrib` : boolean attribute used to mark authors who contributed equally to the work. The [`equal-contrib`][attr:equal-contrib] attribute, set to `yes`, is added to the author's [``] element if this is set to a truthy value. `cor-id` : identifier linking to the contributor's correspondence information. The info itself must be stored as an item in `article.author-notes.corresp`. If the `cor-id` value is set, then an [``][elem:xref] link of [`ref-type`][attr:ref-type] `corresp` is added. The [`rid`][attr:rid] attribute is set to `cor-`, where `` is the stringified value of this attribute. Furthermore, the [`corresp`][attr:corresp] attribute on the author's [``] element is set to `yes` if this attribute is set to a truthy. `affiliation` : the list of organizations with which contributors are affiliated. Each institution is added as an [``] element to the author's contrib-group. The fields are given in the order in which they are included in the output. `id` : internal identifier; used as the [``] element's `id` value, prefixed with `aff-`. `group` : name of the research group or other low-level organizational structure; used as value of an [``] element with [`content-type`][attr:content-type] set to `group`. `department` : name of the department or other mid-level organizational structure; used as value of an [``] element with [`content-type`][attr:content-type] set to `dept`. `organization` : name of the company, university, or other top-level organizational structure; used as value of an [``] element. The institution element is wrapped in an [``] element; any identifiers, like `ringgold` or `ror`, are added to the wrapper and must hence belong to this organization (not the department or group). `isni` : International Standard Name Identifier of the organization. Added via an [``] element with [`institution-id-type`](attr:institution-id-type) set to `ISNI`. `ringgold` : [Ringgold] identifier of the organization. Added via an [``] element with [`institution-id-type`](attr:institution-id-type) set to `Ringgold`. `ror` : Research Organization Registry identifier of the organization. Added via an [``] element with [`institution-id-type`](attr:institution-id-type) set to `ROR`. `pid` : Array of persistent identifiers which are added as [``] elements. Each item must contain a map with keys `type`, used as [`institution-id-type`](attr:institution-id-type), and `id`, used as element content. `street-address` : The organization's street address; each list item is wrapped in an [``] element, separated by a comma and space (`, `). `city` : City in which the organization is located; used only if `street-address` is not given, in which case the value is wrapped in a [``] element. `country` : Country in which the organization is located; used as the value of a [``] element. `country-code` : Two letter ISO-3166-1 country identifier; used as the [`country`][attr:country] attribute in element [``] (if the latter is present). `copyright` : Copyright and licensing information. This information is rendered via the [``][elem:permissions] element. It is recommended to use the `license` field (described below) for licensing information. If licensing information is included below `copyright`, then the variables `type`, `link`, and `text` should always be used together. `statement` : copyright notice or statement; used as content of the [``][elem:copyright-statement]. Use a list for multiple statements. `year` : the year of copyright; used as content of the [``][elem:copyright-year]. Use a list to for multiple copyright years. The JATS documentation states that this field need not to be used if the year is included in the copyright statement. `holder` : the copyright holder; included via the [``][elem:copyright-holder] element. Use a list for multiple copyright holders. `text` : inline text setting the license under which the text is published; included via the [``][elem:copyright-holder] element. `type` : type of the license; used as value of the [`license-type`][attr:license-type] attribute. `link` : external link describing the license; used as value of a `xlink:href` attribute in the `` element. `date` : publication date. This value should usually be a string representation of a date. Pandoc will parse and deconstruct the date into the components given below. It is also possible to pass these components directly. The publication date is recorded in the document via the [``] element and its sub-elements. The [`publication-format`][attr:publication-format] attribute is always set to `electronic`. `iso-8601` : ISO-8601 representation of the publication date. Used as the value of the [``] element's [`iso-8601-date`][attr:iso-8601-date] attribute. This value is set automatically if pandoc can parse the `date` value as a date. `day`, `month`, `year` : Day, month, and year of the publication date. Only the publication year is required. The values are used as the contents of the elements with the respective names. The values are set automatically if pandoc can parse the `date` value as a date. `type` : The type of event marked by this date. The value is set as the [`date-type`][attr:date-type] attribute on the [``] element and defaults to "pub" if not specified. `article` : information concerning the article that identifies or describes it. The key-value pairs within this map are typically used within the [``][elem:article-meta] element. `publisher-id` : external article identifier assigned by the publisher. Used as the content of the [``][elem:article-id] element with attribute [`pub-id-type`][attr:pub-id-type] set to `publisher-id`. `doi` : Digital Object Identifier (DOI) assigned to the article. Used as the content of the [``][elem:article-id] element with attribute [`pub-id-type`][attr:pub-id-type] set to `doi`. `pmid` : PubMed Identifier (PubMed ID) assigned to the article. Used as the content of the [``][elem:article-id] element with attribute [`pub-id-type`][attr:pub-id-type] set to `pmid`. `pmcid` : PubMed Central Identifier assigned to the article. Used as the content of the [``][elem:article-id] element with attribute [`pub-id-type`][attr:pub-id-type] set to `pmcid`. `art-access-id` : generic article accession identifier. Used as the content of the [``][elem:article-id] element with attribute [`pub-id-type`][attr:pub-id-type] set to `art-access-id`. `heading` : name of a subject or topic describing the article. Used as the content of the [``][elem:subject] element, nested in a [``][elem:subj-group] element which has `heading` as its [`subj-group-type`][attr:subj-group-type] attribute. `categories` : list a subject or topic describing the article. Items are each used as the content a the [``][elem:subject] element, grouped in a single [``][elem:subj-group] element with its [`subj-group-type`][attr:subj-group-type] attribute set to `categories`. `author-notes` : Additional information about authors, like conflict of interest statements and corresponding author contact info. Wrapped in an [``][elem:author-notes] element. `conflict` : Conflict of interest statement. Rendered as a footnote ([``][elem:fn]) of [`fn-type`](attr:fn-type) `conflict`. `con` : Contributed-by information. Rendered as a footnote ([``][elem:fn]) of [`fn-type`](attr:fn-type) `con`. `corresp` : Correspondence information. This must be a list of contributor correspondence items, where each item must have the properties `id` and `email`. The info is then rendered via a [``][elem:corresp] element. `funding-statement` : Prose describing the funding. Added to the article's frontmatter via the [`funding-statement`][elem:funding-statement] element. `journal` : information on the journal in which the article is published. This must be a map; the following key/value pairs are recognized. `publisher-id` : journal identifier assigned by the publisher. Used as content of element [``][elem:journal-id] with attribute [`journal-id-type`][attr:journal-id-type] set to `publisher-id`. `nlm-ta` : journal identifier assigned by PubMed. Used as content of element [``][elem:journal-id] with attribute [`journal-id-type`][attr:journal-id-type] set to `nlm-ta`. `pmc` : journal identifier assigned by PubMed Central. Used as content of element [``][elem:journal-id] with attribute [`journal-id-type`][attr:journal-id-type] set to `pmc`. `title` : full title of the journal in which the article is published. Used as content of the [``][elem:journal-title] element. `abbrev-title` : short form of the journal title. Used as content of the [``][elem:abbrev-journal-title] element. `pissn` : ISSN identifier of the publication's print version. Used as content of the [``][elem:issn] element with the [`publication-format`][attr:publication-format] attribute set to `print`. `eissn` : ISSN identifier of the publication's electronic version. Used as content of the [``][elem:issn] element with the [`publication-format`][attr:publication-format] attribute set to `electronic`. `publisher-name` : name of the publishing entity (person, company, or other). Used as the content of the [``][elem:publisher-name] element. `publisher-loc` : place of publication. Used as the content of the [``][elem:publisher-loc] element. `license` : Article licensing information. Each item of this field is rendered as a `` element within the [``][elem:permissions] element. Item content should be either a single paragraph, or a map with the fields listed below. `text` : inline text describing a license under which the text is published; included via the [``][elem:copyright-holder] element. `type` : type of the license; used as value of the [`license-type`][attr:license-type] attribute. `link` : external link describing the license; used as value of a `xlink:href` attribute in the `` element. `notes` : Additional notes concerning the whole article. Added to the article's frontmatter via the [``][elem:notes] element. `subtitle` : Subordinate part of the document title. Added to the document's front matter as a [``][elem:article-title] element. `tags` : list of keywords. Items are used as contents of the [``][elem:kwd] element; the elements are grouped in a [``][elem:kwd-group] with the [`kwd-group-type`][attr:kwd-group-type] value `author`. `title` : The article title. Added to the document's front matter via the [``][elem:article-title] element. `supplementary-material` : Supplementary metadata. Added to the document's front matter via the [``][elem:supplementary-material] element. Only available with `jats_articlepublishing`. `floats-group` : List of floating objects, such as figures, tables, text boxes, etc., that are not part of the main text. The value is rendered by nesting it below a [``][elem:floats-group] element. Only available with `jats_publishing` and `jats_archiving`. Required Metadata ----------------- Pandoc will try to generate a valid JATS document even when information is missing, filling in placeholders or using empty values. This circumvents the intend to ensure a minimum set of information being present in documents of a certain tag set. It is hence recommended to always provide the information listed below. ### Publishing Tag Set Required metadata values: - One or more of `journal.publisher-id`, `journal.nlm-ta`, `journal.pmc`. - One or more of `journal.pissn`, `journal.eissn`. [JATS]: https://jats.nlm.nih.gov/ [Ringgold]: https://ringgold.com/ [attr:content-type]: https://jats.nlm.nih.gov/publishing/tag-library/1.2/attribute/content-type.html [attr:corresp]: https://jats.nlm.nih.gov/publishing/tag-library/1.2/attribute/corresp.html [attr:date-type]: https://jats.nlm.nih.gov/publishing/tag-library/1.2/attribute/date-type.html [attr:equal-contrib]: https://jats.nlm.nih.gov/publishing/tag-library/1.2/attribute/equal-contrib.html [attr:fn-type]: https://jats.nlm.nih.gov/publishing/tag-library/1.2/attribute/fn-type.html [attr:institution-id-type]: https://jats.nlm.nih.gov/publishing/tag-library/1.2/attribute/institution-id-type.html [attr:iso-8601-date]: https://jats.nlm.nih.gov/publishing/tag-library/1.2/attribute/iso-8601-date.html [attr:journal-id-type]: https://jats.nlm.nih.gov/publishing/tag-library/1.2/attribute/journal-id-type.html [attr:kwd-group-type]: https://jats.nlm.nih.gov/publishing/tag-library/1.2/attribute/kwd-group-type.html [attr:license-type]: https://jats.nlm.nih.gov/publishing/tag-library/1.2/attribute/license-type.html [attr:pub-id-type]: https://jats.nlm.nih.gov/publishing/tag-library/1.2/attribute/pub-id-type.html [attr:publication-format]: https://jats.nlm.nih.gov/publishing/tag-library/1.2/attribute/publication-format.html [attr:ref-type]: https://jats.nlm.nih.gov/publishing/tag-library/1.2/attribute/ref-type.html [attr:rid]: https://jats.nlm.nih.gov/publishing/tag-library/1.2/attribute/rid.html [attr:subj-group-type]: https://jats.nlm.nih.gov/publishing/tag-library/1.2/attribute/subj-group-type.html [elem:abbrev-journal-title]: https://jats.nlm.nih.gov/publishing/tag-library/1.2/element/abbrev-journal-title.html [elem:abstract]: https://jats.nlm.nih.gov/publishing/tag-library/1.2/element/abstract.html [elem:article-id]: https://jats.nlm.nih.gov/publishing/tag-library/1.2/element/article-id.html [elem:article-meta]: https://jats.nlm.nih.gov/publishing/tag-library/1.2/element/article-meta.html [elem:article-title]: https://jats.nlm.nih.gov/publishing/tag-library/1.2/element/article-title.html [elem:supplementary-material]: https://jats.nlm.nih.gov/publishing/tag-library/1.2/element/supplementary-material.html [elem:copyright-holder]: https://jats.nlm.nih.gov/publishing/tag-library/1.2/element/copyright-holder.html [elem:copyright-statement]: https://jats.nlm.nih.gov/publishing/tag-library/1.2/element/copyright-statement.html [elem:copyright-year]: https://jats.nlm.nih.gov/publishing/tag-library/1.2/element/copyright-year.html [elem:corresp]: https://jats.nlm.nih.gov/publishing/tag-library/1.2/element/corresp.html [elem:email]: https://jats.nlm.nih.gov/publishing/tag-library/1.2/element/email.html [elem:floats-group]: https://jats.nlm.nih.gov/publishing/tag-library/1.2/element/floats-group.html [elem:fn]: https://jats.nlm.nih.gov/publishing/tag-library/1.2/element/fn.html [elem:funding-statement]: https://jats.nlm.nih.gov/publishing/tag-library/1.2/element/funding-statement.html [elem:given-names]: https://jats.nlm.nih.gov/publishing/tag-library/1.2/element/given-names.html [elem:issn]: https://jats.nlm.nih.gov/publishing/tag-library/1.2/element/issn.html [elem:journal-id]: https://jats.nlm.nih.gov/publishing/tag-library/1.2/element/journal-id.html [elem:journal-title]: https://jats.nlm.nih.gov/publishing/tag-library/1.2/element/journal-title.html [elem:kwd-group]: https://jats.nlm.nih.gov/publishing/tag-library/1.2/element/kwd-group.html [elem:kwd]: https://jats.nlm.nih.gov/publishing/tag-library/1.2/element/kwd.html [elem:license-p]: https://jats.nlm.nih.gov/publishing/tag-library/1.2/element/license-p.html [elem:license]: https://jats.nlm.nih.gov/publishing/tag-library/1.2/element/license.html [elem:notes]: https://jats.nlm.nih.gov/publishing/tag-library/1.2/element/notes.html [elem:permissions]: https://jats.nlm.nih.gov/publishing/tag-library/1.2/element/permissions.html [elem:publisher-loc]: https://jats.nlm.nih.gov/publishing/tag-library/1.2/element/publisher-loc.html [elem:publisher-name]: https://jats.nlm.nih.gov/publishing/tag-library/1.2/element/publisher-name.html [elem:string-name]: https://jats.nlm.nih.gov/publishing/tag-library/1.2/element/string-name.html [elem:subj-group]: https://jats.nlm.nih.gov/publishing/tag-library/1.2/element/subj-group.html [elem:subject]: https://jats.nlm.nih.gov/publishing/tag-library/1.2/element/subject.html [elem:subtitle]: https://jats.nlm.nih.gov/publishing/tag-library/1.2/element/subtitle.html [elem:surname]: https://jats.nlm.nih.gov/publishing/tag-library/1.2/element/surname.html [elem:xref]: https://jats.nlm.nih.gov/publishing/tag-library/1.2/element/xref.html [``]: https://jats.nlm.nih.gov/publishing/tag-library/1.2/element/addr-line.html [``]: https://jats.nlm.nih.gov/publishing/tag-library/1.2/element/aff.html [``]: https://jats.nlm.nih.gov/publishing/tag-library/1.2/element/city.html [``]: https://jats.nlm.nih.gov/publishing/tag-library/1.2/element/contrib.html [``]: https://jats.nlm.nih.gov/publishing/tag-library/1.2/element/country.html [``]: https://jats.nlm.nih.gov/publishing/tag-library/1.2/element/institution-id.html [``]: https://jats.nlm.nih.gov/publishing/tag-library/1.2/element/institution-wrap.html [``]: https://jats.nlm.nih.gov/publishing/tag-library/1.2/element/institution.html [``]: https://jats.nlm.nih.gov/publishing/tag-library/1.2/element/pub-date.html [``]: https://jats.nlm.nih.gov/publishing/tag-library/1.2/element/role.html [``]: https://jats.nlm.nih.gov/publishing/tag-library/1.2/attribute/degree-contribution.html