templatex

A simple yet powerful template manager for Tectonic LaTeX projects.

templatex streamlines the creation of new Tectonic projects by scaffolding them from predefined templates. It features an interactive terminal UI for template selection and uses the Tera templating engine for dynamic content generation.

Features

• Interactive Template Selection: A clean TUI for picking templates if multiple are available.
• Dynamic Templating: Uses the Tera engine to substitute variables in your template files.
• Flexible Configuration: Configure template sources globally via TOML files or environment variables.
• Automatic Tectonic.toml Generation: Creates a basic Tectonic.toml for your new project.
• Customizable Template Sources: Keep your templates organized in one or more directories.

Installation

Install templatex using Cargo:

cargo install --locked templatex

Usage

To create a new project, run:

templatex <project_name> [OPTIONS]

This will launch an interactive prompt to select a template and fill in its variables. The new project will be created in a directory named <project_name>.

Command-Line Arguments & Options

• <NAME>: The name of the new project directory to be created. (Required)

• -t, --template-dir <TEMPLATE_DIR>: Specify a single directory to search for templates, ignoring configured sources.

• -o, --out-dir <OUT_DIR>: Set the output directory for the new project. Defaults to <NAME>.

• -s, --silent: Suppress all logging output.

• -v, --verbose: Enable verbose (DEBUG level) logging.

• --very-verbose: Enable maximum verbosity (TRACE level) logging.

Configuration

templatex can be configured to look for templates in one or more directories.

Config File

You can create a configuration file to define your template source directories. The location is platform-specific:

• Linux: ~/.config/templatex/config/
• macOS: ~/Library/Application Support/com.jayanaxhf.templatex/config/
• Windows: C:\Users\<user>\AppData\Roaming\jayanaxhf\templatex\config\

Create a TOML file in this directory (e.g., settings.toml) with the following format:

# ~/.config/templatex/config/settings.toml

# A list of directories where your templates are stored.
source_dirs = [
    "/path/to/my/templates",
    "~/Documents/latex-templates",
]

Environment Variables

Configuration can also be managed via environment variables.

• TEMPLATEX_CONFIG: Override the default configuration directory path.
• TEMPLATEX_SOURCE_DIRS__0: Set the first source directory. Use __1, __2, etc., for additional directories.

Example:

export TEMPLATEX_SOURCE_DIRS__0="/path/to/my/templates"
export TEMPLATEX_SOURCE_DIRS__1="~/other-templates"
templatex my-new-project

Creating Templates

A template is simply a directory containing the files for your Tectonic project.

Directory Structure

my-templates/
└── basic-article/
    ├── templatex.toml  (optional)
    └── src/
        ├── main.tex
        └── preamble.tex

templatex.toml (Optional)

You can add a templatex.toml file to the root of your template directory to provide a custom name and description for the TUI picker.

# my-templates/basic-article/templatex.toml
name = "Basic Article"
description = "A simple template for a standard article."

If this file is not present, the directory name (basic-article) will be used as the template's name.

Template Variables

Files inside the src/ directory are processed by the Tera templating engine. You can use <~{ variable_name }~> syntax to define placeholders that templatex will prompt you to fill in.

Example main.tex:

% src/main.tex
\documentclass{article}

\input{preamble.tex}

\title{ <~{ title }~> }
\author{ <~{ author }~> }
\date{ <~{ date }~> }

\begin{document}

\maketitle

\section{Introduction}
Hello, world!

\end{document}

When you use this template, templatex will ask you for values for title, author, and date.

Logging

Log files are stored in a platform-specific data directory:

• Linux: ~/.local/share/templatex/
• macOS: ~/Library/Application Support/com.jayanaxhf.templatex/
• Windows: C:\Users\<user>\AppData\Local\jayanaxhf\templatex\data\

The log level can be controlled with the TEMPLATEX_LOG_LEVEL environment variable (e.g., export TEMPLATEX_LOG_LEVEL=debug).