foliantcontrib.pandoc 1.0.5

Pandoc backend for Foliant doc maker. Produces PDF and DOCX.

Pandoc Backend for Foliant

Pandoc is a Swiss-army knife document converter. It converts almost any format to any other format: md to pdf, rst to html, adoc to docx, and so on and so on.

Pandoc backend for Foliant add pdf, docx, and tex targets.

Installation

$ pip install foliantcontrib.pandoc

You also need to install Pandoc and TeXLive distribution for your platform.

Usage

Build pdf:

$ foliant make pdf -p my-project
✔ Parsing config
✔ Applying preprocessor flatten
✔ Making pdf with Pandoc
─────────────────────
Result: My_Project-2017-12-04.pdf

Build docx:

$ foliant make docx -p my-project
✔ Parsing config
✔ Applying preprocessor flatten
✔ Making docx with Pandoc
─────────────────────
Result: My_Project-2017-12-04.docx

Build tex (mostly for pdf debugging):

$ foliant make tex -p my-project
✔ Parsing config
✔ Applying preprocessor flatten
✔ Making docx with Pandoc
─────────────────────
Result: My_Project-2017-12-04.tex

Config

You don't have to put anything in the config to use Pandoc backend. If it's installed, Foliant will detect it.

You can however customize the backend with options in backend_config.pandoc section:

backend_config:
  pandoc:
    pandoc_path: pandoc
    template: !path template.tex
    vars:
      ...
    reference_docx: !path reference.docx
    params:
      ...
    filters:
      ...
    markdown_flavor: markdown
    markdown_extensions:
      ...
    slug: My_Awesome_Custom_Slug

pandoc_path : is the path to pandoc executable. By default, it's assumed to be in the PATH.

template : is the path to the TeX template to use when building pdf and tex (see “Templates” in the Pandoc documentation).

> **Tip**
>
> Use `!path` tag to ensure the value is converted into a valid path relative to the project directory.

vars : is a mapping of template variables and their values.

reference_docx : is the path to the reference document to used when building docx (see “Templates” in the Pandoc documentation).

> **Tip**
>
> Use `!path` tag to ensure the value is converted into a valid path relative to the project directory.

params : are passed to the pandoc command. Params should be defined by their long names, with dashes replaced with underscores (e.g. --pdf-engine is defined as pdf_engine).

filters : is a list of Pandoc filters to be applied during build.

markdown_flavor : is the Markdown flavor assumed in the source. Default is markdown, Pandoc's extended Markdown. See “Markdown Variants” in the Pandoc documentation.

markdown_extensions : is a list of Markdown extensions applied to the Markdown source. See Pandoc’s Markdown in the Pandoc documentation.

slug : is the result file name without suffix (e.g. .pdf). Overrides top-level config option slug.

Example config:

backend_config:
  pandoc:
    template: !path templates/basic.tex
    vars:
      toc: true
      title: This Is a Title
      second_title: This Is a Subtitle
      logo: !path templates/logo.png
      year: 2017
    params:
      pdf_engine: xelatex
      listings: true
      number_sections: true
    markdown_extensions:
      - simple_tables
      - fenced_code_blocks
      - strikeout

Troubleshooting

Could not convert image ...: check that rsvg2pdf is in path

In order to use svg images in pdf, you need to have rsvg-convert executable in PATH.

On macOS, brew install librsvg does the trick. On Ubuntu, apt install librsvg2-bin. On Windows, download rsvg-convert.7z (without fontconfig support), unpack rsvg-convert.exe, and put it anywhere in PATH. For example, you can put it in the same directory where you run foliant make.