diff --git a/docs/tasks/follow-prov-vocabulary-shape-and-term-holds.md b/docs/tasks/follow-prov-vocabulary-shape-and-term-holds.md index b7da09b..7a08118 100644 --- a/docs/tasks/follow-prov-vocabulary-shape-and-term-holds.md +++ b/docs/tasks/follow-prov-vocabulary-shape-and-term-holds.md @@ -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 diff --git a/plates-cli/src/build.rs b/plates-cli/src/build.rs index d1f1895..acf205d 100644 --- a/plates-cli/src/build.rs +++ b/plates-cli/src/build.rs @@ -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; @@ -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(); @@ -348,6 +352,7 @@ pub fn build_sites( audience: &spec.audience, root: &session.root_dir, base_url, + date_fields: &date_fields, }, collected, identifiers, @@ -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. @@ -460,6 +468,7 @@ fn assemble( audience, root, base_url, + date_fields, } = site; let sources: Vec = collected .sources @@ -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, @@ -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 { + /// A build of the archive `files`: the declaration's warnings, and the + /// sites. + fn build(files: &[(&str, &str)]) -> (Vec, Vec) { let dir = tempfile::tempdir().unwrap(); for (path, text) in files { let path = dir.path().join(path); @@ -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 { + let (mut warnings, built) = build(files); for site in built { warnings.extend(site.warnings); } @@ -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}"); + } } diff --git a/plates-render/src/lib.rs b/plates-render/src/lib.rs index 8660542..bb1dbb9 100644 --- a/plates-render/src/lib.rs +++ b/plates-render/src/lib.rs @@ -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, }; diff --git a/plates-render/src/site.rs b/plates-render/src/site.rs index b844787..54e4950 100644 --- a/plates-render/src/site.rs +++ b/plates-render/src/site.rs @@ -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 @@ -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, + /// 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 @@ -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(), @@ -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( @@ -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 @@ -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 { diff --git a/plates-render/src/types.rs b/plates-render/src/types.rs index cdeec98..03c31fc 100644 --- a/plates-render/src/types.rs +++ b/plates-render/src/types.rs @@ -187,9 +187,11 @@ pub struct PublishedPage { pub description: Option, /// Page author (from frontmatter `author`) pub author: Option, - /// Creation date (from frontmatter `created`) + /// Creation date: the field the workspace stamps on creation, else + /// frontmatter `created` ([`DateFields`]) pub created: Option, - /// Last update date (from frontmatter `updated`) + /// Last update date: the field the workspace stamps on an edit, else + /// frontmatter `updated` ([`DateFields`]) pub updated: Option, /// 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 @@ -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..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, + /// The field stamped when a document's content changes. + pub updated: Option, +} + +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. ///