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. subdirectories (object, optional) Explicit list of subdirectories to traverse.
4. files (object, optional) Mapping of Markdown file names to file-level configuration.

categories, tags, 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.
2. inherit (boolean, optional, default true) If true, append to the parent effective list. If false, replace the parent list entirely.

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. categories (object, optional) Overrides categories for this file. Uses the same content and inherit fields as the top-level categories object.
4. 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.

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.