Skip to main content

No project description provided

Project description


CrissCross is a Markdown-centric templating engine.

Some of its features:

  • Replace Mustache-style placeholders
  • Include/import subfiles !INCLUDE ""
  • Convert to other formats using pandoc or rmarkdown
Table of Contents

Getting Started


  • Python 3
  • (optional) either pandoc, or rmarkdown is required to convert files from one format to another
  • (optional) LaTeX is required for PDF generation


pip3 install crisscross


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, and crisscross process to generate PDF files from them.

Here's a sneak peek of the PhD applications example. CrissCross allows you to go from a template that looks like this:

I am applying to **{{school_alt_name}}**’s PhD program because **{{school}}** is awesome. 

!INCLUDE "custom/{{school}}"

To PDFs like these:

Michigan UChicago



There are two commands, process and combine.


process is the command that processes the template files.


Convert into PDF, using key-value pairs specified in VARS.yaml:

crisscross process -y VARS.yaml -o OUTDIR/TEMPLATE.pdf


Usage: crisscross process [OPTIONS] TEMPLATES...

  Preprocess text files, and render with pandoc or rmarkdown.

  -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. 
  --open-ren / --no-open-ren      Whether to open the rendered files
                                  (Default: enabled)
  --open-text / --no-open-text    Whether to open the generated text files
                                  (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". 
  -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 is a helper command takes the "Cartesian product" of lists of files.


crisscross combine a1,a2 b1,b2 -o out/

would generate under out/


where a1_b1 is a concatenation of a1 and b1, a1_b2 a concatenation of a1 and b2, and so on.

See the quiz example for a real-world use case of combine.


Usage: crisscross combine [OPTIONS] [FILES]...

  Generate the 'Cartesian product' of multiple files.

  -o, --out DIRECTORY          Output directory.
  -s, --separator TEXT         Character used to join the names of input
  -q, --quiet / -v, --verbose  Suppress messages. 
                               (Default: disabled)
  -h, --help                   Show this message and exit.

File Inclusion

Two inclusion tags are supported:

Adding asis after the inclusion tag will tell CrissCross to include the file as is, and not to further process it: !INCLUDE asis ""

Key-Value Pairs

Key-value pairs tell CrissCross how to replace placeholder expressions. They can be either placed in YAML files:

lang: English
level: Level

Alternatively, they could be supply using the -V option:

crisscross process -V key1:value1 -V key2:value2 TEMPLATE -o OUTFILE


  • Add the option to render inline placeholders as is
  • Add the option to use different patterns for placeholder expressions
  • Add logic support

Built With

This project uses the following open source libraries.


This project is heavily inspired by:

Other related projects

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

crisscross-0.1.8.tar.gz (12.2 kB view hashes)

Uploaded source

Built Distribution

crisscross-0.1.8-py3-none-any.whl (5.4 kB view hashes)

Uploaded py3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page