ZAP 002 - Metadata¶

12-17 min read · 2,587 words · View in Zensical Spark

With this ZAP we aim to specify the metadata handling in Zensical. Like the Meta plugin in Material for MkDocs, Zensical will support metadata defined per section that apply to all the pages in the section. Beyond feature party with Material for MkDocs, however, we identify opportunities for metadata handling that open up new use cases. We consider what additional functionality and degrees of freedom these use cases require and how we can, at the same time, make using metadata easy as well as reduce the potential for human error.

Problem statement¶

Assigning metadata to the headers of a non-trivial number of pages can be tedious and error prone. So, for convenience and to avoid mistakes, it should be possible to assign metadata in bulk for many files, to provide sensible defaults even if they can be overridden on a page-by-page basis.

What is more, there are use cases where the metadata for a section is controlled by one team while the content can be edited by another. This means it must be possible to completely separate the metadata from the content and ensure that section metadata files take precedence over page metadata. It should also be possible to define metadata not just for the whole section but for individual files within it.

Purpose¶

The purpose of this ZAP is to define the functionality available for metadata handling in Zensical, based on the functionality the Meta plugin in Material for MkDocs provides but extending to new use cases that are currently not supported. The ZAP process helps us ensure that we start developing this functionality from solid understanding of these use cases.

We do not aim to specify the mechanisms for using metadata but how they can be defined in a project. We also do not cover schemas or validation at this point. These will be the subject of separate ZAPs.