No Description

Baldur Kristinsson e0b6a52bba Merge pull request #23 from mletterle/format-arg 2 weeks ago
.gitignore 694c55ff3b Initial commit 5 years ago
AUTHORS 8d21124ed1 Added lollipopman to AUTHORS; documentation change 2 years ago
CHANGELOG 9292e45cea v0.5.1 in Changelog 2 years ago
RELEASE c10892c3cd enhance metadata for the project 3 years ago
mathml.js bed1c99d64 add sources 5 years ago
page.tmpl 36cc9ef83d Replacement page template with support for all math rendering modes 3 years ago
pandoc.pm e0b6a52bba Merge pull request #23 from mletterle/format-arg 2 weeks ago

# ikiwiki-pandoc

Pandoc plugin for ikiwiki.

Pandoc has a richer syntax and more flexible configuration than standard Markdown, and is also able to parse a variety of other syntaxes. This plugin can be configured to generate wiki pages from LaTeX, reST, mediawiki, textile, OPML or Emacs Org sources, as well as markdown. It can also be configured to convert and display inline TeX math using a variety of methods. If Pandoc was compiled with the -fhighlighting option, it will also apply syntax highlighting to code blocks and inline code spans. Finally, it is possible to export the content of a wiki page to several of the non-HTML formats supported by pandoc, including pdf and docx, or to create slideshows using Beamer and reveal.js.

## Install

# (1) Install the library.
# Alternatively, can be installed in /usr/share/perl5 or similar.
#
mkdir -p ~/.ikiwiki/IkiWiki/Plugin
cp pandoc.pm ~/.ikiwiki/IkiWiki/Plugin

# (2) Install template (for math support).
# $TEMPLATEDIR is often /usr/share/ikiwiki/templates by default. # Check the templatedir setting of your *.setup file. # mv$TEMPLATEDIR/page.tmpl $TEMPLATEDIR/page.tmpl.orig cp page.tmpl$TEMPLATEDIR

# (3) Possibly install javascript (only for mathml).
# $UNDERLAYDIR is often /usr/share/ikiwiki and depends on the # settings underlaydir and add_underlays in your *.setup file # cp *.js$UNDERLAYDIR/javascript/

# (4) Activate module:
#     add 'pandoc' to add_plugins list in your *.setup file

# Between those two commands, you may want to tweak some options.
#
ikiwiki --changesetup *.setup
ikiwiki --rebuild --setup *.setup


Note: If you want to put mathematics markup into your pages or blog entries, you are likely to run into problems with the smiley plugin, so you should probably disable it by adding it to the disable_plugins list in your *.setup file.

## Updating to a newer version

Start by examining which files have changed since you last installed or updated the plugin. For each such file, repeat the relevant installation steps. If in doubt, repeat them all (i.e. steps 1–3 from above).

If ikiwiki-pandoc now supports options which have been added since your previous installation/update, you may wish to take the time to refresh your setup file as well by carrying out step 5 above, possibly followed by changing the new options from their default values.

## Options

The following options are available in the *.setup file. Some of them are also available in the web settings.

### Program paths

• pandoc_command (string): Path to pandoc executable. If not set, looks for pandoc in your $PATH. • pandoc_citeproc (string): Path to pandoc-citeproc executable (for references/bibliography handling). If not set, looks for it in $PATH.

### Input format support

• pandoc_markdown_ext (string): Markdown file extension(s) for pandoc handling. Multiple comma-separated extensions may be specified, e.g. md,mdwn,markdown,pd.

• pandoc_rst (boolean): If true, enables processing of ReST documents (fixed extension: .rst).

• pandoc_latex (boolean): If true, enables processing of LaTeX documents (fixed extension: .tex).

• pandoc_textile (boolean): If true, enables processing of textile documents (fixed extension: .textile).

• pandoc_mediawiki (boolean): If true, enables processing of MediaWiki documents (fixed extension: .mediawiki).

• pandoc_org (boolean): If true, enables processing of Emacs Org-mode documents (fixed extension: .org).

• pandoc_opml (boolean): If true, enables processing of OPML documents (fixed extension: .opml).

### Settings for mathematics display

Pandoc's variant of markdown supports TeX math delimited with $...$ (inline math) and $$...$$ (display math). There are several possibilities with regard to the way in which this appears in the HTML output. For a more detailed description, see later in this document.

These settings have no effect unless you have activated the page.tmpl file which comes with this module (or have inserted an appropriate math support block into your own template).

• pandoc_math (string): base setting for math support. Can be one of mathjax, katex, mathml, asciimathml, jsmath, latexmathml, mimetex, or webtex. For most people, mathjax is recommended.

• pandoc_math_custom_js (string): Optionally specify a javascript URL to load support for the math display option specified under pandoc_math. You would use this if you e.g. have a local version of MathJax or KaTeX. If you have picked mathml, it would probably be sensible to point to the mathml.js script which comes with this module. For mimetex and webtex, this setting should not point to a javascript file but to a server-side (CGI) URL which returns an image for insertion into the page at the appropriate point.

• pandoc_math_custom_css: Optional custom CSS URL to control the appearances of math.

### Settings for references and bibliography

• pandoc_bibliography (string): Full path to the (BibTeX-format) bibliography file to use by default. If this is empty, you must specify either bibliography (filename) or references (structured list of references) in a YAML meta-block in the page itself.

• pandoc_csl (string): CSL file to use by default to format in-line references and the list of references. If this is empty, the default Chicago author-year format will be used, unless you specify a CSL file using csl in a YAML meta-block in the page itself.

