pandoc_styles 0.9.18

Description:

pandoc styles 0.9.18

pandoc-styles
This script allows you to define styles for pandoc. In styles you can define, with which arguments pandoc should be invoked for different formats. In addition it allows to run scripts before and after a conversion and gives much power to these scripts and to filters.

pandoc-styles

Installation

Requirements
Install

Via pipx
Local python


Setup


Usage
Defining Styles

Basic Usage
Inheritance


Stylepacks
Advanced Feature

Adressing files in the configuration folder
Verbatim Variables
Preflight
Process Sass
Add to template
Replace in template
Replace in output
Postflight
Filter
Advanced Example


Commandline tools
Creating stylepacks



Installation
Requirements
To use this script, you need the following:


Python 3.6 or higher:
You can get python here.


Pandoc 3.1 or higher:
You can download pandoc here.


(Optional) pipx:
You can find installation instruction here


Install
Now you need to install this script itself.
Via pipx
The recommended way is via pipx. This runs the script in an isolated environment.
Open the console and enter:
pipx install pandoc-styles
pandoc-styles --init

If you need additional python packages in the isolated environment, you can install them via
pipx inject pandoc-styles package-name

If you for example need the matplotlib stack use
pipx inject pandoc-styles numpy scipy matplotlib pandas sympy nose

Local python
You can install the script into your local python environment
Open the console and enter:
pip3 install pandoc_styles
pandoc-styles --init

Setup
Depending on your system, you may have to configure some settings for everything to work.
Upon initialization this script created the directory "pandoc_styles" in your user folder. Inside you can find the config.yaml file. Set the option in there that are needed for your system.
Usage
The "pandoc_styles" folder can be used as a central point to store styles, scripts, filter etc. Some subfolders are pre-created for you to use.
The "styles.yaml" file contains all the styles. Here you define your styles and the script looks here for styles specified in the metadata block of your files.
To use your styles, your source files need to have a metadata block. These commands in the block are recognized by this script:

styles: A list of styles to be used for the file
style-defintion: In addition of defining styles in the "styles.yaml" file, you can define a style here too. Style settings given here have precedence over those given in "styles.yaml"
formats: A list of formats the source file should be converted to. If none is given, html- and pdf-files are build.
destination: A directory to create the output in.
output-name: The desired name of the outputfile without extension. In none is given, the filename is used.
fields that exist in the style. They override the default given in the style.

If you convert all files in a folder as one document, these additional commands are available:

file-list: Specify exactly which files in the folder should be converted.
excluded-files: Exclude the listed files from beeing converted.

Then to convert your file, open the console and enter:
pandoc-styles "your_file"

Or if you want to convert all files in a folder as one document:
pandoc-styles -f
The commandline script has many optional parameters to be useful in macros, batch files etc. Enter
pandoc-styles -h

to see all the options.
Defining Styles
Basic Usage
Styles are written in yaml, just like pandoc metadata-blocks. A style is defined like this:
Name:
format:
pandoc-option: value
pandoc-variable: value

"Name" is how the style is adressed. A style directly defined in the metadata-block has no name. "Format" specifies for which format the following commands should be invoked. There is a special value: "all". Everything under "all" is used in any format. Examples for formats are html, pdf, latex, epub etc.
Under the format you just enter pandoc options and variables. If a parameter is a flag, use "true". Parameters given the value "false" are ignored.
A Basic example
This is an example metadata-block in a source file:
---
title: Example
author: John Doe
formats:
- html
- pdf
style-definition:
all:
toc: true
toc-depth: 3
highlight-style: tango
language: en
html:
standalone: true
pdf:
pdf-engine: xelatex
---

Inheritance
A style can have a field named "inherit". This is a list of other styles it inherits from. Styles lower on the list update styles that are higher. The following rules are in place:

Single values are replaced
If a value is another dictionary, new values are appended to it, if a value exists, these rules are used again on it
If a value is a list, new values are appended to it.

Stylepacks
It is possible, to bundle all files necessary for a particular style and share this as a stylepack. You can install a stylepack either through extracting its contents into the styles folder inside the config folder or through the pandoc_styles_tools command line interface with the option import command.
To use a stylepack, include a field "stylepacks" in the matadata. It looks like this:
stylepacks:
- stylepack_1_name:
- style_1
- style2
- stylepack_2_name

If you do not specify styles from the stylepack, it uses its default style.
Example
pandoc_styles: novel is a stylepack to create novels out of your source files. A documentation for using this stylepack is found on the github page and inside the style folder of the pack once installed. You can install it with this command:
pandoc-styles-tools import novel -u https://github.com/dickloraine/pandoc_styles_novel/releases/latest/download/novel.zip

Advanced Feature
Adressing files in the configuration folder
You can point to a file in the configuration directory, if you prepend the path with "~/". The script searches first for the given path and then looks in appropiatly named subfolders and finally in the "misc" subfolder. For example:
filter:
- ~/test-filter.py

Would find the file "test-filter.py" in the subfolder "filter" in the configuration directory.
Verbatim Variables
If you need template variables that should not be rendered in the output format (for example file paths), you can add these under the "verbatim-variables" field:
verbatim-variables:
my-path: "my/path"

Some variables are predefiened and always usable in templates:

config-dir: The path to the config dir
stylepackName-dir: The path to the directory of the given stylepack
temp-dir: The path to the currently used temporary directory

Preflight
You can run other command-line apps and scripts before the conversion happens. Just enter the command-line command in the preflight field in the style definition. You can pass the files list to it with <files>. Explicitly mark the value as a string, to avoid any hassle with special characters. For example:
Test-style:
html:
preflight:
- 'some_app -d -f <files>'

