wp-materialize

wp-materialize is an automation compiler that materializes specified Markdown files into WordPress posts. Git/filesystem state is the single source of truth; WordPress is a derived view.

Install

python -m pip install -e .

Source Layout

The wp_materialize package lives directly under src/ (single-package mapping).

Documentation

• configurations.md
• examples.md

Configuration

Global config is required and must be a JSON object with these fields:

1. wordpress_root (string, required): Path where wp CLI is executed.
2. repo_storage_dir (string, required): Directory where git repos are cloned.
3. git_repositories (array, optional): Git repos to manage.
4. directories (array, optional): Non-git directories to manage.

git_repositories entries:

1. name (string, required): Stable identifier for the repo.
2. url (string, required): Git clone URL.
3. branch (string, optional, default main): Branch to checkout.
4. root_subdir (string, optional): Subdirectory that contains manifests/content.

directories entries:

1. name (string, required): Stable identifier for the directory.
2. path (string, required): Filesystem path.
3. root_subdir (string, optional): Subdirectory that contains manifests/content.

Global config (required):

~/.config/wp-materialize/config.json

Example:

{
  "wordpress_root": "/var/www/wordpress",
  "repo_storage_dir": "/home/user/wp-materialize-repos",
  "git_repositories": [
    {
      "name": "content-repo",
      "url": "https://github.com/example/content-repo.git",
      "branch": "main",
      "root_subdir": "posts"
    }
  ],
  "directories": [
    {
      "name": "local-notes",
      "path": "/home/user/notes",
      "root_subdir": "wordpress"
    }
  ]
}

State is stored separately (created on first successful apply):

~/.config/wp-materialize/state.json

Usage

Dry-run evaluation:

wp-materialize evaluate

Apply (evaluate, then materialize):

wp-materialize apply

Skip git sync:

wp-materialize apply --no-sync

Local export (writes per-post directories with HTML, metadata, and WP command):

wp-materialize local /path/to/output

Notes:

1. The local export assumes every post is new and generates create commands.
2. The local export does not call WordPress or resolve category IDs.

Create placeholder config or manifest:

wp-materialize new --config
wp-materialize new --config /path/to/config.json
wp-materialize new --manifest /path/to/content

Add files or subdirectories to a manifest (no evaluation):

wp-materialize add-file /path/to/content/post.md
wp-materialize add-file /path/to/content/post.md /path/to/content
wp-materialize add-file /path/to/content/post.md --current

wp-materialize add-subdir /path/to/content/notes
wp-materialize add-subdir /path/to/content/notes /path/to/content
wp-materialize add-subdir /path/to/content/notes --current

Manifests

Each managed directory must contain a .wp-materialize.json manifest. See configurations.md for the manifest guide.

Python Prerequisites

1. Python 3.10+
2. Packages:
   • Markdown>=3.6
   • py_gfm (only required when using renderer: "py-gfm")

System Prerequisites

1. wp CLI must be installed and available in PATH for apply.
2. local does not require wp.

Install dependencies:

python -m pip install -r requirements.txt