bulletin.md

An open, Markdown-based file format for worship bulletins.

A .bulletin.md file is a single UTF-8 text document that represents one bulletin — the order of worship a congregation holds on paper — in a form that is human-readable, machine-parseable, and portable. A person can read and edit it, an AI can reason over it, and a renderer can lay it out.

---
bulletin_spec: "1.0"
---

## Gathering Hymn {.section type=hymn ref=opening_hymn}
{{opening_hymn.title}}

Frontmatter is data, body is content, directives ({.section …}) are presentation, and {{merge.tags}} mark the parts that change every week. Stripped of every directive and tag, the file still reads as clean Markdown — that's a design rule, not an accident.

The normative specification is SPEC.md (v1.0, Stable). If you are implementing a parser, a serializer, or any tool that reads or writes bulletins, that document is the contract — including its diagnostics table and the rule that unknown things are surfaced, never silently dropped.

Why an open format

Churches should own their bulletins as plain files, forever, with no proprietary lock-in. And tools should be able to cooperate: presentation software, church-management systems, denominational publishers — anything can read and write the same file. The goals (portability, round-trip fidelity, graceful degradation, openness) are specified in SPEC.md §1.2.

Conformance

conformance/ holds the fixture suite an implementation must pass: canonical documents, expected ASTs, adversarial inputs, and expected diagnostics. The contract (what to assert, including byte-identical serialization and lossless round-trips) is documented in conformance/README.md. CI on this repository checks fixture integrity; implementations run the same fixtures through their own parser and serializer.

Who reads and writes it

• QuickBulletins — the reference user: imports .bulletin.md natively and exports every bulletin back to it (the format is the product's forever-export).
• Lutheran Kit — bulletin export planned; the first independent writer.
• Your tool next — the format is MIT-licensed, and scope-fitting fixture contributions are welcome.

Versioning

The bulletin_spec frontmatter key is required and versioned (currently "1.0"). Parsers MUST reject a major version they do not implement rather than guess. MINOR additions are backwards-compatible (new section types, new optional keys); anything breaking is a MAJOR.

License

Specification text, fixtures, and any reference code: MIT © Heavenly Technologies LLC — see LICENSE and the license note in SPEC.md.