Configuration

gramr reads three files. In all of them, unknown keys are errors, so a typo never goes unnoticed.

File	Where	What for
Global configuration	~/.config/gramr/config.toml	Defaults shared by all sites. Optional.
Site configuration	~/.config/gramr/sites/<site>.toml	One per site: where the site repository and the notes are, where to push.
Repository configuration	gramr.toml, in the site repository	How the site is built. Created by gramr init.

~/.config is $XDG_CONFIG_HOME when it is set.

Global configuration

~/.config/gramr/config.toml. gramr config edit creates and opens it.

[source]
path = "~/Notes"    # default source folder

Key	Default	Rules
source.path	none	Absolute, or starting with ~.

Site configuration

~/.config/gramr/sites/<site>.toml. The file name is the site name, used in gramr publish <site> and in the notes' gramr.site: letters, digits, - and _ only. gramr site list lists them.

[repository]
url = "ssh://git@forgejo.example.com/sites/blog.git"
ref = "main"
# path = "~/dev/blog"     # or a local folder

[source]
path = "~/Writing/Blog"   # optional: overrides the global source folder
include = ["**"]          # optional: restrict the folders scanned
default_section = "notes"

[image]
name = "forgejo.example.com/sites/blog"

Key	Default	Rules
repository.url + repository.ref	—	Remote site repository. ref is a branch, a tag or a commit SHA.
repository.path	—	Local folder. It does not need to be a Git repository. Absolute, or starting with ~. Set either url + ref, or path, not both.
source.path	global source.path	Absolute, or starting with ~. Required here if the global configuration does not set it.
source.include	["**"]	Glob patterns relative to source.path. * does not cross /, ** does: Blog/* only matches notes directly in Blog/. Must not be empty. Links and attachments are still resolved against the whole folder.
source.default_section	required	Section of notes without gramr.section.
image.name	required	Image name without tag or digest, e.g. forgejo.example.com/sites/blog. A registry port (registry:5000/blog) is fine.

How the site repository is used

gramr never modifies the site repository. It copies it into a temporary workspace, writes the notes there, and builds the image from it. The workspace is removed when gramr exits, unless --keep-workspace is set.

Site repository	Workspace
url + ref	Cloned without history, submodules included (Zola themes are often submodules). Authentication uses your SSH or credential setup.
path	Copied as is, uncommitted changes included, skipping what the folder's own .gitignore files exclude (public/, node_modules/…). Your global Git excludes are ignored, so the copy is the same on every machine.

.git folders are always removed: the image never contains the history.

With a branch as ref, two builds may use different commits; the git-<sha> tag records the one actually used. Fetching a commit by its SHA depends on the server: if it refuses, use a branch or a tag.

Repository configuration

gramr.toml, at the root of the site repository. Required, but it can be empty: every key has a default. All paths are relative to the repository and must stay inside it.

[build]
dockerfile = "Dockerfile"
context = "."
platforms = ["linux/arm64"]

[content]
generator = "zola"
dir = "content"
assets_dir = "static/assets"
section_index = "_index.md"

Key	Default	Rules
build.dockerfile	Dockerfile
build.context	.	Docker build context.
build.platforms	[]	Target platforms, e.g. linux/arm64. Empty means the platform of the machine running gramr. preview always uses it.
content.generator	zola	Only zola for now. Zola ≥ 0.23 is required for unlisted pages.
content.dir	content	Where pages are written. For Zola, must be inside content/.
content.assets_dir	static/assets	Where attachments are copied. For Zola, must be inside static/ (served at /).
content.section_index	_index.md	A section exists only if its folder contains this file. A file name, not a path.