Macros for Foliant.
Project description
# Macros for Foliant
*Macro* is a string with placeholders that is replaced with predefined content during documentation build. Macros are defined in the config.
## Installation
```shell
$ pip install foliantcontrib.macros
```
## Config
Enable the preprocessor by adding it to `preprocessors` and listing your macros in `macros` dictionary:
```yaml
preprocessors:
- macros:
macros:
foo: This is a macro definition.
bar: "This is macro with a parameter: {0}"
```
## Usage
Here's the simplest usecase for macros:
```yaml
preprocessors:
- macros:
macros:
support_number: "8 800 123-45-67"
```
Now, every time you need to insert your support phone number, you put a macro instead:
```markdown
Call you support team: <<macro>support_number</macro>.
Here's the number again: <<m>support_number</m>.
```
Macros are useful in documentation that should be built into multiple targets, e.g. site and pdf, when the same thing is done differently in one target than in the other.
For example, to reference a page in MkDocs, you just put the Markdown file in the link:
```markdown
Here is [another page](another_page.md).
```
But when building documents with Pandoc all sources are flattened into a single Markdown, so you refer to different parts of the document by anchor links:
```markdown
Here is [another page](#another_page).
```
This can be implemented using `<<if></if>` tag:
```markdown
Here is [another page](<if backends="pandoc">#another_page</if><if backends="mkdocs">another_page.md</if>).
```
This bulky construct quickly gets old when you use many cross-references in your documentation.
To make your sources cleaner, move this construct to the config as a reusable macro:
```yaml
preprocessors:
- macros:
macros:
ref: <<if backends="pandoc">{0}</if><if backends="mkdocs">{1}</if>
```
And use it in the source:
```markdown
Here is [another page](<<macro params="#another_page, another_page.md">ref</macro>).
```
*Macro* is a string with placeholders that is replaced with predefined content during documentation build. Macros are defined in the config.
## Installation
```shell
$ pip install foliantcontrib.macros
```
## Config
Enable the preprocessor by adding it to `preprocessors` and listing your macros in `macros` dictionary:
```yaml
preprocessors:
- macros:
macros:
foo: This is a macro definition.
bar: "This is macro with a parameter: {0}"
```
## Usage
Here's the simplest usecase for macros:
```yaml
preprocessors:
- macros:
macros:
support_number: "8 800 123-45-67"
```
Now, every time you need to insert your support phone number, you put a macro instead:
```markdown
Call you support team: <<macro>support_number</macro>.
Here's the number again: <<m>support_number</m>.
```
Macros are useful in documentation that should be built into multiple targets, e.g. site and pdf, when the same thing is done differently in one target than in the other.
For example, to reference a page in MkDocs, you just put the Markdown file in the link:
```markdown
Here is [another page](another_page.md).
```
But when building documents with Pandoc all sources are flattened into a single Markdown, so you refer to different parts of the document by anchor links:
```markdown
Here is [another page](#another_page).
```
This can be implemented using `<<if></if>` tag:
```markdown
Here is [another page](<if backends="pandoc">#another_page</if><if backends="mkdocs">another_page.md</if>).
```
This bulky construct quickly gets old when you use many cross-references in your documentation.
To make your sources cleaner, move this construct to the config as a reusable macro:
```yaml
preprocessors:
- macros:
macros:
ref: <<if backends="pandoc">{0}</if><if backends="mkdocs">{1}</if>
```
And use it in the source:
```markdown
Here is [another page](<<macro params="#another_page, another_page.md">ref</macro>).
```
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
Built Distribution
Close
Hashes for foliantcontrib.macros-1.0.3.tar.gz
Algorithm | Hash digest | |
---|---|---|
SHA256 | 922127fdcfc97a8aa799563904713b2f257d7e4efdc1fd925ee1abbe8ce0608f |
|
MD5 | 2e9f0c9d1838311a2e8bde17db4a3ea2 |
|
BLAKE2b-256 | 78eac535f30593a1e412b8c447dc5ff1b43ffe0b85c2066748419cf0a1bdb933 |
Close
Hashes for foliantcontrib.macros-1.0.3-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | e44f2f0c55cdc7033ecd844f8ea0f76e69b94013fbba39411013a946e437587c |
|
MD5 | c16c84b26488996f6b807b37e7ab51e5 |
|
BLAKE2b-256 | e75257b9476a0c33caf5fdb43924aa0b7eec8a07f2c17f3028e8d62094cd85d4 |