pandoc-template

A tern template for converting Markdown to HTML via pandoc.

Setup

In your project's .tern/config.toml:

[[templates]]
name = "pandoc-template"
url = "https://codeberg.org/Nicothekiller/tern-pandoc-template.git"

Usage

# 1. Install/update the template
tern --update

# 2. Convert your markdown files
tern

# Rebuild everything after a template update (outputs are only regenerated
# for files tern hasn't seen change since the last conversion):
tern --force

What it does

Step	What happens
tern --update	Clones/pulls the template, installs converters and data files
tern	Runs the pandoc converter on .md files in docs/, outputs HTML to docs-html/, and automatically runs setup.sh (pipeline snippet) to sync docs.css / docs.js into docs-html/

Warning: the docs.css / docs.js copies in docs-html/ are overwritten on every tern run by setup.sh. Don't edit them there — customize the files in .tern/data/pandoc-template/ instead. Tern only rewrites .tern/data/pandoc-template/ when you run tern --update; normal runs never touch it.

Note that tern --update also replaces .tern/data/pandoc-template/ with the template version, wiping customizations there. Back up your edits before updating, or fork this template repo and point your .tern/config.toml at your fork for durable customization.

Directory layout

project/
├── .tern/
│   ├── config.toml
│   ├── cache/pandoc-template/      # cloned repo
│   ├── converters/pandoc-template/ # pandoc.lua converter
│   └── data/pandoc-template/       # docs.html, docs.css, docs.js, filters, setup.sh
├── docs/                           # source markdown files
└── docs-html/                      # generated HTML + docs.css + docs.js

Features

All features are controlled through YAML front matter in your markdown files or standard Pandoc/HTML syntax.

Front Matter Variables

---
title: My Page
subtitle: A deeper look
author: Jane Doe
date: 2025-01-01
lang: es
dir: rtl
description: Page description for SEO
keywords: docs, guide
favicon: /favicon.ico
---

Variable	Effect	Rendered as
title	Page title + <h1> header	<title> + header block
subtitle	Subtitle below title	<p class="subtitle">
author	Author name(s)	<p class="author">
date	Publication date	<p class="date">
lang	Language attribute	<html lang="es"> (defaults to en)
dir	Text direction	<html dir="rtl">
description	Meta description	<meta name="description">
keywords	Meta keywords	<meta name="keywords">
favicon	Favicon path	<link rel="icon">
mermaid-theme	Mermaid color theme	theme passed to mermaid.initialize (default: default)

Link Rewriting

Links to other markdown files are rewritten automatically:

See the [installation guide](install.md) and the [FAQ](faq.md#troubleshooting).

becomes install.html and faq.html#troubleshooting in the generated HTML, so you can link sources directly and the docs work when served as HTML. Only the path part of a relative link target ending in .md is rewritten — #anchors and ?query strings are preserved as-is, and code blocks, inline code and absolute URLs (https://…, mailto:…) are left untouched.

Asset Paths

The stylesheet and script are referenced with a relative prefix (the template exposes it as the root metadata variable), so generated pages work:

• served from the output root (docs-html/)
• served from a subpath (e.g. GitHub Pages project sites at /repo/)
• opened directly from the filesystem via file://

No configuration needed.

Table of Contents

Enabled by default. To customize the heading:

---
toc-title: Contents
---

MathJax

LaTeX math is rendered via MathJax 3 (loaded from CDN). Use standard Pandoc math syntax:

Inline: $E = mc^2$

Display: $$ \int_a^b f(x) \, dx $$

MathJax is only loaded on pages that actually contain math.

Mermaid

Diagrams rendered with Mermaid v11 (loaded from CDN). Use fenced code blocks with the mermaid class:

```mermaid
graph LR
    A[Start] --> B{Decision}
    B -->|Yes| C[Continue]
    B -->|No| D[Stop]
```

No configuration needed. Mermaid is only loaded on pages that actually contain diagrams. The color theme can be set per page via front matter:

---
mermaid-theme: dark
---

Tabsets

Add {.tabset} to any heading to create tabbed sections. Child headings one level deeper become the tabs:

## Installation {.tabset}

### Linux
sudo apt install pandoc

### macOS
brew install pandoc

### Windows
choco install pandoc

All heading levels work (## {.tabset} → ### tabs, ### {.tabset} → #### tabs), and tabsets can be nested (tabs inside tabs).

Image Maximizer

Click any image or SVG larger than 200px to open it in a full-screen viewer with:

• Scroll wheel — zoom in/out
• Drag — pan around
• R key — reset zoom
• + / - keys — quick zoom
• ESC / click outside — close

No configuration needed — works automatically on all <img> and <svg> elements.

Details / Summary

Native HTML <details> elements are styled with custom +/- indicators:

<details>
<summary>Click to expand</summary>

Hidden content here...
</details>

Chat Bubbles

Styled containers for conversation-style layouts:

<div class="chat-container">

<div class="message executor">
**Executor**
Your message content here
</div>

<div class="message target">
**Target**
Their reply here
</div>

</div>

• .executor — left-aligned, subtle gray border
• .target — right-aligned, subtle blue border

Go to Top

Add a fixed back-to-top button by adding a link with class go-top:

[Go to Top](#){.go-top}

Syntax Highlighting

Pandoc's built-in syntax highlighting is applied via $styles.html()$. Use fenced code blocks with language tags:

```python
def hello():
    print("Hello!")
```

Custom Head / Foot Content

Inject arbitrary HTML into <head> or before/after <body> via front matter:

---
header-includes: |
  <link rel="stylesheet" href="/custom.css">
include-before: |
  <div class="banner">Notice</div>
include-after: |
  <script src="/analytics.js"></script>
---