README_template.md

CrissCross

CrissCross is a Markdown-centric templating engine for offline documents.

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
  • Installation
• Examples
• Usage
  • Commands
  • Process
    • Example
    • Options
  • Combine
    • Example
    • Options
  • File Inclusion
  • Key-Value Pairs
• Roadmap
• Built With
• Acknowledgments
  • Other related projects

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:

!INCLUDE asis "examples/app/template.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

!INCLUDE asis "help/process.md"

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

!INCLUDE asis "help/combine.md"

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" -->.

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:

!INCLUDE asis "examples/lang/custom/en.yaml"

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.

• 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