Amatl - Markdown processing utility

What's Amatl ?

Amatl is a simple command-line utility that can help you to transform your CommonMark (also known as Markdown) files into full-fledged HTML/PDF documents.

For example, this simple website is generated with Amatl itself.

Features

Create document from local or remote resources via URL resolving;
Integrate MermaidJS diagrams et code blocks with syntax highlighting;
Use custom directives to include others documents or generate tables of content;
Use pre-defined or custom layouts to transform your content into presentations, report, etc
Use Go templating to inject dynamic data into your document;
Rewrite you relative links and embed external resources.

Why the name amatl ?

Amate (Spanish: amate [aˈmate] from Nahuatl languages: āmatl [ˈaːmat͡ɬ] is a type of bark paper that has been manufactured in Mexico since the precontact times. It was used primarily to create codices.

Source: Wikipédia

Amatl is a free software project published under the MIT licence.

Getting started

Installation

🐧 On Linux

Visit the latest release page or use the following wget command:

wget https://github.com/Bornholm/amatl/releases/download/v0.27.1/amatl_0.27.1_linux_amd64.tar.gz

Replace amd64 by your architecture.

Extract the binary then move it to your preferred location, for example /usr/local/bin
```
tar -xzf amatl_0.27.1_linux_amd64.tar.gz
sudo mv ./amatl /usr/local/bin
```

Check that your installation is ok by running the --help command

 amatl help

The command should return something like this:

 NAME:
   amatl - a markdown to markdown/html/pdf compiler

 USAGE:
   amatl [global options] command [command options]

 COMMANDS:
   render
   help, h  Shows a list of commands or help for one command

 GLOBAL OPTIONS:
   --debug            Enable debug mode (default: false) [$AMATL_DEBUG]
   --log-level value  Set logging level (default: "info") [$AMATL_LOG_LEVEL]
   --workdir value    The working directory [$AMATL_WORKDIR]
   --help, -h         show help

🪟 On Windows

Visit the latest release page and download the file named:
```
amatl_0.27.1_windows_amd64.tar.gz
```
Replace amd64 with your architecture if needed.
Uncompress the archive with your preferred archive extractor.
Move amatl.exe to a directory included in your PATH (e.g., C:\Program Files\Amatl\) or run it directly from the extracted folder.
Open PowerShell or Command Prompt and run:
```
amatl.exe help
```
You should see the list of commands and global options, confirming the installation was successful.

Why does my virus-scanning software think the binary is infected?

This is a common occurrence, especially on Windows machines, and is almost always a false positive.

More informations on the official Go FAQ

🍎 On MacOS

Visit the latest release page or use curl:
```
curl -LO https://github.com/Bornholm/amatl/releases/download/v0.27.1/amatl_0.27.1_darwin_amd64.tar.gz
```
Replace amd64 with your CPU architecture (e.g., arm64 for Apple Silicon).

Extract the archive and move the binary:

tar -xzf amatl_0.27.1_darwin_amd64.tar.gz
sudo mv ./amatl /usr/local/bin

Verify the installation:
```
amatl help
```
You should see the CLI help output, confirming that Amatl is installed.

Usage

Amatl's render command allows you to convert Markdown files into various output formats. Below are common use cases.

🖥️ Generate an HTML file

amatl render html -o output.html your-file.md

This will convert your-file.md into a standalone output.html file.

🖨️ Generate a PDF file

Note: PDF generation requires Chrome or Chromium to be installed on your system.

amatl render pdf -o output.pdf your-file.md

This creates a output.pdf file from the specified Markdown input.

📝 Generate a Markdown file (processed)

Useful for combining multiple files using the include{} directive or for generating a table of contents using toc{}.

amatl render markdown -o output.md your-file.md

This produces a processed Markdown file with all directives resolved.

URL Resolving

Amatl provides a flexible URL resolver to access various types of resources. It supports the following URL schemes:

file:// — Refers to local filesystem resources. Paths without a scheme are also interpreted as local files.
http:// and https:// — Used to access HTTP(S) resources.
stdin:// — Refers to data piped in via standard input (stdin).

These URL schemes can be used consistently across the application, including when specifying inputs for commands like render.

🔐 Basic authentication

Amatl supports HTTP Basic Authentication for http(s):// URLs.

To enable it, set the following environment variables:

AMATL_HTTP_BASIC_AUTH_USERNAME

AMATL_HTTP_BASIC_AUTH_PASSWORD

When these variables are set, credentials are automatically applied to all HTTP(S) requests during URL resolution.

Variables and Templating

Available for: Markdown, HTML, PDF

Amatl supports dynamic content injection using Go templates. This allows you to define reusable or customizable elements directly within your documents.

🔧 Injecting variables

Use the --vars option with a URL (e.g., a local file or stdin://) pointing to a JSON document containing your variable values. These will be accessible within the template under .Vars.

Example:

echo '{"foo": "bar"}' | amatl render pdf --vars stdin:// my-doc.md

In my-doc.md, you can access the variable like this:

# My Document

Here my value will be replaced: {{ .Vars.foo }}

Amatl also includes the full Sprig function library to enhance template expressions with string manipulation, logic functions, and more.

📄 Using metadata from YAML front matter

Amatl parses YAML front matter and exposes its content through the .Meta object in templates. This is particularly useful for static values defined in the document itself.

---
foo: "bar"
---

# My Document

Here my value will be replaced: {{ .Meta.foo }}

Directives

Available for: Markdown, HTML, PDF

Amatl extends the CommonMark syntax with what we call "directives".

A directive takes this form:


:directive{attr="value1", attr="value2", ...}

Please take note of the linefeed before and after the directive. They are required.

Each directive triggers a specific behavior based on its type.

`:include{url="<url>", fromHeadings="<headingLevel>", shiftHeadings="<levelShift>"}`

Include another Markdown file in your document.

Parameters

`url="<url>"`

Required

The URL of the Markdown document to include. This can be a local file or a remote document's URL (see "URL resolving").

`fromHeadings="<headingLevel>"`

Optional
Type: int

Only include sections that match the given heading level threshold.

`shiftHeadings="<levelShift>"`

Optional
Type: int

Shift the included headings by the given amount.

`:toc{minLevel="<minLevel>", maxLevel="<maxLevel>"}`

Generate a table of contents for the whole document.

Parameters

`minLevel="<minLevel>"`

Optional
Type: int

Only include headings matching this minimum level.

`maxLevel="<maxLevel>"`

Optional
Type: int

Only include headings matching this maximum level.

`:attrs{attributes...}`

Assign the given attributes to the following element (for example class, id, etc).

Layouts

Available for: HTML, PDF

A layout is an HTML template that can be used to decorate your rendered Markdown content.

Layouts allow you to:

Insert content before or after the main Markdown content.
Apply custom styling or structural transformations to match your organization's branding or formatting needs.
Use layout-specific variables to further enhance the output.

Amatl provides three built-in layouts, and you can also supply your own custom layout using the --html-layout flag.

✨ Built-in layouts

`amatl://document.html`

A clean, print-friendly layout designed for general documents (e.g. reports or papers), formatted in A4 by default.

Default layout for HTML and PDF outputs.
Best suited for structured, text-heavy documents.

Example: 📄 View sample document (PDF)

Variables:

title: Sets the HTML document title.

`amatl://presentation.html`

A layout for creating slide-style presentations from your Markdown content.

Example: 📊 View sample presentation (PDF)

Variables:

title: Sets the HTML document title.

`amatl://website.html`

A simple, responsive layout suitable for rendering Markdown as a web page.

Example: 🌐 Visit example website

Variables:

title: Sets the HTML document title.

🛠️ Using a custom layout

To use a custom layout, provide the path or URL with the --html-layout flag:

amatl render markdown -o output.html --html-layout file://my-layout.html my-doc.md

How to

Write your own layout

Coming soon...

Use in CI

Coming soon...

🙏 Attributions

This project wouldn’t be possible without the incredible work of the open-source community. Special thanks to:

Thank you for your amazing work !

What's Amatl ?

Features

Getting started

Installation

🐧 On Linux

🪟 On Windows

🍎 On MacOS

Usage

🖥️ Generate an HTML file

🖨️ Generate a PDF file

📝 Generate a Markdown file (processed)

URL Resolving

🔐 Basic authentication

Variables and Templating

🔧 Injecting variables

📄 Using metadata from YAML front matter

Directives

:include{url="<url>", fromHeadings="<headingLevel>", shiftHeadings="<levelShift>"}

Parameters

url="<url>"

fromHeadings="<headingLevel>"

shiftHeadings="<levelShift>"

:toc{minLevel="<minLevel>", maxLevel="<maxLevel>"}

Parameters

minLevel="<minLevel>"

maxLevel="<maxLevel>"

:attrs{attributes...}

Layouts

✨ Built-in layouts

amatl://document.html

amatl://presentation.html

amatl://website.html

🛠️ Using a custom layout

How to

Write your own layout

Share your configuration

Use in CI

🙏 Attributions

`:include{url="<url>", fromHeadings="<headingLevel>", shiftHeadings="<levelShift>"}`

`url="<url>"`

`fromHeadings="<headingLevel>"`

`shiftHeadings="<levelShift>"`

`:toc{minLevel="<minLevel>", maxLevel="<maxLevel>"}`

`minLevel="<minLevel>"`

`maxLevel="<maxLevel>"`

`:attrs{attributes...}`

`amatl://document.html`

`amatl://presentation.html`

`amatl://website.html`