Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
22 changes: 14 additions & 8 deletions docs/tasks/follow-prov-vocabulary-shape-and-term-holds.md
Original file line number Diff line number Diff line change
@@ -1,21 +1,27 @@
---
title: Follow prov's vocabulary shape, term holds and field stamps
part_of: '[Tasks](/docs/tasks/tasks.md)'
status: open
status: done
author: adammharris
created: 2026-09-28
updated: 2026-10-06
updated: 2026-10-21
audience: public
---

# Follow prov's vocabulary shape, term holds and field stamps

**Where it stands, 2026-10-06.** Steps 1 to 6 landed in `2283376` (prov
0.16, taken from git rather than crates.io): the planner goes through
`Workspace::export_plan`, so a term holds a page back; `reify` is gone outside
`docs/proposals/`; the `hold` docs name a term; and plates' own `prov.yaml`
declares its stamps on the fields. Step 7 is what is left: `plates-render`
still reads a page's dates by the literal names `created` and `updated`.
**Status.** Done. Steps 1 to 6 landed in `2283376` (prov 0.16, taken from
git rather than crates.io): the planner goes through `Workspace::export_plan`,
so a term holds a page back; `reify` is gone outside `docs/proposals/`; the
`hold` docs name a term; and plates' own `prov.yaml` declares its stamps on the
fields. Step 7 followed: `plates-render` reads a page's dates through
`SiteOptions::date_fields`, a `DateFields` naming the fields the workspace
stamps, and `plates-cli` fills it from the config's `created_field()` and
`updated_field()`. The literal `created` and `updated` stay the fallback page
by page, so a workspace that declares no stamp, a page written before it did,
and a page mounted from a peer that stamps the literal names all keep their
dates. `a_page_shows_the_date_its_archive_stamps` builds an archive stamping
`modified` and finds that date on the page.

prov's next release changes three things plates reads, and plates does not
compile against it until they are followed. None is released yet: the
Expand Down
57 changes: 52 additions & 5 deletions plates-cli/src/build.rs
Original file line number Diff line number Diff line change
Expand Up @@ -23,9 +23,9 @@ use plates::{
CollectOptions, DigestMemo, FRONT_PAGE_KEY, MountOptions, NoStamp, RegistryLinks, SiteTheme,
collect_mounted, collect_site, plan_site, read_page_shells, read_term_config, read_theme,
};
use plates_render::SiteStyle;
use plates_render::html::Generator;
use plates_render::site::{SiteOptions, SourceDoc, humanize_name, render_site};
use plates_render::{DateFields, SiteStyle};

use crate::config::Source;
use crate::session::Session;
Expand Down Expand Up @@ -142,6 +142,10 @@ pub fn build_sites(
}

let ws = session.workspace()?;
let date_fields = DateFields {
created: session.config.created_field().map(String::from),
updated: session.config.updated_field().map(String::from),
};
// One read scope over the whole run, so a document reached by two sites is
// parsed once rather than once per site.
let _scope = ws.read_scope();
Expand Down Expand Up @@ -348,6 +352,7 @@ pub fn build_sites(
audience: &spec.audience,
root: &session.root_dir,
base_url,
date_fields: &date_fields,
},
collected,
identifiers,
Expand Down Expand Up @@ -441,6 +446,9 @@ struct Site<'a> {
root: &'a Path,
/// The address the site is served at, for canonical links and feeds.
base_url: Option<&'a str>,
/// The fields this archive stamps with a document's creation and edit
/// dates, as its own config declares them.
date_fields: &'a DateFields,
}

