Breaking change: .env replaced by project.conf + pandoc.yaml

[lex57ukr]

What changed

The .env configuration file has been removed and replaced by two purpose-built files:

File	Purpose
project.conf	Operational settings only — project name and Docker naming
pandoc.yaml	All book metadata — title, author, date, PDF layout, EPUB options, etc.

This is not a simple rename. The old .env mixed operational plumbing with book content in a single flat file. The new structure separates these concerns entirely.

Why we made this change

1. Unicode corruption

The previous system used environment variables from .env as a fallback to inject metadata into Pandoc via -M command-line flags (e.g., -M author="François Müller"). Pandoc's CLI corrupts unicode characters passed through -M flags. This caused garbled author names, titles, and descriptions for anyone using non-ASCII characters.

By making pandoc.yaml the sole metadata source, Pandoc reads the YAML file natively — unicode is preserved perfectly.

2. Single source of truth

The old system had a confusing dual-path: metadata could come from either user-metadata.yaml or .env environment variables, with a fallback chain in publish.sh. This made it unclear which file actually controlled your book's output. Now there is exactly one place for all book settings: pandoc.yaml.

3. Cleaner separation of concerns

The old .env crammed together unrelated settings — your book's title sat next to Docker container naming. The new split puts operational plumbing in project.conf (you set this once and forget it) and everything about your book's content and appearance in pandoc.yaml.

4. Better discoverability

pandoc.yaml is a well-commented YAML file with references to Pandoc documentation. Settings like papersize, geometry, fontfamily, and cover-image are documented inline with accepted values and examples — no more guessing at KEYSTONE_LATEX_GEOMETRY variable names.

How to migrate your existing project

Step 1: Rebuild your Docker image

The updated publish.sh inside the container expects the new configuration files. You must rebuild your local image to pick up these changes:

make image

This runs docker compose build and bakes the new publish.sh into your project's image. Builds will fail if you skip this step — the old image still expects .env environment variables for metadata.

Step 2: Create project.conf

In your project root (next to where .env used to be), create project.conf:

# ------------------------------------------------------------------------------
# Keystone project configuration
# ------------------------------------------------------------------------------

# The name of your project (used in artifact filenames, e.g., my-book-20250101.pdf)
KEYSTONE_PROJECT=my-book

# Docker configuration (usually no changes needed)
KEYSTONE_DOCKER_COMPOSE_PROJECT=keystone-${KEYSTONE_PROJECT}
KEYSTONE_DOCKER_IMAGE=${KEYSTONE_DOCKER_COMPOSE_PROJECT}

Replace my-book with whatever you had as KEYSTONE_PROJECT in your old .env.

Step 3: Create pandoc.yaml

Create pandoc.yaml in your project root. Move your book metadata from the old .env variables into YAML format:

---
title: My Book Title
subtitle: An optional subtitle
author: Your Name
date: auto
lang: en-US
footer-copyright: auto

description: |
  A short description of your book.

keywords:
  - keyword1
  - keyword2

# PDF layout
papersize: letter
geometry: margin=1in
fontsize: 10pt
fontfamily: libertine

# EPUB cover image (comment out if not using EPUB)
# cover-image: ./assets/cover.jpg
...

Here's how the old .env variables map to pandoc.yaml fields:

Old .env variable	New pandoc.yaml field
KEYSTONE_TITLE	title
KEYSTONE_SUBTITLE	subtitle
KEYSTONE_AUTHOR	author
KEYSTONE_DATE	date
KEYSTONE_FOOTER_COPYRIGHT	footer-copyright
KEYSTONE_DESCRIPTION	description
KEYSTONE_KEYWORDS	keywords (YAML list)
KEYSTONE_LATEX_PAPERSIZE	papersize
KEYSTONE_LATEX_GEOMETRY	geometry
KEYSTONE_LATEX_FONTSIZE	fontsize
KEYSTONE_LATEX_FONTFAMILY	fontfamily
KEYSTONE_COVER_IMAGE	cover-image

Step 4: Update Makefile

Open your Makefile and change the include line near the top:

-include .env
+include project.conf

Also update every line that references .env as the --env-file flag. Look for the DC variable and change it:

-DC = docker compose -p $(KEYSTONE_DOCKER_COMPOSE_PROJECT) --file $(COMPOSE_FILE) --env-file .env
+DC = docker compose -p $(KEYSTONE_DOCKER_COMPOSE_PROJECT) --file $(COMPOSE_FILE) --env-file project.conf

Step 5: Update docker-compose.yaml

In your .docker/docker-compose.yaml, make two changes:

1. Update env_file to point to project.conf instead of .env:

   env_file:
     - ../project.conf

2. Add the pandoc.yaml bind mount to the volumes section:

   volumes:
     - ../pandoc.yaml:/keystone/.pandoc/metadata/user-metadata.yaml:ro

   This mounts your pandoc.yaml as the metadata file Pandoc reads inside the container.

Step 6: Delete .env

Once you've verified your new files are in place, remove the old .env:

rm .env

Step 7: Build and verify

Run your usual build command (make publish, make all, etc.) and verify the output looks correct.

Important notes

• pandoc.yaml must not be empty. The build will hard-fail if the file exists but is empty. It must contain at least your book's title and author.
• cover-image must be commented out if unused. Setting cover-image: with no value (YAML null) will crash EPUB builds. Comment out the line entirely if you don't have a cover image.
• The env-var fallback is gone. There is no longer any mechanism to inject metadata through environment variables. All book metadata must live in pandoc.yaml.

Questions?

If you run into any issues migrating, please open a discussion in the Q&A category and we'll help you out.