Skip to main content

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

Project description

Pandoc Backend for Foliant

PDF built with 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


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.11.tar.gz (5.0 kB view details)

Uploaded Source

Built Distribution

foliantcontrib.pandoc-1.0.11-py3-none-any.whl (5.7 kB view details)

Uploaded Python 3

File details

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

File metadata

  • Download URL: foliantcontrib.pandoc-1.0.11.tar.gz
  • Upload date:
  • Size: 5.0 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/1.13.0 pkginfo/1.5.0.1 requests/2.11.1 setuptools/41.0.1 requests-toolbelt/0.9.1 tqdm/4.32.2 CPython/3.6.8

File hashes

Hashes for foliantcontrib.pandoc-1.0.11.tar.gz
Algorithm Hash digest
SHA256 27f226ece91528fa078d7006dc2a66fb8551a4e3894c8ae2185b660818eeebe8
MD5 2f44e8f4258003a6b714949178cbf832
BLAKE2b-256 2c92a04c102b6e176e3498c458274102e54cfe820df6b598581e42ac5f4d484b

See more details on using hashes here.

File details

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

File metadata

  • Download URL: foliantcontrib.pandoc-1.0.11-py3-none-any.whl
  • Upload date:
  • Size: 5.7 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/1.13.0 pkginfo/1.5.0.1 requests/2.11.1 setuptools/41.0.1 requests-toolbelt/0.9.1 tqdm/4.32.2 CPython/3.6.8

File hashes

Hashes for foliantcontrib.pandoc-1.0.11-py3-none-any.whl
Algorithm Hash digest
SHA256 a5cb2006d5ea1d4a08839c41e790ba9c0d671346aaddfdbf9dffb61b789b3a9f
MD5 60854476e8c7c0c32ee7841596cfd2ad
BLAKE2b-256 b195b06fff857b591d8c5f531aabb684df561591306c9a00c603b35e59a4a6f0

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