Templates & Markdown - Engrave Guide
Description: Guides for the Engrave, A lightweight static-site generator built on Python and Jinja.

Skip to content

# Templates + Markdown

Engrave renders Jinja2 templates discovered under your source directory. Use standard Jinja features plus a built-in Markdown helper/filter.

## Rendering rules

- Only `.html` files are rendered. A template is skipped if any path segment starts with `_` (e.g., `_partials/header.html`), but it can still be included by other templates.
- The relative path under `DIR_SRC` is preserved in `DIR_DEST` (e.g., `pages/about/index.html` stays nested).
- Jinja loads templates relative to `DIR_SRC` (or a list of template roots if you pass more than one), so `{% extends "base.html" %}` or `{% include "partials/nav.html" %}` work as usual.

## Bringing in Markdown files

Use the global `markdown()` helper inside templates to load and render a Markdown file relative to the current template.

HTML

    <article>
      {{ markdown('includes/intro.md') }}
    </article>

Details: - Markdown files are rendered as Jinja templates first (using the current context), then converted to HTML, so you can use template variables in your `.md` snippets. - Paths must be relative to the template; absolute paths raise an error and attempts to escape outside the configured loader roots are blocked. - Lookups walk the loader search paths (handy when you pass multiple template roots) and fall back with a `FileNotFoundError` if the file is missing. - File reads and compilation are cached per modification time, but Markdown content is re-rendered for each request so context changes are reflected.

## Inline Markdown filter

Convert inline strings to HTML with the `markdown` filter. Results are cached with an LRU to avoid repeated parsing.

HTML

    <p>{{ "This text **is** inline markdown." | markdown }}</p>

## Organizing partials and assets

- Keep non-page templates under `_partials/` or any `_`-prefixed folder to prevent standalone rendering (copy rules still apply to those paths).
- Store reusable Markdown snippets in `includes/` (or any folder) and pull them into pages with `markdown()`.
- Pair your templates with asset copy rules (`--copy '.*\\.(css|js|svg)$'`) so builds place files alongside rendered HTML.