Skip to content

A Markdown-centric template engine for batch offline document generation.

License

Notifications You must be signed in to change notification settings

pnlng/crisscross

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

22 Commits
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

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

  • 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

About

A Markdown-centric template engine for batch offline document generation.

Topics

Resources

License

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published