Skip to main content

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

Project description

# Pandoc Backend for Foliant

[Pandoc](http://pandoc.org/) 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

```shell
$ pip install foliantcontrib.pandoc
```

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

## Usage

Build pdf:

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

Build docx:

```shell
$ 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):

```shell
$ 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:

```yaml
backend_config:
pandoc:
binary_path: pandoc
template: !path template.tex
vars:
...
reference_docx: !path reference.docx
params:
...
filters:
...
markdown_flavor: markdown_strict
markdown_extensions:
...
```

`binary_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”](http://pandoc.org/MANUAL.html#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”](http://pandoc.org/MANUAL.html#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_strict`, which is the original Markdown by John Gruber. See [“Markdown Variants”](http://pandoc.org/MANUAL.html#markdown-variants) in the Pandoc documentation.

`markdown_extensions`
: is a list of Markdown extensions applied to the Markdown source. See [Pandoc’s Markdown](http://pandoc.org/MANUAL.html#pandocs-markdown) in the Pandoc documentation.

Example config:

```yaml
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`](http://opensourcepack.blogspot.ru/2012/06/rsvg-convert-svg-image-conversion-tool.html) (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`.

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

foliantcontrib.pandoc-1.0.1.tar.gz (4.3 kB view details)

Uploaded Source

Built Distribution

foliantcontrib.pandoc-1.0.1-py3-none-any.whl (6.7 kB view details)

Uploaded Python 3

File details

Details for the file foliantcontrib.pandoc-1.0.1.tar.gz.

File metadata

File hashes

Hashes for foliantcontrib.pandoc-1.0.1.tar.gz
Algorithm Hash digest
SHA256 4a4d7faa9bfb8e9972ac4151952fb797127503fe4a663e489b0d81a564e1cabb
MD5 ccfcb450548dd14886bf6492f9953644
BLAKE2b-256 b1ae8c1931b5d9a2a33b901dd426c6dad82820e1d8a68c5bd24cf1082ea4bf52

See more details on using hashes here.

File details

Details for the file foliantcontrib.pandoc-1.0.1-py3-none-any.whl.

File metadata

File hashes

Hashes for foliantcontrib.pandoc-1.0.1-py3-none-any.whl
Algorithm Hash digest
SHA256 cca67c370e388687dbd473c582d7d1ae58aacb79899d0126e11f21634e0416fa
MD5 2920bdb7dcb009dde7b49a226f3e32fa
BLAKE2b-256 6d10909a5e0dcc42f8b4e6944631ae24df8bf8009aee10c1549338d2c5e50e68

See more details on using hashes here.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Pingdom Monitoring Sentry Error logging StatusPage Status page