If you give it just a single python file, it assumes that it is a special preflight script. These are written in python and have access to the style infos and files that should be converted.
Here a basic example of a preflight script, that appends text given in the field "append-to-file" in the style definition to the end of the files:
from pandoc_styles import run_preflight_script, file_read, file_write


def preflight(self):
text_to_append = self.cfg["append-to-file"]
if isinstance(text_to_append, list):
text_to_append = "\n".join(text_to_append)
file_write(self.files[-1], f"{file_read(self.files[-1])}\n{text_to_append}")


if __name__ == '__main__':
run_preflight_script(preflight)

Modify only the preflight function to include your code.
And to run it in your style definition:
Test-style:
html:
preflight:
- append-to-file.py
append-to-file: "Test"

Process Sass
You can point to sass-files that should be used for html output and this script converts them for you to css and uses that in the output. In addition you can define variables used in the sass file and specify, where the compiled css file shoud be copied.
Test-style:
html:
sass:
files: ~/default.scss
output-path: temp
variables:
body-font-size: 10pt

"files" is a list of sass files to be included.
"output-path" can be "~/" to output to the css folder in the configuration folder, a relative path or "temp" to be used with the "self-contained" parameter. If ommited, the css output is in the same folder as the source files output.
"variables" can be any variables in your sass files.
Add to template
Sometimes you want to include some code directly into the template, instead of just including it in the header. Mostly, if you want to define and use your own template variables.
This option just injects the given code directly into the head of the template.
It accepts a path to a file and will add the contents of the file to the template.
Test-style:
pdf:
add-to-template:
- |
\titlehead{{$titletop-left$
\hfill $titletop-right$\\}
$titlehead$}
\publishers{\small $titlebottom$}

Replace in template
As above, but instead of just adding the code to the head, it replaces arbitrary text in the template. You need to give it a pattern and a replacement text. Optionally you can use the flag "add" to not replace the text, but prepend to it and the field "count" if only some matches should be replaced.
Test-style:
html:
replace-in-template:
- pattern: \$body\$
replacement-text: |
<div class="content">
$body$
</div>

Replace in output
Exactly the same as replace-in-template but for text in the output-file
Postflight
These scripts are called after the source is converted. Pretty similar to preflight, but instead of <files> it only accepts a single <file>
Some app:
Test-style:
html:
preflight:
- 'some_app -d -f <file>'

Custome script:
from pandoc_styles import run_postflight_script, file_read, file_write


def postflight(self):
text_to_append = self.cfg["append-to-output"]
if isinstance(text_to_append, list):
text_to_append = "\n".join(text_to_append)
file_write(ffile, f"{file_read(ffile)}\n{text_to_append}")


if __name__ == '__main__':
run_postflight_script(postflight)

Test-style:
html:
preflight:
- append-to-output.py
append-to-output: "Test"

Filter
This script includes some functionality to make writing filters a little bit more easy.
Advanced Example
Pandocs self-contained flag doesn't work for html if math is used, because mathjax can't be included. This style is not really self-contained, but it allows for single files with all css included. This example useses the default.sass file included in this script. Fonts are also just referenced instead of included, to make for small file-sizes.
For code in pdfs, it introduces line-wrap in code blocks and ligatures in the font.
In addition, inheritance is shown.
All:
all:
lang: en
pdf:
pdf-engine: "xelatex"

Math-document:
inherits:
- Code
html:
self-contained: true
mathjax: true
sass:
files: ~/default.scss
output-path: temp
replace-in-template:
- pattern: \$body\$
replacement-text: |
<div class="content">
$body$
</div>
- pattern: \$table-of-contents\$
replacement-text: |
<div id="sidebar">
<input class="trigger" type="checkbox" id="mainNavButton">
<label for="mainNavButton" onclick></label>
$table-of-contents$
</div>
replace-in-output:
- pattern: (<\/head>)
count: 1
add: true
replacement-text: |
<link href="https://fonts.googleapis.com/css?family=Noto+Sans|Noto+Serif|Oswald" rel="stylesheet">
<link rel="stylesheet" href="https://cdn.jsdelivr.net/gh/tonsky/[email protected]/distr/fira_code.css">
- pattern: <script type="text\/javascript">\/\*\n\s+\*\s+\/MathJax\.js.*?<\/script>
replacement-text: |
<script src="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.2/MathJax.js?config=TeX-AMS_CHTML-full" type="text/javascript"></script>

Code:
all:
highlight-style: tango
pdf:
monofont: Fira Code
# allow code line break
add-to-template:
- |
\usepackage{fvextra}
\DefineVerbatimEnvironment{Highlighting}{Verbatim}{breaklines,breakautoindent=true,commandchars=\\\{\}}
- |
\setmonofont[
Contextuals={Alternate}
]{$monofont$}
\makeatletter
\def\verbatim@nolig@list{}
\makeatother

Commandline tools
Some additional tools are available on the commandline with the command:
pandoc-styles-tools

The import option is used to import stylepacks.
One tool merges styles and outputs the new style in a file.
The localize tool copies all used assets into the local directory, to have a self-contingent project folder.
Creating stylepacks
To create a stylepack, just create a folder with the name of the stylepack. Inside the folder put a yaml file containing the style definitions with the name of the stylepack. Then mimick the config folder for organizing the files provided.
In the yaml file reference links to files inside the stylepack with "stylepack_name@path".
Create a zip of your folder (with the folder inside the zip) and name it after your stylepack.