/// Render one collected site into the bytes that represent it.
Expand All @@ -460,6 +468,7 @@ fn assemble(
audience,
root,
base_url,
date_fields,
} = site;
let sources: Vec<SourceDoc> = collected
.sources
Expand Down Expand Up @@ -512,6 +521,10 @@ fn assemble(
// collection walked the relation this workspace configures, and the
// render layer has no workspace to ask.
outline: collected.outline,
// Which fields hold a page's dates, which only the workspace's
// config can say: an archive stamping `modified` keeps its edit
// date there.
date_fields: date_fields.clone(),
// Which document each page is, named the way a reference from
// outside this archive would name it.
identifiers,
Expand Down Expand Up @@ -669,9 +682,9 @@ mod tests {
assert!(identifiers(&collected, "", &[]).is_empty());
}

/// Every warning a build of the archive `files` says: the declaration's,
/// then each site's.
fn build_warnings(files: &[(&str, &str)]) -> Vec<String> {
/// A build of the archive `files`: the declaration's warnings, and the
/// sites.
fn build(files: &[(&str, &str)]) -> (Vec<String>, Vec<BuiltSite>) {
let dir = tempfile::tempdir().unwrap();
for (path, text) in files {
let path = dir.path().join(path);
Expand All @@ -680,7 +693,13 @@ mod tests {
}
let session = Session::open_at(dir.path()).unwrap();
let built = build_sites(&session, None, None, None).unwrap();
let mut warnings = session.warnings.clone();
(session.warnings.clone(), built)
}

/// Every warning a build of the archive `files` says: the declaration's,
/// then each site's.
fn build_warnings(files: &[(&str, &str)]) -> Vec<String> {
let (mut warnings, built) = build(files);
for site in built {
warnings.extend(site.warnings);
}
Expand Down Expand Up @@ -775,4 +794,32 @@ mod tests {

assert!(warnings.is_empty(), "{warnings:#?}");
}

/// A page in an archive that stamps its edits into `modified` shows that
/// date: the build reads the stamped fields off the workspace's config
/// rather than the literal `updated`.
#[test]
fn a_page_shows_the_date_its_archive_stamps() {
let (_, built) = build(&[
("README.md", ROOT),
(
"book.md",
"---\ntitle: Book\naudience: public\nmodified: 2026-03-04\n\
part_of: '[Vault](/README.md)'\n---\nRead me.\n",
),
("vocab/audiences.md", INDEX),
(
".config/config.yaml",
"fields:\n modified: { stamp: edit }\n\
exports:\n blog:\n label: Blog\n gate: { field: audience, value: public }\n",
),
]);

let book = String::from_utf8(built[0].files["book.html"].clone()).unwrap();
let modified = book
.lines()
.find(|l| l.contains("article:modified_time"))
.unwrap_or_else(|| panic!("no modified time on the page: {book}"));
assert!(modified.contains("2026-03-04"), "{modified}");
}
}
4 changes: 2 additions & 2 deletions plates-render/src/lib.rs
Original file line number Diff line number Diff line change
Expand Up @@ -65,6 +65,6 @@ pub use shell::{
#[cfg(feature = "syntax-highlighting")]
pub use syntax::{CLASS_PREFIX, HIGHLIGHTED_CLASS, Syntaxes, highlight_code_blocks};
pub use types::{
Arrangement, Expression, FrameDoc, Grain, Heading, LinkEdge, OutlineNode, PageLayout,
output_filename, serve_at_dest,
Arrangement, DateFields, Expression, FrameDoc, Grain, Heading, LinkEdge, OutlineNode,
PageLayout, output_filename, serve_at_dest,
};
84 changes: 79 additions & 5 deletions plates-render/src/site.rs
Original file line number Diff line number Diff line change
Expand Up @@ -27,7 +27,7 @@ use crate::html::{HtmlRenderer, PageContext, SiteStyle};
use crate::nav::{build_site_nav_tree, forest_roots, nav_for_page, neighbours, reading_order};
use crate::shell::{ShellExtension, ShellTemplate};
use crate::types::{
Heading, LinkEdge, NavLink, OutlineNode, PageLayout, PublishedPage, SiteNavNode,
DateFields, Heading, LinkEdge, NavLink, OutlineNode, PageLayout, PublishedPage, SiteNavNode,
};
// Where it was declared until 0.5.0. It lives in `types` now so that a caller
// that only *assembles* a header or footer — `plates::theme` — does not have
Expand Down Expand Up @@ -144,6 +144,10 @@ pub struct SiteOptions {
/// this existed got. Nodes naming documents this site does not publish are
/// pruned; their published descendants hoist. See [`crate::nav`].
pub outline: Vec<OutlineNode>,
/// Which frontmatter fields hold a page's dates, as the workspace stamps
/// them. The default reads the literal `created` and `updated`, which is
/// what every site published before this existed got. See [`DateFields`].
pub date_fields: DateFields,
/// The site's shell template, as the text of the template file.
///
/// A string rather than a path because this crate reads nothing: it is
Expand Down Expand Up @@ -300,6 +304,7 @@ impl Default for SiteOptions {
style: SiteStyle::default(),
arrangement: Arrangement::default(),
outline: Vec::new(),
date_fields: DateFields::default(),
template: None,
templates: IndexMap::new(),
lang: DEFAULT_LANG.to_string(),
Expand Down Expand Up @@ -644,8 +649,8 @@ fn collect_context(
}

let date = frontmatter::get_string(&fm, "date_of_document")
.or_else(|| frontmatter::get_string(&fm, "created"))
.or_else(|| frontmatter::get_string(&fm, "updated"))
.or_else(|| opts.date_fields.created_in(&fm))
.or_else(|| opts.date_fields.updated_in(&fm))
.filter(|d| !d.is_empty())
.map(String::from);
let group_keys = group_labels(
Expand Down Expand Up @@ -1391,8 +1396,8 @@ fn page_skeleton(
_ => None,
});

let created = frontmatter::get_string(fm, "created").map(String::from);
let updated = frontmatter::get_string(fm, "updated").map(String::from);
let created = opts.date_fields.created_in(fm).map(String::from);
let updated = opts.date_fields.updated_in(fm).map(String::from);
let date_of_document = frontmatter::get_string(fm, "date_of_document").map(String::from);
// One line, because the chain, the grain and the multi-valued case are all
// the view spec's to answer now — including the two spellings a field
Expand Down Expand Up @@ -2830,6 +2835,75 @@ mod tests {
assert!(orphan_page.parent_link.is_none());
}

/// A workspace that stamps `made` and `modified` rather than `created` and
/// `updated` has its pages' dates read from those fields — the names its
/// own config declares, which the layer holding the workspace passes in.
#[test]
fn a_page_reads_its_dates_from_the_fields_its_workspace_stamps() {
let note = "---\ntitle: Note\nmade: 2026-01-02\nmodified: 2026-03-04\n---\nBody.\n";
let opts = SiteOptions {
date_fields: DateFields {
created: Some("made".into()),
updated: Some("modified".into()),
},
..SiteOptions::default()
};

let pages = build_pages(&[src("index.md", note, true)], &opts);
assert_eq!(pages[0].created.as_deref(), Some("2026-01-02"));
assert_eq!(pages[0].updated.as_deref(), Some("2026-03-04"));
}

/// The literal names stay the fallback, page by page: a workspace that
/// declares no stamp reads `created` and `updated` as it always has, and a
/// page that predates the stamp — or comes from a mounted peer that stamps
/// the literal names — keeps its dates under one that does.
#[test]
fn a_page_without_the_stamped_field_falls_back_to_the_literal_name() {
let note = "---\ntitle: Note\ncreated: 2025-05-06\nupdated: 2025-07-08\n---\nBody.\n";
for date_fields in [
DateFields::default(),
DateFields {
created: Some("made".into()),
updated: Some("modified".into()),
},
] {
let opts = SiteOptions {
date_fields,
..SiteOptions::default()
};
let pages = build_pages(&[src("index.md", note, true)], &opts);
assert_eq!(pages[0].created.as_deref(), Some("2025-05-06"));
assert_eq!(pages[0].updated.as_deref(), Some("2025-07-08"));
}
}

/// An entry record — what a template's `entries` lists — is dated by the
/// same chain its page is, so an entry dated only by the stamped field
/// still carries that date there.
#[test]
fn an_entry_record_is_dated_by_its_stamped_field() {
let opts = SiteOptions {
date_fields: DateFields {
created: Some("made".into()),
updated: None,
},
..SiteOptions::default()
};
let index = "---\ntitle: Home\n---\n:::each{of=entries as=entry}\n- :val[entry.title] :val[entry.date]\n:::\n";
let note = "---\ntitle: Note\nmade: 2026-01-02\n---\nBody.\n";
let out = render_site(
&[src("index.md", index, true), src("note.md", note, false)],
&opts,
);
let home = out
.pages
.iter()
.find(|p| p.dest_filename == "index.html")
.expect("the front page");
assert!(home.html.contains("Note 2026-01-02"), "{}", home.html);
}

// ── generated index ─────────────────────────────────────────────────────

fn entry(title: &str, date: &str) -> String {
Expand Down
51 changes: 49 additions & 2 deletions plates-render/src/types.rs
Original file line number Diff line number Diff line change
Expand Up @@ -187,9 +187,11 @@ pub struct PublishedPage {
pub description: Option<String>,
/// Page author (from frontmatter `author`)
pub author: Option<String>,
/// Creation date (from frontmatter `created`)
/// Creation date: the field the workspace stamps on creation, else
/// frontmatter `created` ([`DateFields`])
pub created: Option<String>,
/// Last update date (from frontmatter `updated`)
/// Last update date: the field the workspace stamps on an edit, else
/// frontmatter `updated` ([`DateFields`])
pub updated: Option<String>,
/// The date the document is *about*, as opposed to when its file was made
/// (from frontmatter `date_of_document`). First link in the date chain a
Expand Down Expand Up @@ -370,6 +372,51 @@ impl PublishedPage {
}
}

/// Which frontmatter fields hold a page's creation and last-edit dates.
///
/// A workspace names them itself — prov's `fields.<name>.stamp: create` and
/// `stamp: edit`, answered by `WorkspaceConfig::created_field` and
/// `updated_field` — and an archive stamping `modified` keeps its edit date
/// there, not under `updated`. This crate reads no configuration, so the layer
/// holding the workspace passes the answer in, the way it passes the
/// [`outline`](crate::site::SiteOptions::outline).
///
/// `None` is a workspace that stamps nothing then. Either way the literal
/// `created` and `updated` stay the fallback, page by page: a page written
/// before the workspace declared a stamp, or mounted from a peer that stamps
/// the literal names, keeps the dates it was published with.
#[derive(Debug, Clone, PartialEq, Eq, Default)]
pub struct DateFields {
/// The field stamped when a document is made.
pub created: Option<String>,
/// The field stamped when a document's content changes.
pub updated: Option<String>,
}

impl DateFields {
/// When `frontmatter`'s document was made: the stamped field, else
/// `created`.
pub fn created_in<'a>(&self, frontmatter: &'a prov::Mapping) -> Option<&'a str> {
Self::read(frontmatter, self.created.as_deref(), "created")
}

/// When `frontmatter`'s document last changed: the stamped field, else
/// `updated`.
pub fn updated_in<'a>(&self, frontmatter: &'a prov::Mapping) -> Option<&'a str> {
Self::read(frontmatter, self.updated.as_deref(), "updated")
}

fn read<'a>(
frontmatter: &'a prov::Mapping,
stamped: Option<&str>,
literal: &str,
) -> Option<&'a str> {
stamped
.and_then(|field| crate::frontmatter::get_string(frontmatter, field))
.or_else(|| crate::frontmatter::get_string(frontmatter, literal))
}
}

/// One node of a site's **spanning outline**: the archive's own containment
/// hierarchy, materialized by whoever holds the workspace.
///
Expand Down
Loading