https://github.com/foliant-docs/foliantcontrib.flags
Preprocessor for `if` blocks in Foliant sources
https://github.com/foliant-docs/foliantcontrib.flags
Last synced: 5 months ago
JSON representation
Preprocessor for `if` blocks in Foliant sources
- Host: GitHub
- URL: https://github.com/foliant-docs/foliantcontrib.flags
- Owner: foliant-docs
- License: mit
- Created: 2017-12-14T04:46:00.000Z (over 8 years ago)
- Default Branch: develop
- Last Pushed: 2020-07-16T08:00:18.000Z (almost 6 years ago)
- Last Synced: 2025-09-28T00:22:54.605Z (9 months ago)
- Language: Python
- Homepage:
- Size: 8.79 KB
- Stars: 0
- Watchers: 2
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: changelog.md
- License: LICENSE
Awesome Lists containing this project
README
[](https://pypi.org/project/foliantcontrib.flags/) [](https://github.com/foliant-docs/foliantcontrib.flags)
# Conditional Blocks for Foliant
This preprocessors lets you exclude parts of the source based on flags defined in the project config and environment variables, as well as current target and backend.
## Installation
```shell
$ pip install foliantcontrib.flags
```
## Config
Enable the propressor by adding it to `preprocessors`:
```yaml
preprocessors:
- flags
```
Enabled project flags are listed in `preprocessors.flags.flags`:
```yaml
preprocessors:
- flags:
flags:
- foo
- bar
```
To set flags for the current session, define `FOLIANT_FLAGS` environment variable:
```shell
$ FOLIANT_FLAGS="spam, eggs"
```
You can use commas, semicolons, or spaces to separate flags.
> **Hint**
>
> To emulate a particular target or backend with a flag, use the special flags `target:FLAG` and `backend:FLAG` where `FLAG` is your target or backend:
>
> $ FOLIANT_FLAGS="target:pdf, backend:pandoc, spam"
## Usage
Conditional blocks are enclosed between `...` tags:
```markdown
This paragraph is for everyone.
This parapraph is for management only.
```
A block can depend on multiple flags. You can pick whether all tags must be present for the block to appear, or any of them (by default, `kind="all"` is assumed):
```markdown
This is included only if both `spam` and `eggs` are set.
This is included if both `spam` or `eggs` is set.
```
You can also list flags that must *not* be set for the block to be included:
```markdown
This is included only if neither `spam` nor `eggs` are set.
```
You can check against the current target and backend instead of manually defined flags:
```markdown
This is for pdf outputThis is for the site
This is only for MkDocs.
```