Pandoc filter to allow file and header includes
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.
- Include as raw blocks
- Indent and dedent included contents
- Partial include: Allow including only parts of the file using options
- Code include: Allow using
!includein code blocks
- Unix style pathname
- Recursive include: It depends on
include-entryheader to work
- Yaml header Merging: 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: Use
!include-header file.yamlto include Yaml header from file.
Then, use pip to install:
pip install --user pandoc-include
make sure that the
pandoc-include executable is put in the directory which is in the PATH environment.
To install the current (development) version hosted on the repository, use
pip install --upgrade --force --no-cache git+https://github.com/DCsunset/pandoc-include
You can use
pip show pandoc-include
to check the version currently installed.
To use this filter, add to pandoc command
pandoc input.md --filter pandoc-include -o output.pdf
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.
For code include, use
!include statement in a code block:
```cpp !include filename.cpp ```
The path can be either absolute or relative to the current file's directory. Besides, unix-style pathname can used. (If the include statement is used in an included file, then the path is absolute or relative to the included file itself.)
If there are special characters in the filename, use quotes:
!include "filename with space" !include 'filename"with"quotes'
The second syntax may lead to wrong highlighting when using a markdown editor. If it happens, use the first syntax. Also make sure that there are no circular includes.
!include command also supports options:
!include`<key1>=<value1>, <key2>=<value2>` some_file
For example, to specify line ranges in options:
!include`startLine=1, endLine=10` some_file
Or to include snippets with enclosed delimiters:
!include`snippetStart="<!-- Start -->", snippetEnd="<!-- End -->"` some_file
<!-- Start --> and
<!-- End --> are two strings occuring in
If multiple occurences of
<!-- Start --> or
<!-- End --> are in
some_file, then pandoc-include will include all the blocks between the delimiters.
snippetStart is not found or specified, it will include till the end or from the start.
||Start line of include (default: 1)|
||End line of include (default: number of the last line)|
||Start delimiter of a snippet|
||End delimiter of a snippet|
||Whether to include the delimiters (default:
||Increment (or decrement) section levels of include|
||Remove n leading whitespaces of each line where possible (
||The input format of the included file (see
||Include as raw block. The arg is the format (
Note: the values above are parsed as Python literals. So
str should be quoted like
bool should be
--- include-entry: '<path>' include-order: 'natural' rewrite-path: true pandoc-options: - --filter=pandoc-include - <other options> ---
include-entry option is to make recursive includes work.
Its value 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 test.md --filter pandoc-include -o test.pdf
However, to compile a file not in current directory, like:
pandoc dir/test.md --filter pandoc-include -o test.pdf
The header should now be set to:
include-order options is to define the order of included files if the unix-style pathname matches multiple files.
The default value is
natural, which means using the natural order.
Other possible values are
default means to keep the order returned by the Python
rewrite-path option is a boolean value to configure whether the relative paths of images should be rewritten to paths relative to the root file.
The default value is
For example, consider the following directory structure:
main.md content/ chapter01.md image.png
chapter01.md uses the image
It should use
pandoc-options option is a list to specify the pandoc options when recursively processing included files.
By default, the included file will inherit the
pandoc-options from its parent file, unless specified in its own file.
To make the recursive includes work,
--filter=pandoc-include is necessary.
The default value of
pandoc-options: - --filter=pandoc-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/chap01.md !include chapters/chap02.md !include chapters/chap03.md !include`raw="latex"` data/table.tex
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
main.md, we can extend the header:
--- title: Title --- !include-header header.yaml # Section Body
main.md then is equivalent to the follow markdown:
--- title: Title name: xxx school: yyy email: zzz --- # Section Body
The pandoc command-line options are processed in order.
If you want some options to be applied in included files,
make sure the
--filter pandoc-include option is specified before those options.
For example, use bibliography in the included files:
pandoc main.md --filter pandoc-include --citeproc --bibliography=ref.bib -o main.pdf
Release history Release notifications | RSS feed
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Hashes for pandoc_include-1.2.0-py3-none-any.whl