Pandoc backend for Foliant doc maker. Produces PDF and DOCX.
Project description
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
.
LaTeX listings package does not work correctly with non-ASCII characters, e.g. Cyrillic letters
If you use non-ASCII characters inside backticks in your document, you can see an error like this:
Error producing PDF.
! Undefined control sequence.
\lst@arg ->git clone [SSH-к
люч]
l.627 ...through{\lstinline!git clone [SSH-ключ]!}
To fix it, set listings
parameter to false
:
backend_config:
pandoc:
...
params:
pdf_engine: xelatex
listings: false
number_sections: true
...
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for foliantcontrib.pandoc-1.0.11.tar.gz
Algorithm | Hash digest | |
---|---|---|
SHA256 | 27f226ece91528fa078d7006dc2a66fb8551a4e3894c8ae2185b660818eeebe8 |
|
MD5 | 2f44e8f4258003a6b714949178cbf832 |
|
BLAKE2b-256 | 2c92a04c102b6e176e3498c458274102e54cfe820df6b598581e42ac5f4d484b |
Hashes for foliantcontrib.pandoc-1.0.11-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | a5cb2006d5ea1d4a08839c41e790ba9c0d671346aaddfdbf9dffb61b789b3a9f |
|
MD5 | 60854476e8c7c0c32ee7841596cfd2ad |
|
BLAKE2b-256 | b195b06fff857b591d8c5f531aabb684df561591306c9a00c603b35e59a4a6f0 |