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

Skip to content

# Quickstart

Spin up a small Engrave site to see how HTML rendering, Markdown inclusion, and asset copying work together.

## 1) Install

Shell

    pip install engrave

## 2) Create a source tree

Use any layout you like. Only `.html` files are rendered; any path segment starting with `_` is skipped for HTML output (handy for partials/includes). Markdown lives alongside templates and is pulled in from HTML.

Shell

    site/
      base.html
      index.html
      about/index.html
      includes/intro.md
      assets/site.css

Example `base.html`:

HTML

    <!doctype html>
    <html>
      <head>
        <meta charset="utf-8" />
        <title>{{ title or "Engrave demo" }}</title>
        <link rel="stylesheet" href="/assets/site.css" />
      </head>
      <body>
        <main>
          {{ markdown('includes/intro.md') }}
          {% block content %}{% endblock %}
        </main>
      </body>
    </html>

Example `index.html`:

HTML + Jinja

    {% extends "base.html" %}
    {% set title = "Home" %}
    {% block content %}
      <h1>Welcome</h1>
      <p>Edit this file and rebuild to see Engrave render it.</p>
    {% endblock %}

`includes/intro.md`:

Markdown + Jinja

    ## Engrave

    This site is rendered from HTML templates. Markdown is pulled in on demand with
    {% raw %}`{{ markdown("includes/intro.md") }}`{% endraw %}.

> Markdown snippets are rendered as Jinja templates first, so you can reference page variables inside them.

## 3) Build once

Shell

    $ engrave build site/ build/ --copy '.*\.(css|png|svg)$' --exclude 'drafts/.*'

- HTML under `site/` is rendered into `build/` (segments prefixed with `_` are skipped for HTML rendering).
- Assets matching the regex are copied verbatim; `--exclude` uses regex matching against the path string to skip both rendering and copying.
- Add `--log-level DEBUG` (or set `LOG_LEVEL`) if you want more verbose output.

## 4) Develop with Live Reload (SSE)

Shell

    $ engrave server site/ build/ --copy '.*\.(css|png|svg)$' \
    --watch-add 'build/.*\.(js)$'

- Engrave builds once, renders `.html` requests directly from `site/`, and copies matching assets into `build/`.
- Watches `.html` and `.md` under `site/` plus any copy targets. Add `--watch-add REGEX` for extra paths relative to your current working directory—these emit SSE events only (no auto-copy/build).
- Browse `http://127.0.0.1:8000/` and add the reload snippet from Live Reload for auto-refresh via SSE (default endpoint `/__engrave/watch`).