Powerful includes for Foliant doc maker.
Project description
Includes for Foliant
Includes preprocessor lets you reuse parts of other documents in your Foliant project sources. It can include from files on your local machine and remote Git repositories. You can include entire documents as well as parts between particular headings, removing or normalizing included headings on the way.
Installation
$ pip install foliantcontrib.includes
Config
To enable the preprocessor with default options, add includes
to preprocessors
section in the project config:
preprocessors:
- includes
The preprocessor has a number of options:
preprocessors:
- includes:
cache_dir: !path .includescache
recursive: true
aliases:
...
cache_dir
: Path to the directory for cloned repositories. It can be a path relative to the project path or a global one; you can use ~/
shortcut.
> **Note**
>
> To include files from remote repositories, the preprocessor clones them. To save time during build, cloned repositories are stored and reused in future builds.
recursive
: Flag that defines whether includes in included documents should be processed.
aliases
: Mapping from aliases to Git repository URLs. Once defined here, an alias can be used to refer to the repository instead of its full URL.
For example, if you set this alias in the config:
- includes:
aliases:
foo: https://github.com/boo/bar.git
baz: https://github.com/foo/far.git#develop
you can include README.md file content from this repository using this syntax:
<<include>$foo$path/to/doc.md</include>
<<include>$baz#master$path/to/doc.md</include>
Note that in the second example we override the default revision.
Usage
To include a document from your machine, put the path to it between <<include>...</include>
tags:
Text below is taken from another document.
<<include>/path/to/another/document.md</include>
To include a document from a remote Git repository, put its URL between $
s in front of the document path:
Text below is taken from a remote repository.
<<include>
$https://github.com/foo/bar.git$path/to/doc.md
</include>
If the repository alias is defined in the project config, you can use it instead of the URL:
- includes:
aliases:
foo: https://github.com/foo/bar.git
And then in the source:
<<include>$foo$path/to/doc.md</include>
You can also specify a particular branch or revision:
Text below is taken from a remote repository on branch develop.
<<include>$foo#develop$path/to/doc.md</include>
To include a part of a document between two headings, use the #Start:Finish
syntax after the file path:
Include content from "Intro" up to "Credits":
<<include>sample.md#Intro:Credits</include>
Include content from start up to "Credits":
<<include>sample.md#:Credits</include>
Include content from "Intro" up to the next heading of the same level:
<<include>sample.md#Intro</include>
Options
sethead
: The level of the topmost heading in the included content. Use it to guarantee that the included text doesn't break the parent document's heading order:
# Title
## Subtitle
<<include sethead="3">
other.md
</include>
nohead
: Flag that tells the preprocessor to strip the starting heading from the included content:
# My Custom Heading
<<include nohead="true">
other.md#Original Heading
</include>
Default is `false`.
Options can be combined. For example, use both sethead
and nohead
if you want to include a section with a custom heading:
# My Custom Heading
<<include sethead="1" nohead="true">
other.md#Original Heading
</include>
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.includes-1.0.7.tar.gz
Algorithm | Hash digest | |
---|---|---|
SHA256 | 7d6a30a858f8c7f089007e5237ae5749c308d02c81eb177f58263b4c6b191b39 |
|
MD5 | adeb52c2553696813ebac0b3051de159 |
|
BLAKE2b-256 | da2968ed0f802831ae7474108735d640a082639d76a1cea924afe2ab840a6206 |
Hashes for foliantcontrib.includes-1.0.7-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 5526faab77de81bc866ec0cd0f4ce67ca96e087d6dabd75559d935b4cbad9131 |
|
MD5 | 39080316d2ff3e953bca34e25b1cfba7 |
|
BLAKE2b-256 | 05c9c94bb69028b9228f4eac597e5b8fee96f2cec2033f44f025c476a0501c15 |