No project description provided
Project description
CrissCross
CrissCross is a Markdown-centric templating engine.
Some of its features:
- Replace Mustache-style placeholders
- Include/import subfiles
!INCLUDE "subfile.md"
- Convert to other formats using pandoc or rmarkdown
Table of Contents
- [CrissCross](#crisscross) - [Getting Started](#getting-started) - [Prerequisites](#prerequisites) - [Installation](#installation) - [Examples](#examples) - [Usage](#usage) - [Basic Usage](#basic-usage) - [Commands](#commands) - [Process](#process) - [Combine](#combine) - [File Inclusion](#file-inclusion) - [Roadmap](#roadmap) - [Built With](#built-with) - [Acknowledgments](#acknowledgments) - [Other related projects](#other-related-projects)Getting Started
Prerequisites
Crisscross requires Python 3.
To convert files from one format to another, crisscross requires either pandoc, or rmarkdown.
Installation
pip3 install crisscross
Examples
Here are some sample use cases of CrissCross, ordered by increasing complexity.
- English and Spanish: Generate PDFs of the same file with keywords in different languages.
- PhD Applications: Generate personal statements customized for different schools.
- Weekly Quiz: Generate quizzes and their solutions for 2 different sections using the same template.
- The examples uses
crisscross combine
to take the "Cartesian product" of different sets of YAML metadata files, andcrisscross process
to generate PDF files from them.
- The examples uses
Here's a sneak peek of the PhD applications example. CrissCross allows you to from a template that looks like this:
I am applying to **{{school_alt_name}}**’s PhD program because **{{school}}** is awesome.
!INCLUDE "custom/{{school}}_last.md"
To PDFs like these:
Michigan | UChicago |
---|---|
Usage
Basic Usage
Convert TEMPLATE.md
into PDF, using key-value pairs specified in VARS.yaml
:
crisscross process TEMPLATE.md -y VARS.yaml -o OUTDIR/TEMPLATE.pdf
Commands
There are two commands, process
and combine
.
Process
process
is the command that processes the template files.
Usage: crisscross process [OPTIONS] TEMPLATES...
Preprocess text files, and render with pandoc or rmarkdown.
Options:
-y, --yaml PATH The YAML file(s) to be used. If wildcard
characters are used, then the whole argument
must be quoted, e.g., -y '*.yaml'.
(Default: custom/*.yaml)
--no-yaml Use no YAML files. In this case, key-value
pairs must be supplied with -k --key-value.
(Default: disabled)
-o, --out PATH Schema for the path to an output file.
Variables are accepted.
(Default:
docs/{{id}}.pdf)
--open-ren / --no-open-ren Whether to open the rendered files
automatically.
(Default: enabled)
--open-text / -no-open-text Whether to open the generated text files
automatically.
(Default: disabled)
-a, --args TEXT A string of arguments to be passed on to
pandoc. Passing arguments to rmarkdown not
supported. If there are spaces, the string
should be quoted.
-r, --render [pandoc|rmarkdown]
Render using vanilla pandoc or rmarkdown, or
do not render at all.
(Default: pandoc)
--no-render Do not render the files with pandoc or
rmarkdown. Only do variable substitution or
file inclusion.
(Default: disabled)
--include-tag [include|import] Syntax for file inclusion. Either !INCLUDE
"filename" or @import "filename".
(Default:
include)
-V, --variable TEXT A key-value pair separated by ":". No spaces
allowed. Can be used in conjunction with or
in place of YAML files.
-f, --force Suppress warnings.
(Default: disabled)
-q, --quiet / -v, --verbose Suppress messages.
(Default: disabled)
-h, --help Show this message and exit.
Combine
combine
is a helper command takes the "Cartesian product" of lists of files.
Usage: crisscross combine [OPTIONS] [FILES]...
Generate the 'Cartesian product' of multiple files.
Options:
-o, --out DIRECTORY Output directory.
-s, --separator TEXT Character used to join the names of input
files.
-q, --quiet / -v, --verbose Suppress messages.
(Default: disabled)
-h, --help Show this message and exit.
File Inclusion
Two inclusion tags are supported:
!INCLUDE "foo.md"
, in the style of Markdown Preprocessor, and@import "foo.md"
, in the style of Markdown Preview Enhanced- However, unlike MPE, CrissCross does not support
<!-- @import "foo.md" -->
.
- However, unlike MPE, CrissCross does not support
Adding asis
after the inclusion tag will tell CrissCross to include the file as is, and not to further process it: !INCLUDE asis "foo.md"
Roadmap
- Add the option to render inline placeholders as is
- Add logic support
Built With
This project uses the following open source libraries.
- pallets/click: Python composable command line interface toolkit
- hackebrot/poyo: A lightweight YAML Parser for Python
- noahmorrison/chevron: A Python implementation of mustache
Acknowledgments
This project is heavily inspired by:
- alpianon/include-pandoc: A wrapper for pandoc to pre-process includes
- michaelstepner/pandoc-mustache: Pandoc filter for variable substitution using Mustache syntax
Other related projects
- jreese/markdown-pp: Preprocessor for Markdown files to generate a table of contents and other documentation needs
- DCsunset/pandoc-include: Pandoc filter to allow file includes
- owickstrom/pandoc-include-code: A Pandoc filter for including code from source files
- MrToph/pandoc-code-file-filter: A filter for pandoc to include sections of code from a file
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
Hashes for crisscross-0.1.5-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 4ab06b366c3b2f89637a211a439b7c5492c6682831ff6f6f263af69dbc6f85a7 |
|
MD5 | 432ea8f4ed7fbbbcb12ef533f3785814 |
|
BLAKE2b-256 | f81eddd38d96fb65d56061fcad84d1267d5d86230178707ad3614de4ae8ab28f |