mirror of
https://github.com/jgm/pandoc.git
synced 2026-09-19 02:22:09 +08:00
Albert KrewinkelandAner Lucero
909ced5153
Thanks and credit go to Aner Lucero, who laid the groundwork for this feature in the 2021 GSoC project. He contributed many changes, including modifications to the readers for HTML, JATS, and LaTeX, and to the HTML and JATS writers. Shared (Albert Krewinkel): - The new function `figureDiv`, exported from `Text.Pandoc.Shared`, offers a standardized way to convert a figure into a Div element. Readers (Aner Lucero): - HTML reader: `<figure>` elements are parsed as figures, with the caption taken from the respective `<figcaption>` elements. - JATS reader: The `<fig>` and `<caption>` elements are parsed into figure elements, even if the contents is more complex. - LaTeX reader: support for figures with non-image contents and for subfigures. - Markdown reader: paragraphs containing just an image are treated as figures if the `implicit_figures` extension is enabled. The identifier is used as the figure's identifier and the image description is also used as figure caption; all other attributes are treated as belonging to the image. Writers (Aner Lucero, Albert Krewinkel): - DokuWiki, Haddock, Jira, Man, MediaWiki, Ms, Muse, PPTX, RTF, TEI, ZimWiki writers: Figures are rendered like Div elements. - Asciidoc writer: The figure contents is unwrapped; each image in the the figure becomes a separate figure. - Classic custom writers: Figures are passed to the global function `Figure(caption, contents, attr)`, where `caption` and `contents` are strings and `attr` is a table of key-value pairs. - ConTeXt writer: Figures are wrapped in a "placefigure" environment with `\startplacefigure`/`\endplacefigure`, adding the features caption and listing title as properties. Subfigures are place in a single row with the `\startfloatcombination` environment. - DocBook writer: Uses `mediaobject` elements, unless the figure contains subfigures or tables, in which case the figure content is unwrapped. - Docx writer: figures with multiple content blocks are rendered as tables with style `FigureTable`; like before, single-image figures are still output as paragraphs with style `Figure` or `Captioned Figure`, depending on whether a caption is attached. - DokuWiki writer: Caption and "alt-text" are no longer combined. The alt text of a figure will now be lost in the conversion. - FB2 writer: The figure caption is added as alt text to the images in the figure; pre-existing alt texts are kept. - ICML writer: Only single-image figures are supported. The contents of figures with additional elements gets unwrapped. - HTML writer: the alt text is no longer constructed from the caption, as was the case with implicit figures. This reduces duplication, but comes at the risk of images that are missing alt texts. Authors should take care to provide alt texts for all images. Some readers, most notably the Markdown reader with the `implicit_figures` extension, add a caption that's identical to the image description. The writer checks for this and adds an `aria-hidden` attribute to the `<figcaption>` element in that case. - JATS writer: The `<fig>` and `<caption>` elements are used write figures. - LaTeX writer: complex figures, e.g. with non-image contents and subfigures, are supported. The `subfigure` template variable is set if the document contains subfigures, triggering the conditional loading of the *subcaption* package. Contants of figures that contain tables are become unwrapped, as longtable environments are not allowed within figures. - Markdown writer: figures are output as implicit figures if possible, via HTML if the `raw_html` extension is enabled, and as Div elements otherwise. - OpenDocument writer: A separate paragraph is generated for each block element in a figure, each with style `FigureWithCaption`. Behavior for single-image figures therefore remains unchanged. - Org writer: Only the first element in a figure is given a caption; additional block elements in the figure are appended without any caption being added. - RST writer: Single-image figures are supported as before; the contents of more complex images become nested in a container of type `float`. - Texinfo writer: Figures are rendered as float with type `figure`. - Textile writer: Figures are rendered with the help of HTML elements. - XWiki: Figures are placed in a group. Co-authored-by: Aner Lucero <4rgento@gmail.com>
Pandoc
The universal markup converter
Pandoc is a Haskell library for converting from one markup format to another, and a command-line tool that uses this library. It can convert from
bibtex(BibTeX bibliography)biblatex(BibLaTeX bibliography)commonmark(CommonMark Markdown)commonmark_x(CommonMark Markdown with extensions)creole(Creole 1.0)csljson(CSL JSON bibliography)csv(CSV table)tsv(TSV table)docbook(DocBook)docx(Word docx)dokuwiki(DokuWiki markup)endnotexml(EndNote XML bibliography)epub(EPUB)fb2(FictionBook2 e-book)gfm(GitHub-Flavored Markdown), or the deprecated and less accuratemarkdown_github; usemarkdown_githubonly if you need extensions not supported ingfm.haddock(Haddock markup)html(HTML)ipynb(Jupyter notebook)jats(JATS XML)jira(Jira/Confluence wiki markup)json(JSON version of native AST)latex(LaTeX)markdown(Pandoc’s Markdown)markdown_mmd(MultiMarkdown)markdown_phpextra(PHP Markdown Extra)markdown_strict(original unextended Markdown)mediawiki(MediaWiki markup)man(roff man)muse(Muse)native(native Haskell)odt(ODT)opml(OPML)org(Emacs Org mode)ris(RIS bibliography)rtf(Rich Text Format)rst(reStructuredText)t2t(txt2tags)textile(Textile)tikiwiki(TikiWiki markup)twiki(TWiki markup)vimwiki(Vimwiki)- the path of a custom Lua reader, see Custom readers and writers below
It can convert to
asciidoc(AsciiDoc) orasciidoctor(AsciiDoctor)beamer(LaTeX beamer slide show)bibtex(BibTeX bibliography)biblatex(BibLaTeX bibliography)commonmark(CommonMark Markdown)commonmark_x(CommonMark Markdown with extensions)context(ConTeXt)csljson(CSL JSON bibliography)docbookordocbook4(DocBook 4)docbook5(DocBook 5)docx(Word docx)dokuwiki(DokuWiki markup)epuborepub3(EPUB v3 book)epub2(EPUB v2)fb2(FictionBook2 e-book)gfm(GitHub-Flavored Markdown), or the deprecated and less accuratemarkdown_github; usemarkdown_githubonly if you need extensions not supported ingfm.haddock(Haddock markup)htmlorhtml5(HTML, i.e. HTML5/XHTML polyglot markup)html4(XHTML 1.0 Transitional)icml(InDesign ICML)ipynb(Jupyter notebook)jats_archiving(JATS XML, Archiving and Interchange Tag Set)jats_articleauthoring(JATS XML, Article Authoring Tag Set)jats_publishing(JATS XML, Journal Publishing Tag Set)jats(alias forjats_archiving)jira(Jira/Confluence wiki markup)json(JSON version of native AST)latex(LaTeX)man(roff man)markdown(Pandoc’s Markdown)markdown_mmd(MultiMarkdown)markdown_phpextra(PHP Markdown Extra)markdown_strict(original unextended Markdown)markua(Markua)mediawiki(MediaWiki markup)ms(roff ms)muse(Muse)native(native Haskell)odt(OpenOffice text document)opml(OPML)opendocument(OpenDocument)org(Emacs Org mode)pdf(PDF)plain(plain text)pptx(PowerPoint slide show)rst(reStructuredText)rtf(Rich Text Format)texinfo(GNU Texinfo)textile(Textile)slideous(Slideous HTML and JavaScript slide show)slidy(Slidy HTML and JavaScript slide show)dzslides(DZSlides HTML5 + JavaScript slide show)revealjs(reveal.js HTML5 + JavaScript slide show)s5(S5 HTML and JavaScript slide show)tei(TEI Simple)xwiki(XWiki markup)zimwiki(ZimWiki markup)- the path of a custom Lua writer, see 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.
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 and Lua filters).
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.
Documentation
Pandoc’s website contains a full User’s Guide. It is also available here as pandoc-flavored Markdown. The website also contains some examples of the use of pandoc and a limited online demo.
Contributing
Pull requests, bug reports, and feature requests are welcome. Please make sure to read the contributor guidelines before opening a new issue.
License
© 2006-2022 John MacFarlane (jgm@berkeley.edu). Released under the GPL, version 2 or greater. This software carries no warranty of any kind. (See COPYRIGHT for full copyright and warranty notices.)