wp-materialize/README.md

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 validation:

wp-materialize validate

Apply (validate, 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.
3. pandoc must be installed and available in PATH when using renderer: "pandoc".

Install dependencies:

python -m pip install -r requirements.txt