• pandoc_csl_default_lang (string): Language code to use by default during citations processing, unless something different is specified in the YAML meta block (using either of the keys lang or locale). Language codes follow RFC 1766 and are typically either two letters (e.g. en for English) or two letters followed by a hyphen and a refinement code (e.g. en-GB for British English). If no language code is configured here, pandoc-citeproc uses the default language of the preferred CSL file, or US English (en-US) if it specifies no default language. Underscore may be used instead of a hyphen in language codes, so en-GB and en_GB are equivalent. Pandoc-citeproc supports almost 50 major European and Asian languages.

### Output tweaking

• pandoc_smart (boolean): Whether smart quotes and other typographic niceties are enabled.

• pandoc_obfuscate (boolean): Whether to detect and obfuscate email adresses automatically.

• pandoc_html5 (boolean): Whether Pandoc should produce HTML5.

• pandoc_ascii (boolean): Produce ASCII output rather than UTF-8.

• pandoc_numsect (boolean): Whether to number sections.

• pandoc_sectdiv (boolean): Attach IDs to section DIVs instead of to headers.

• pandoc_codeclasses (string): CSS classes to add to indented code blocks. One may also specify CSS classes individually for each block.

• pandoc_html_extra_options: Extra pandoc options that are specific for HTML and do not apply to other output formats. (Note that this, like other *_extra_options, is a list, not simply a string). You may also set this option per page in the yaml metadata block using the key html_extra_options. Note that a per-page setting (even if it is an empty list) overrides the global setting rather than extending it.

### Extra output formats

It is sometimes useful to use pandoc to export the content of a wiki page to non-html formats, e.g. pdf or docx. This can be triggered by setting certain attributes in the YAML meta block of the page. The currently supported formats are pdf, docx, odt, latex, beamer, revealjs and epub. The corresponding meta attributes are the boolean values generate_pdf, generate_docx, generate_odt, generate_latex, generate_beamer, generate_revealjs and generate_epub. As a shortcut, generate_all_formats will turn on the generation of all seven formats; some of them may then be turned off individually. For instance,

generate_all_formats: true
generate_beamer: false
generate_revealjs: false


will export files of all formats except Beamer and reveal.js.

When such extra formats have been generated for a page, links to the exported files will be appended to the so-called action links ("Edit", "History", etc.). These links are at the top of the page in the default theme.

#### Configuration options

There are several configuration options related to the export functionality:

• pandoc_latex_template: Path to pandoc template for LaTeX and PDF output. Since PDF files are created by way of LaTeX, there is no separate PDF template. (Obviously, PDF generation requires a working LaTeX installation).

• pandoc_latex_extra_options: List of extra pandoc options for LaTeX and PDF generation. (Note that this, like other *_extra_options, is a list, not simply a string).

• pandoc_beamer_template: Path to pandoc template for Beamer PDF output. (Beamer is a presentations package for LaTeX).

• pandoc_beamer_extra_options: List of extra pandoc options for Beamer PDF generation.

• pandoc_pdf_export_cleanup: Whether to cleanup LaTeX auxiliary files after doing a PDF export (including Beamer). The default is to keep this False, since it often speeds PDF regeneration up considerably when updating a page.

• pandoc_revealjs_template: Path to pandoc template for Reveal.js slides output.

• pandoc_revealjs_extra_options: List of extra pandoc options for Reveal.js slides generation. Please note that the option --self-contained is added automatically. In order for this to work, pandoc has to know where to find the reveal.js Javascript and CSS files. The easiest way of making sure of this is to keep them in pandoc's default user data directory. You can see the name of this folder by running pandoc --version; usually it is ~/.pandoc, in which case the reveal.js files would be in the subdirectory ~/.pandoc/reveal.js/. You can download the most recent reveal.js release here.

• pandoc_docx_template: Path to reference docx document used by pandoc for MS Word output.

• pandoc_docx_extra_options: List of extra pandoc options for docx generation.

• pandoc_odt_template: Path to reference odt document used by pandoc for OpenDocument output for LibreOffice, OpenOffice, etc.

• pandoc_odt_extra_options: List of extra pandoc options for odt generation.

• pandoc_epub_template: Path to pandoc template for epub output. (Note that the this will actually generate EPUB3 files rather than the more familiar EPUB2. The reason is that EPUB3 has better native math support).

• pandoc_epub_extra_options: List of extra pandoc options for epub generation.

#### Overriding settings on a specific page

It is possible to override and/or extend the settings for an output format on a given page, using meta attributes with the same names as the configuration options above, except without the pandoc_* prefix. As an example, consider the YAML metadata block below:

title: The Communist Manifesto
author:
- Karl Marx
- Friedrich Engels
date: 1848-02-21
lang: en-GB
bibliography: /home/km/bib/communism.bib
generate_pdf: true
generate_docx: true
latex_template: booklet_tpl.latex
latex_extra_options:
- -\-biblatex
- -\-variable=biblio-style:authoryear
docx_template: manifesto_tpl.docx


Here, the latex_template setting (which controls both pdf and latex output) will replace whatever was configured in the *.setup file under pandoc_latex_template, while the latex_extra_options setting will be added to the list of extra arguments (if any) specified in pandoc_latex_extra_options.

Also note that pandoc interprets string values in the meta block as markdown, which is why we need to backslash-escape one of the leading hyphens in each option. Otherwise, -- will be turned into – (an ndash) during meta parsing, at least if the pandoc_smart configuration option is turned on, with predictably undesireable results.



GPLv2. See LICENSE for more details.