Package: pandoc-include
pandoc-includePandoc filter to allow file and header includes.The filter script is based onUser Guide for Panflute.
This repository is to provide a simple way to install and use it.FeaturesInclude as raw blocksIndent and dedent included contentsPartial include: Allow including only parts of the file using optionsCode include: Allow using!includein code blocksUnix style pathnameRecursive include: It depends oninclude-entryheader to workYaml 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.TODO[] Write options to a tmp file and pass the filename by environment variableInstallationpandoc-include requirespythonandpip.Then, use pip to install:pip install --user pandoc-includeAfter installation,
make sure that thepandoc-includeexecutable is put in the directory which is inthe PATH environment.To install the current (development) version hosted on the repository, usepip install --upgrade --force --no-cache git+https://github.com/DCsunset/pandoc-includeYou can usepip show pandoc-includeto check the version currently installed.UsageNote: you should usepandocwith version greater than or equal to2.17,
which is the minimum version that is tested.CommandTo use this filter, add to pandoc commandpandoc input.md --filter pandoc-include -o output.pdfSyntaxEach include statement has its own line and has the syntax:!include somefolder/somefile

!include-header file.yamlOr$include somefolder/somefile

$include-header file.yamlEach include statement must be in its own paragraph. That is, in its own line
and separated by blank lines.For code include, use!includestatement in a code block:```cpp!includefilename.cpp```The path can be either absolute or relative to thecurrentfile's directory.
Besides,unix-stylepathname 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'If the filename contains special sequences in markdown, use backquotes:
(Note: this also applies to include statment in code blocks)!include `__filename__`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.The!includecommand also supports options:!include`<key1>=<value1>, <key2>=<value2>` some_fileFor example, to specify line ranges in options:!include`startLine=1, endLine=10` some_fileOr to include snippets with enclosed delimiters:!include`snippetStart="<!-- Start -->", snippetEnd="<!-- End -->"` some_fileOr includingxmlfiles transforming them withXSLT:!include`format="markdown", xslt="xslt/api.xslt"` main_8h.xmlwhere<!-- Start -->and<!-- End -->are two strings occuring insome_file.If multiple occurences of<!-- Start -->or<!-- End -->are insome_file, then pandoc-include will include all the blocks between the delimiters.
IfsnippetEndorsnippetStartis not found or specified, it will include till the end or from the start.Supported options:KeyValueDescriptionstartLineintStart line of include (default: 1)endLineintEnd line of include (default: number of the last line)snippetStartstrStart delimiter of a snippetsnippetEndstrEnd delimiter of a snippetincludeSnippetDelimitersboolWhether to include the delimiters (default:False)incrementSectionintIncrement (or decrement) section levels of includededentintRemove n leading whitespaces of each line where possible (-1means remove all)formatstrThe input format of the included file (seepandoc --list-input-formats). It will be automatically deduced from the path if not set. (Hint: extensions can also be enabled here)rawstrInclude as raw block. The arg is the format (latex,html...)xsltstrXSLTfile to use for transforming the given.xmlfile (This is intended to be used with Doxygen'sxmloutputNote: the values above are parsed as Python literals. Sostrshould be quoted like'xxx'or"xxx";boolshould beTrueorFalse.Header options---
include-entry: '<path>'
include-order: 'natural'
include-resources: '<path>[:<path>]'
rewrite-path: true
pandoc-options:
  - --filter=pandoc-include
  - <other options>
---include-entryTheinclude-entryoption 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 defaultinclude-entryvalue is..For example, to compile a file in current directory, no header is needed:pandoc test.md --filter pandoc-include -o test.pdfHowever, to compile a file not in current directory, like:pandoc dir/test.md --filter pandoc-include -o test.pdfThe header should now be set to:include-entry: 'dir'.include-orderTheinclude-orderoptions is to define the order of included files if the unix-style pathname matches multiple files.
The default value isnatural, which means using thenatural order.
Other possible values arealphabeticalanddefault.
Thedefaultmeans to keep the order returned by the Pythonglobmodule.include-resourcesTheinclude-resourcescan be used to simplify relative paths of include statements by searching in the given paths for files with relative paths when otherwise not found.Given following directory structure andpandoccommand:main.md
examples/
    hello-world.c
content/
    chapter1/
        chapter01.md
        image.png
    chapter2/
        chapter02.md
        image.png$ pandoc --metadata include-resources=examples/ ... main.mdThis will make it possible to have following include line inchapter01.mdandchapter02.md```cpp!includehello-world.c```Instead of:```cpp!include../../examples/hello-world.c```This is most useful if some resources, e.g. source code or Doxygen output,
is located in an external directory structure.rewrite-pathTherewrite-pathoption 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 istrue.For example, consider the following directory structure:main.md
content/
  chapter01.md
  image.pngSupposechapter01.mduses the imageimage.png.
It should use![Image](image.png)ifrewrite-pathistrue,
or![Image](content/image.png)ifrewrite-pathisfalse.pandoc-optionsThepandoc-optionsoption isa listto specify the pandoc options when recursively processing included files.
By default, the included file willinheritthepandoc-optionsfrom its parent file,unlessspecified in its own file.To make the recursive includes work,--filter=pandoc-includeisnecessary.
The default value ofpandoc-optionsis:pandoc-options:
  - --filter=pandoc-includeExamplesFile includeFile include can be used to separate chapters into different files,
or include some latex files:---
title: Article
author: Authortoc: true---!include chapters/chap01.md

!include chapters/chap02.md

!include chapters/chap03.md

!include`raw="latex"` data/table.texHeader includeFor header include, it is useful to define a header template
and include it in many files.For example, in theheader.yaml, we can define basic info:name:xxxschool:yyyemail:zzzIn themain.md, we can extend the header:---title: Title---!include-header header.yaml# SectionBodyThemain.mdthen is equivalent to the follow markdown:---
title: Title
name: xxx
school: yyyemail: zzz---# SectionBodyEnvironment VariablesThe following environment variables can be set to change the default behaviour:KeyValueDescriptionPANDOC_INCLUDE_NOT_FOUND_ERROR0or1Emit an error if file not found (default: 0)DevelopmentTo setup local dev environment, you can use pythonvenvto create a virtual environment fromrequirements.txt.Or if you use Nix, you can simply runnix develop.Trouble ShootingThe pandoc command-line options are processed in order.
If you want some options to be applied in included files,
make sure the--filter pandoc-includeoption 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.pdfLicenseMIT License