From 109363672896618dfdfa11c9e5ef538cf5265463 Mon Sep 17 00:00:00 2001 From: Cas Rusnov Date: Sun, 14 Apr 2019 19:52:00 -0700 Subject: [PATCH] Document meatdata. --- READMES/METADATA.md | 41 +++++++++++++++++++++++++++++++---------- TODO.md | 1 - 2 files changed, 31 insertions(+), 11 deletions(-) diff --git a/READMES/METADATA.md b/READMES/METADATA.md index 3278a4a..5f8c97c 100755 --- a/READMES/METADATA.md +++ b/READMES/METADATA.md @@ -2,8 +2,7 @@ ## FORMAT ## -Metadata shall be stored in json files. It shall take the form of a top-level dictionary, with each key being an item of metadata. Heirarchical metadata -and types are preserved and explitily allowed. +Metadata is stored as a JSON file which allows C-likecomments. Metadata is loaded from the top down, so each parent from the root can impart metadata on children. Children can explitily nullify parent metadata by assigning it to undefined. @@ -16,29 +15,51 @@ On-disk meatdata is stored as a file along side the non-metadata file with the e All files define the following keys by default: -filename +file_name : The local path of the file -path +file_path : The full path to the file from the root -type +dir +: The directory to the path from root for this file +os-path +: The native OS path to this file +guessed-type : The guessed mime-type of the file stat : A tree of stat() values in a dictionary, without the ST_ prefix, and with lowercase keys. +templates +: The path to the template files. +uuid +: A UUID for this file based on its path and a specified `uuid-oid-root` metadata +build-time +: The time stamp for the build time -Most files will want to define these keys: +Files can also explicitly override these which are set to empty defaults: +mime-type +: Either the specified mime-type or guessed type if undefined. template : The full path to the template file -template-fs +dir-template : The full path to the filesystem template title : A title for this object derived from the template, metadata or other sources. +summary +: A summary of the file contents. description -: A description of this file. +: A description of file contents. -## METAMETADATA ## +Trees have some metadata that projects should probably override (generally in their top-level .meta): + +uuid-oid-root +: A string added to the beginning of the path that identifies this site, used for deriving OID UUIDs. +author +: The full name of the author of this site (should also be overridden per-file if necessary). +author_email +: The email of the author of this site (see above) +site_root +: The full URL for the root of this web site used for links and whatnot, with ending slash. -Some keys support metadata replacement, such as title, description, template and type. The metadata becomes a micro template which allows some template functions to occur at load time based on existing / default metadata. ## CACHING STRATEGY ## diff --git a/TODO.md b/TODO.md index ad2e5f8..efe697a 100644 --- a/TODO.md +++ b/TODO.md @@ -2,7 +2,6 @@ * Pygments pretty printing of source code et al. including exposing that to the template API. * Smart CSS things (fill in the processors) -* Document all of the internally generated and "expected" metadata keys. # Maybe #