Export format

An instance's content as plain files: YAML for types and the profile, markdown with frontmatter for entries. export_content writes it, import_content reads it, and the bundled demos are written in it. A bundle written by hand is a way to set up a new instance's content in a text editor and keep it in git.

This page describes format version 1.

Layout

lapidarium.yaml               format version
profile.yaml                  profile and links
types/<key>.yaml              type settings and fields
content/<type>/<slug>.md      frontmatter, then the text parts as the body
assets.yaml                   alt text per asset path
assets/…                      the files, at the paths entries refer to

Keys left at their default are not written, and you may leave them out by hand. Every setting is described in Content; the keys are the field names there in snake_case.

lapidarium.yaml

format: 1

profile.yaml

The profile's fields, plus links, a list of platform, url and label. photo is an asset path.

name: Sam Rivera
handle: samrivera
tagline: I build small, boring, durable tools for the web, and talk about them.
photo: assets/demo/sam.svg
bio: Maintainer of a handful of Python libraries. Prefers HTML that works without JavaScript.
email: sam@example.com
links:
  - platform: github
    url: https://github.com/example
    label: GitHub
  - platform: mastodon
    url: https://fosstodon.org/@example
    label: Mastodon

types/<key>.yaml

A type's settings, then fields, in order. The file name must match key.

key: talk
label: Talk
label_plural: Talks
route: talks
colour: '#6639ba'
icon: mic
order: 2
layout: media_first
allowed_parts: [text, video, file, link]
required_parts: [video]
door_enabled: true
list_filters: [year, tag]
fields:
  - key: event
    label: Event
    kind: text
    show_on_card: true
  - key: slides_url
    label: Slides
    kind: url

A calendar type:

key: event
label: Event
label_plural: Events
route: events
colour: '#a2306f'
icon: event
order: 5
role: calendar
allowed_parts: [text, link]
door_enabled: true
door_pick: upcoming
fields:
  - key: role
    label: Role
    kind: choice
    choices: [organizer, speaker, attendee]
    required: true
    show_on_card: true

content/<type>/<slug>.md

The type and the slug come from the path, not the frontmatter. Frontmatter keys, in the order they are written:

title, summary, date, start_at, end_at, location, is_online, outcome, external_url, status, featured, hide_from_whats_new, license, cover, tags, metadata, parts, relations, syndication, created_at, updated_at.

• status defaults to draft; write published for the entry to appear.
• metadata holds the type's own fields, by key.
• parts lists every part in order, each with kind and as needed url, asset, caption and options. A text part is just - kind: text; its text is the body.
• Several text parts split the body with <!-- part -->, one section per text part, in order. The counts must match.
• relations are role and to, where to is <type>/<slug>.
• syndication lists platform and url.

---
title: Zero Node Django
summary: Shipping a modern front end with plain CSS, ES modules and no build step.
date: 2026-06-05
status: published
featured: true
tags: [django, css]
metadata:
  event: DjangoCon Europe 2026
  slides_url: https://example.com/slides/zero-node
parts:
  - kind: video
    url: https://www.youtube.com/watch?v=dQw4w9WgXcQ
  - kind: text
  - kind: file
    asset: assets/demo/zero-node-slides.txt
    caption: Slide outline
    options:
      download_label: Download the outline
relations:
  - role: related
    to: repo/lapidarium
---
Most sites need less tooling than they carry. This talk removes it piece by piece.

assets.yaml and assets/

Each file an entry or the profile refers to sits at its path under assets/, and assets.yaml gives its alt text. Paths stay under assets/; .. is refused.

- path: assets/demo/sam.svg
  alt: Line drawing of a person with a laptop.
- path: assets/demo/zero-node-slides.txt
  alt: ''

Checks on import

import_content validates the whole bundle before it writes anything, and reports every problem by file:

• the format version is one it reads;
• keys and slugs are [-a-zA-Z0-9_]+;
• type colours pass the contrast check against the active theme;
• list_filters name year, tag or a field of the type;
• metadata keys are fields of the type and their values fit the field kind;
• built-in fields are only those the type's role uses, with end_at on or after start_at;
• parts are allowed by the type, required parts are present, and their assets exist;
• relations point at other entries in the same bundle, part_of at a container, without loops, and never from published to draft.

The full demos are in src/lapidarium/links/content_files/demos/.