# Welcome

> **Version:** 1.4.x **License:** Commercial / GPL‑compatible **Requires:** WordPress 6.4+, PHP 8.0+

PorterWP is a *developer‑first* toolkit that turns any **WordPress block theme** into a fully‑fledged, schema‑driven application. It ships as a plugin and expects a companion **`/porter`** folder inside your child theme where all configuration lives.

* Zero‑boilerplate **Custom Post Types** & **Taxonomies** via JSON.
* **ACF Blocks**, **block styles**, **patterns** & **variations** without touching PHP.
* Automatic include of theme PHP helpers from **`/porter/inc`**.
* *Production‑only* object‑cache layer with a one‑click purge.
* A premium **Filters** block that adds faceted search to any Query Loop.

***

## Quick Start 🚀

1. **Buy & download PorterWP Premium** Get your license at <https://porterwp.com/> and grab the ZIP plus your Freemius key.
2. **Install the plugin** Upload via *Plugins › Add New* or run:

   ```bash
   wp plugin install ~/Downloads/porterwp-premium.zip --activate
   ```
3. **Activate your licence** A Freemius modal will prompt for the key; you can revisit it under *Plugins › PorterWP Premium › Manage License*.
4. **Install the latest skeleton theme** Download or clone the starter from <https://github.com/whoisandywhite/porterwp-public/tree/main/resources/theme-skeleton> **(it is a complete WordPress theme)** and drop the whole folder into `wp-content/themes/`.
   1. Rename the folder if you like (`my‑theme`, `client‑site`, …).
   2. Open **`style.css`** inside the theme and change the theme header (`Theme Name`, `Author URI`, etc.).
   3. Open **`package.json`** and update the `name` + `description` fields so NPM uses your project slug.
5. **Compile assets (optional, recommended)**

   ```bash
   npm install        # once
   npx gulp build     # production build
   npx gulp watch     # dev: SCSS → CSS, JS minify, etc.
   ```

### Recommended `wp-config.php` additions

```php
// Tell PorterWP when to cache
// Options: production, staging, development, local
if ( ! defined( 'WP_ENVIRONMENT_TYPE' ) ) {
    define( 'WP_ENVIRONMENT_TYPE', 'development' );
}
```

PorterWP only caches in `production`. Keeping other environments set to `development` or `local` means you never have to hit **Clear Cache** while theming.

> **Next →** [Directory Structure](https://whoisandywhite.gitbook.io/porterwp/documentation/directory-structure)

## Configuration Files

The JSON files inside `porter/config/` let you shape every aspect of the theme. See the [Configuration Files Index](https://whoisandywhite.gitbook.io/porterwp/documentation/configuration-files) for a full breakdown.

## Build Pipeline

PorterWP ships with a **Gulp 5 / ES modules** tool‑chain for compiling Sass, minifying JS, and generating block assets.

| File             | Purpose                                                                                                                         |
| ---------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| **gulpfile.js**  | Task definitions: compile SCSS, autoprefix, uglify CSS, minify JS, auto‑generate block style stubs, and create post‑type icons. |
| **package.json** | NPM dependencies and scripts for the build pipeline (no theme‑specific names—this is a prototype starter).                      |

```bash
# install dependencies
npm install

# one‑off production build
npm run gulp build   # or: npx gulp build

# watch files during development
npm run gulp watch   # or: npx gulp watch
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://whoisandywhite.gitbook.io/porterwp/readme.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.