wp-materialize/configurations.md

Configuration Reference

This document defines every JSON field for both the global config and per-directory manifests.

Global Config (~/.config/wp-materialize/config.json)

Top-level fields:

1. wordpress_root (string, required) Path to the WordPress root directory where the wp CLI is executed.
2. repo_storage_dir (string, required) Directory where git repositories are cloned or updated.
3. git_repositories (array, optional) List of git repositories to manage. Default is an empty list.
4. directories (array, optional) List of non-git directories to manage. Default is an empty list.

git_repositories entries:

1. name (string, required) Stable identifier for the repository. Used to build post identity.
2. url (string, required) Git clone URL.
3. branch (string, optional, default main) Branch to checkout and pull.
4. root_subdir (string, optional) Subdirectory within the repo that contains .wp-materialize.json and content. If omitted or null, the repo root is used.

directories entries:

1. name (string, required) Stable identifier for the directory. Used to build post identity.
2. path (string, required) Filesystem path to the directory.
3. root_subdir (string, optional) Subdirectory within the directory that contains .wp-materialize.json and content. If omitted or null, the directory root is used.

Per-Directory Manifest (.wp-materialize.json)

Each managed directory must contain a manifest. Manifests define a scope boundary. No implicit traversal is allowed; subdirectories must be listed explicitly.

Top-level fields:

1. categories (object, optional) Inherited category paths for this directory and its children.
2. tags (object, optional) Inherited tags for this directory and its children.
3. author (object, optional) Inherited author for this directory and its children. Must resolve to a single author.
4. subdirectories (object, optional) Explicit list of subdirectories to traverse.
5. files (object, optional) Mapping of Markdown file names to file-level configuration.

categories, tags, author, and subdirectories objects:

1. content (array of strings, optional) List of values for the given field. For categories, each string is a hierarchical path such as Systems/Infrastructure. For subdirectories, each string is a directory name under the current directory. For author, exactly one string must remain after inheritance is applied.
2. inherit (boolean, optional, default true) If true, append to the parent effective list. If false, replace the parent list entirely.

Note: Root directory manifests do not need to specify inherit for these top-level fields (the default is true). File-level overrides inside files still support inheritance via their own inherit fields.

files entries:

Each key is a Markdown file name (relative to the manifest directory). Each value is an object with the following fields:

1. title (string, required if use_heading_as_title is not set) Explicit WordPress post title.
2. use_heading_as_title (object, optional) Extracts a heading from the Markdown as the title and removes that heading from the body while promoting remaining headings by one level.
3. created_on (string, optional) Manual override for the post creation time in YYYY-MM-DD hh:mm format.
4. last_modified (string, optional) Manual override for the post modified time in YYYY-MM-DD hh:mm format.
5. categories (object, optional) Overrides categories for this file. Uses the same content and inherit fields as the top-level categories object.
6. tags (object, optional) Overrides tags for this file. Uses the same content and inherit fields as the top-level tags object.

use_heading_as_title object:

1. level (integer, required) Heading level to extract, from 1 to 6.
2. strict (boolean, optional, default true) If true, exactly one matching heading must exist.

If created_on or last_modified is not provided, the system infers the value. For git_repositories sources it uses git commit timestamps; for directories sources it uses filesystem timestamps. The system does not auto-detect git for entries declared under directories, even if the path is inside a git repo.

Post Identity

Each post is identified with:

_wp_materialize_source = <source_name>:<relative_path>

source_name is the name from the global config entry, and relative_path is relative to the repo or directory root used for identity resolution.

Tag and Category Creation

Missing categories and tags are created automatically during apply, after a successful dry-run evaluation and before any post updates.