From nothing to a published site, in one page. Each step links to the reference if you want the details.

Status: early development. Expect rough edges.

What you need

  • Git, to fetch remote site repositories.
  • Docker with Buildx (included in Docker Desktop and recent Docker Engine packages).
  • A Zola site: a folder with a config.toml, a theme or templates. zola init creates one.
  • A container registry you can push to (docker login done): Forgejo, Gitea, GHCR, Docker Hub…
  • Notes in Markdown, in any folder: an Obsidian vault, a Logseq graph or plain .md files.

1. Install gramr

gramr is not packaged yet. Install it with Cargo:

cargo install --git ssh://git@forgejo.smoowy.fr:2322/smoowy/gramr.git

Or from a clone: cargo install --path .

2. Prepare the site repository

In your Zola site, run:

gramr init

It creates gramr.toml (how the site is built), a Dockerfile and a .dockerignore. Existing files are kept. See gramr init.

Then create the section your notes will go into. A section is a folder of content/ with an _index.md:

mkdir -p content/notes
printf -- '+++\ntitle = "Notes"\n+++\n' > content/notes/_index.md

gramr never creates sections: they belong to the site, with their templates, sorting and pagination.

3. Describe the site

Create ~/.config/gramr/sites/blog.toml. The file name is the site name: here, blog.

[repository]
path = "~/dev/blog"                # the site repository, a local folder
# url = "ssh://git@example.com/sites/blog.git"   # or a remote repository…
# ref = "main"                                   # …and a branch, tag or commit

[source]
path = "~/Notes"                   # where your notes are
default_section = "notes"          # the section created above

[image]
name = "registry.example.com/sites/blog"   # no tag: gramr adds them

gramr init prints this file with your values. Every key is in the configuration reference.

4. Check your setup

gramr doctor

It checks Docker, Buildx, Git, the Zola version and every site configuration, without building anything.

5. Mark a note for publication

Nothing is published unless a note says so. Add a gramr block to its front matter:

---
gramr:
  publish: public
  site: blog
title: My first page
---

Hello from gramr.

The page goes to the default_section (notes). Use section: … to put it elsewhere. See Writing notes.

6. See what would be published

gramr publish blog --dry-run

It lists the pages, the attachments, the links gramr had to remove and the image tags, without building anything. Every problem (missing section, ambiguous link…) is reported here.

7. Preview the site

gramr preview blog

The site is built and served at http://localhost:8080 until Ctrl+C. See Previewing.

8. Publish

gramr publish blog

gramr builds the image and pushes it to your registry, then prints the tags and the digest. Running it is up to you: see Deploying.

Next