Skip to main content

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

Getting Started

Prerequisites

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

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, 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}}_last.md"

To PDFs like these:

Michigan UChicago

Usage

Commands

There are two commands, process and combine.

Process

process is the command that processes the template files.

Example

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

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

Options

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.

Example

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

would generate under out/

out/
  a1_b1
  a1_b2
  a2_b1
  a2_b2

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.

Options

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:

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"

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

Roadmap

  • [ ] 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.

Acknowledgments

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.

Files for crisscross, version 0.1.8
Filename, size File type Python version Upload date Hashes
Filename, size crisscross-0.1.8-py3-none-any.whl (5.4 kB) File type Wheel Python version py3 Upload date Hashes View hashes
Filename, size crisscross-0.1.8.tar.gz (12.2 kB) File type Source Python version None Upload date Hashes View hashes

Supported by

Elastic Elastic Search Pingdom Pingdom Monitoring Google Google BigQuery Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN DigiCert DigiCert EV certificate StatusPage StatusPage Status page