Transpilation Rules

Transpilation rules control how Texpile converts editor content into LaTeX code. Every element you see in the editor (headings, paragraphs, images, tables, blockquotes, etc.) has a corresponding rule that defines what LaTeX it produces.

How Rules Work

Texpile provides a base preset (@texpile/base/v1) that covers all standard elements with sensible defaults. You can use this as-is or override specific rules to match your template’s requirements.

Rules use #placeholder# syntax to insert dynamic content. For example, a heading rule might look like:

\section{#text#}

When Texpile encounters a “Heading 1” in the editor, it replaces #text# with the actual heading text.

Using Presets in Rules

Just like exports and document sections, rules support presets. Most templates start with the base preset and only override what they need:

1. Add @texpile/base/v1 as the first rule (provides defaults for all elements)
2. Add any additional presets (e.g., @texpile/tables/academic/v1 for booktabs-style tables)
3. Add inline overrides for anything you want to customize

Inline overrides are written as JSON in the code editor within the template editor.

Rules cascade: later items override earlier ones. So if @texpile/base/v1 defines heading/1 as \section{#text#}, and you add an override after it, your override wins.

Common Overrides

Headings

Override how heading levels map to LaTeX commands:

% Heading 1 -> unnumbered section
\section*{#text#}

% Heading 2 -> numbered subsection
\subsection{#text#}

Blockquotes

Override the blockquote environment:

\begin{displayquote}
#content#
\end{displayquote}

Images

Image rules have several variants depending on alignment and numbering:

• center: default centered figure
• center_spanning: column-spanning figure (for multi-column templates)
• center_unnumbered: figure with caption but no number
• center_nocaption: figure with no caption
• left/right: wrapped figures using wrapfigure

Each variant also has a _spanning version for multi-column layouts.

Example for a two-column template like IEEE:

% Regular figure (single column)
\begin{figure}[htbp]
\centering
\includegraphics[width=#scale#\columnwidth]{#src#}
\caption{#caps#}
#label#
\end{figure}

% Spanning figure (both columns)
\begin{figure*}[htbp]
\centering
\includegraphics[width=#scale#\textwidth]{#src#}
\caption{#caps#}
#label#
\end{figure*}

Available placeholders for images:

• #src#: image filename
• #scale#: width as a fraction (e.g., 0.8)
• #caps#: caption text
• #label#: the \label{...} command

Tables

Table rules control the structure of the generated table:

• table: the inner tabular environment
• table_row: how each row is formatted
• table_cell: how each cell is formatted
• table_wrapper: the outer table float environment (numbered tables)
• table_wrapper_spanning: column-spanning version of the wrapper

Table Borders

You can customize table borders:

• top: border before the first row (e.g., \toprule, \hline, or false)
• bottom: border after the last row (e.g., \bottomrule, \hline, or false)
• vertical: vertical separators between columns (e.g., |, ||, or false)
• headerRow: border after the header row (e.g., \midrule, \hline, or false)
• rowBorder: border between all rows for a grid style
• partialRule: command for partial rules when rowspans cross borders (\cmidrule or \cline)

Example for academic-style tables (booktabs):

top: \toprule
bottom: \bottomrule
headerRow: \midrule
vertical: false
partialRule: \cmidrule

Example for grid-style tables:

top: \hline
bottom: \hline
vertical: |
rowBorder: \hline

Citations

Override how citation commands map to LaTeX. Each command has two forms: a basic form and a form with notes (prenote/postnote).

Available placeholders:

• #key#: the citation key
• #pre#: the prenote (e.g., “see”)
• #post#: the postnote (e.g., “p. 42”)

Default mappings:

autocite -> \autocite{#key#}  (with notes: \autocite[#pre#][#post#]{#key#})
parencite -> \parencite{#key#}
textcite -> \textcite{#key#}
cite -> \cite{#key#}

You can remap these for different citation packages. For example, IEEE maps everything to \cite:

autocite -> cite
parencite -> cite
textcite -> cite
cite -> cite

Cross-References

Customize how references to figures, tables, equations, and sections are formatted:

• figure: e.g., Fig.~\ref{#label#} or \autoref{#label#}
• table: e.g., Table~\ref{#label#}
• equation: e.g., \eqref{#label#}
• section: e.g., \ref{#label#}
• default: fallback for unknown reference types

Text Marks

Control how inline formatting is output:

• highlight: what LaTeX to generate for highlighted text. Set to #text# (plain text) if the template doesn’t support highlight.
• textcolor: what LaTeX to generate for colored text. Set to #text# if the template doesn’t support colors.

JSON Reference

Inline rule overrides are written as JSON. You only need to include the keys you want to override. Below is the full reference for every available key.

heading

Maps heading levels (1–5) to LaTeX commands.

{ "heading": { "1": "\\section*{#text#}" } }

paragraph

Template for paragraph text. Placeholder: #text#.

Default: #text#

code_block

Template for code blocks. Placeholder: #text# (the raw code content).

Default: \begin{verbatim}\n#text#\n\end{verbatim}

blockquote

Template for blockquotes. Placeholder: #content# (the blockquote’s inner content).

Default: \begin{quote}\n#content#\n\end{quote}

list

Templates for ordered and unordered lists. Placeholder: #content# (the list items).

list_item

Template for a list item. Placeholder: #content#.

Default: \item #content#

nolabel_list_item

Template for a list item without a label (used in certain list contexts). Placeholder: #content#.

Default: \item[] #content#

image

Templates for images. Each variant controls a different alignment/caption combination. Placeholders:

• #src#: image filename
• #scale#: width as a fraction of text/column width (e.g., 0.8)
• #scale2#: adjusted width for wrapfigure (scale minus margin)
• #caps#: caption text
• #label#: the \label{...} command

Variants:

Example (single-column figure for IEEE):

{
  "image": {
    "center": "\\begin{figure}[htbp]\n\\centering\n\\includegraphics[width=#scale#\\columnwidth]{#src#}\n\\caption{#caps#}\n#label#\\end{figure}"
  }
}

marks

Templates for inline text formatting. Placeholder: #text# (the marked text).

To disable highlight or textcolor output, set them to #text# (outputs plain text with no formatting).

text_transforms

Templates for special text transformations.

citation

Maps citation variant names to LaTeX citation commands. The value is the command name (without backslash). Texpile automatically generates the full command with #key#, #pre#, and #post# placeholders.

To map all variants to a single command (e.g., IEEE):

{
  "citation": {
    "autocite": "cite",
    "parencite": "cite",
    "textcite": "cite",
    "cite": "cite"
  }
}

ref

Templates for cross-references. Placeholder: #label# (the reference label).

Example (IEEE-style references):

{
  "ref": {
    "figure": "Fig.~\\ref{#label#}",
    "table": "Table~\\ref{#label#}",
    "equation": "\\eqref{#label#}"
  }
}

table

Templates for table structure. Contains sub-keys for each part of the table.

Structure templates:

tableColumnPattern: controls the column specifiers in the tabular environment.

tableBorders: controls border lines.

Example (booktabs-style table):

{
  "table": {
    "tableBorders": {
      "top": "\\toprule",
      "bottom": "\\bottomrule",
      "headerRow": "\\midrule",
      "vertical": false,
      "partialRule": "\\cmidrule"
    }
  }
}