Skip to main content

Pandoc filter to allow file and header includes

Project description


PyPI PyPI - Downloads GitHub

Pandoc filter to allow file and header includes.

The filter script is based on User Guide for Panflute. This repository is to provide a simple way to install and use it.


  • Recursive include (supported from v0.4.0): It depends on include-entry header to work
  • Yaml header Merging (supported from v0.5.0): When an included file has its header, it will be merged into the current header. If there's a conflict, the original header of the current file remains.
  • Header include (supported from v0.6.0): Use !include-header file.yaml to include Yaml header from file.


First, install python and python-pip.

Then, use pip to install:

pip install --user pandoc-include

After installation, make sure that the pandoc-include executable is put in the directory which is in the PATH environment.



To use this filter, add to pandoc command

pandoc --filter pandoc-include -o output.pdf

Header option

include-entry: 'path'

This option is to make recursive includes work.

The include-entry option is a path relative to current working directory or absolute where the entry file (the initial file) locates. It should be placed in the entry file only, not in the included files. It is optional and the default include-entry value is ..

For example, to compile a file in current directory, no header is needed:

pandoc --filter pandoc-include -o test.pdf

However, to compile a file not in current directory, like:

pandoc dir/ --filter pandoc-include -o test.pdf

The header should now be set to: include-entry: 'dir'.


Each include statement has its own line and has the syntax:

!include somefolder/somefile

!include-header file.yaml


$include somefolder/somefile

$include-header file.yaml

Each include statement must be in its own paragraph. That is, in its own line and separated by blank lines.

The path can be either absolute or relative to the current file's directory. (If the include statement is in an included file, then the path is relative to the included file itself.) If no extension was given, ".md" is assumed.


File include

File include can be used to separate chapters into different files, or include some latex files:

title: Article
author: Author
toc: true

!include chapters/

!include chapters/

!include chapters/

!include data/table.tex

Recursive include is supported from v0.4.0.

Header include

For header include, it is useful to define a header template and include it in many files.

For example, in the header.yaml, we can define basic info:

name: xxx
school: yyy
email: zzz

In the, we can extend the header:

title: Title

!include-header header.yaml

# Section


The then is equivalent to the follow markdown:

title: Title
name: xxx
school: yyy
email: zzz

# Section


Note: The second syntax may lead to wrong highlighting when using a markdown editor. If it happens, use the first syntax.


MIT License

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

pandoc-include-0.6.1.tar.gz (4.2 kB view hashes)

Uploaded Source

Built Distribution

pandoc_include-0.6.1-py3-none-any.whl (5.1 kB view hashes)

Uploaded Python 3

Supported by

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