151 lines
3.5 KiB
Markdown
151 lines
3.5 KiB
Markdown
# 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
|
|
|
|
```bash
|
|
python -m pip install -e .
|
|
```
|
|
|
|
## Source Layout
|
|
|
|
The `wp_materialize` package lives directly under `src/` (single-package mapping).
|
|
|
|
## Documentation
|
|
|
|
- [configurations.md](configurations.md)
|
|
- [examples.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:
|
|
|
|
```json
|
|
{
|
|
"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:
|
|
|
|
```bash
|
|
wp-materialize validate
|
|
```
|
|
|
|
Apply (validate, then materialize):
|
|
|
|
```bash
|
|
wp-materialize apply
|
|
```
|
|
|
|
Skip git sync:
|
|
|
|
```bash
|
|
wp-materialize apply --no-sync
|
|
```
|
|
|
|
Local export (writes per-post directories with HTML, metadata, and WP command):
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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):
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
python -m pip install -r requirements.txt
|
|
```
|