keith/Portfolio-2026
1
0
Fork 0
Code Issues 1 Pull Requests Actions Packages Projects Releases Wiki Activity

🔵 other: Rename project and publish

Browse Source
This commit is contained in:
Keith Solomon
2026-07-29 14:25:19 -05:00
parent 5512918b0f
commit 7dbb991fb9
70 changed files with 558 additions and 5386 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/getting-started.md
+101 -116
View File
@@ -1,6 +1,6 @@
# Getting Started with VDI-Starter-v5
# Getting Started with SoloFrame Evo
This guide walks you through setting up a local development environment for the VDI-Starter-v5 WordPress theme from scratch. It covers prerequisites, installation, configuration, and common development workflows.
This guide walks you through setting up a local development environment for the SoloFrame Evo WordPress theme from scratch. It covers prerequisites, installation, configuration, and common development workflows.
---
@@ -15,7 +15,7 @@ This guide walks you through setting up a local development environment for the
7. [Activating the Theme](#activating-the-theme)
8. [Development Workflow](#development-workflow)
9. [Project Architecture](#project-architecture)
10. [Creating Custom ACF Blocks](#creating-custom-acf-blocks)
10. [Creating Custom SCF/ACF Blocks](#creating-custom-scfacf-blocks)
11. [Testing](#testing)
12. [Code Quality](#code-quality)
13. [Troubleshooting](#troubleshooting)
@@ -24,7 +24,7 @@ This guide walks you through setting up a local development environment for the
## Overview
VDI-Starter-v5 is a minimal WordPress theme designed as a starting point for custom theme development. It uses a modern stack:
SoloFrame Evo is a minimal WordPress theme designed as a starting point for custom theme development. It uses a modern stack:
- **Tailwind CSS v4** for utility-first styling, compiled via the Tailwind CLI
- **ACF Pro** for custom field management and block registration
@@ -41,14 +41,14 @@ The theme intentionally avoids heavyweight frameworks. Every PHP file in `lib/`
Before you begin, make sure the following tools are installed on your machine.
| Tool | Minimum Version | Why It Is Needed |
|-------------|-----------------|------------------------------------------------------------------------------------------------------|
| Node.js | 22+ | Tailwind CSS v4 CLI requires a modern Node runtime. Older versions will fail during `npm run build`. |
| npm | Latest (bundled with Node) | Package management for JavaScript dependencies and build scripts. |
| PHP | 8.0+ | WordPress core requirement and theme compatibility. |
| Composer | 2.x | Installs PHP_CodeSniffer with WordPress coding standards for linting. |
| WordPress | 6.5+ | The theme uses `wp_enqueue_script_module()`, which was introduced in WordPress 6.5. |
| ACF Pro | Latest | All custom blocks depend on ACF Pro. Blocks will not register without it. |
| Tool | Minimum Version | Why It Is Needed |
| ------------- | -------------------------- | ---------------------------------------------------------------------------------------------------- |
| Node.js | 22+ | Tailwind CSS v4 CLI requires a modern Node runtime. Older versions will fail during `npm run build`. |
| npm | Latest (bundled with Node) | Package management for JavaScript dependencies and build scripts. |
| PHP | 8.0+ | WordPress core requirement and theme compatibility. |
| Composer | 2.x | Installs PHP_CodeSniffer with WordPress coding standards for linting. |
| WordPress | 6.5+ | The theme uses `wp_enqueue_script_module()`, which was introduced in WordPress 6.5. |
| ACF Pro | Latest | All custom blocks depend on ACF Pro. Blocks will not register without it. |
### Checking Your Versions
@@ -96,36 +96,36 @@ Docker gives you the most control and works on any operating system, but it requ
1. Install [Docker Desktop](https://www.docker.com/products/docker-desktop/).
2. Use the official `wordpress` Docker image with a custom theme mount. A minimal `docker-compose.yml` might look like:
```yaml
version: '3.8'
services:
db:
image: mysql:8.0
environment:
MYSQL_ROOT_PASSWORD: wordpress
MYSQL_DATABASE: wordpress
MYSQL_USER: wordpress
MYSQL_PASSWORD: wordpress
volumes:
- db_data:/var/lib/mysql
```yaml
version: '3.8'
services:
db:
image: mysql:8.0
environment:
MYSQL_ROOT_PASSWORD: wordpress
MYSQL_DATABASE: wordpress
MYSQL_USER: wordpress
MYSQL_PASSWORD: wordpress
volumes:
- db_data:/var/lib/mysql
wordpress:
image: wordpress:latest
ports:
- "8080:80"
environment:
WORDPRESS_DB_HOST: db:3306
WORDPRESS_DB_USER: wordpress
WORDPRESS_DB_PASSWORD: wordpress
WORDPRESS_DB_NAME: wordpress
volumes:
- ./themes/vdi-starter-v5:/var/www/html/wp-content/themes/vdi-starter-v5
depends_on:
- db
wordpress:
image: wordpress:latest
ports:
- "8080:80"
environment:
WORDPRESS_DB_HOST: db:3306
WORDPRESS_DB_USER: wordpress
WORDPRESS_DB_PASSWORD: wordpress
WORDPRESS_DB_NAME: wordpress
volumes:
- ./themes/SoloFrame-Evo:/var/www/html/wp-content/themes/SoloFrame-Evo
depends_on:
- db
volumes:
db_data:
```
volumes:
db_data:
```
3. Run `docker compose up -d` and visit `http://localhost:8080` to complete the WordPress installation wizard.
@@ -136,29 +136,17 @@ volumes:
### Step 1: Clone the Repository
```bash
git clone https://github.com/Vincent-Design-Inc/VDI-Starter-v5.git
cd VDI-Starter-v5
git clone https://github.com/ksolomon/SoloFrame-Evo.git
cd SoloFrame-Evo
```
If you are contributing to an existing project, clone it into your local WordPress `wp-content/themes/` directory so WordPress can detect it:
```bash
cd /path/to/your/local-wp-site/wp-content/themes/
git clone https://github.com/Vincent-Design-Inc/VDI-Starter-v5.git
git clone https://github.com/ksolomon/SoloFrame-Evo.git
```
If you cloned it elsewhere, you can symlink it into the themes directory:
```bash
# macOS/Linux
ln -s /path/to/VDI-Starter-v5 /path/to/wp-content/themes/vdi-starter-v5
# Windows (run in an elevated Command Prompt)
mklink /D "C:\path\to\wp-content\themes\vdi-starter-v5" "C:\path\to\VDI-Starter-v5"
```
Using a symlink means your local edits are immediately reflected in WordPress without copying files.
### Step 2: Install PHP Dependencies
```bash
@@ -173,9 +161,9 @@ This installs PHP_CodeSniffer and the WordPress Coding Standards (WPCS) ruleset.
npm install
```
This installs the frontend build toolchain: Tailwind CSS v4 and its CLI, BrowserSync, Playwright, dotenv, and other utilities. Tailwind v4 uses the `@tailwindcss/cli` package directly (no `tailwind.config.js` file is needed -- configuration lives in `styles/theme.css`).
This installs the frontend build toolchain: Tailwind CSS v4 and its CLI, BrowserSync, Playwright, dotenv, and other utilities. Tailwind v4 uses the `@tailwindcss/cli` package directly. No `tailwind.config.js` file is needed -- configuration lives in `styles/theme.css`.
### Step 4: Configure Environment Variables
## Environment Configuration
Copy the example environment file and edit it:
@@ -185,16 +173,16 @@ cp .env.example .env
Open `.env` and set the two variables:
| Variable | Description | Example Value |
|-------------------|-----------------------------------------------------------------------------------------------|------------------------------|
| `LOCALHOST_URL` | The full URL of your local WordPress site, including the scheme (`http` or `https`) | `https://vdi-starter.local` |
| `BROWSERSYNC_PORT`| The port BrowserSync should listen on. Defaults to `5000` if not set. | `5000` |
| Variable | Description | Example Value |
| ------------------- | ----------------------------------------------------------------------------------- | ------------------------------ |
| `LOCALHOST_URL` | The full URL of your local WordPress site, including the scheme (`http` or `https`) | `https://soloframe-evo.local` |
| `BROWSERSYNC_PORT` | The port BrowserSync should listen on. Defaults to `5000` if not set. | `5000` |
The `LOCALHOST_URL` must match exactly what your local WordPress environment responds to. If you are using Local by Flywheel with SSL enabled, include `https://`. If you are using Docker on port 8080, use `http://localhost:8080`.
BrowserSync proxies this URL and injects a live-reload script, so any change you make to PHP templates, CSS, or JS files will automatically refresh the browser.
### Step 5: Build Assets for the First Time
## Building Assets
Before activating the theme, compile the Tailwind CSS so the theme has its stylesheet:
@@ -204,7 +192,7 @@ npm run build
This runs:
```
```bash
npx @tailwindcss/cli -i ./styles/theme.css -o ./static/dist/theme.css --optimize
```
@@ -227,15 +215,11 @@ Log into your local WordPress admin dashboard and navigate to **Appearance > The
> - **Creates 4 default pages:** Home, News, Page Not Found (Error 404), and Contact Us.
> - **Sets WordPress to use a static front page:** Home becomes the front page, News becomes the posts page. This overrides any existing "Reading Settings".
> - **Deletes the default "Hello World" post** (ID 1) and the **sample page** (ID 2). These are trashed permanently (`wp_delete_post` with `$force_delete = true`).
> - **Installs 7 plugins** from external URLs and selectively activates them:
> 1. **ACF Pro** -- installed and activated (from `https://docs.vincentdevelopment.ca/files/advanced-custom-fields-pro.zip`)
> 2. **Gravity Forms** -- installed and activated (from `https://docs.vincentdevelopment.ca/files/gravity-forms.zip`)
> 3. **UpdraftPlus** -- installed, NOT activated (from WordPress.org)
> 4. **Simple History** -- installed and activated (from WordPress.org)
> 5. **The SEO Framework** -- installed and activated (from WordPress.org)
> 6. **Better Search Replace** -- installed and activated (from WordPress.org)
> 7. **Google Site Kit** -- installed, NOT activated (from WordPress.org)
> - **Creates an "Owner" role** (administrator capabilities minus plugin/theme management).
> - **Installs 4 plugins** from external URLs and selectively activates them:
> 1. **Secure Custom Fields** -- installed and activated (from WordPress.org)
> 2. **Simple History** -- installed and activated (from WordPress.org)
> 3. **The SEO Framework** -- installed and activated (from WordPress.org)
> 4. **Better Search Replace** -- installed and activated (from WordPress.org)
> - **Writes an installation log** to `wp-content/mu-plugin-install.log`.
>
> **Do NOT activate this theme on an existing production site without reviewing `lib/activation.php` first.** The activation routine is designed for fresh installs and will modify pages, settings, and plugin state without confirmation.
@@ -271,7 +255,7 @@ This runs `bin/.watch.js`, which starts BrowserSync and watches for file changes
When you edit a `.js` file in `static/js/`, BrowserSync injects the updated script without a full page reload (hot injection).
The dev server is accessible at the `LOCALHOST_URL` you configured, proxied through the `BROWSERSYNC_PORT`. For example, if your `.env` has `LOCALHOST_URL=https://vdi-starter.local` and `BROWSERSYNC_PORT=5000`, your dev URL is `https://vdi-starter.local` with BrowserSync overlay on port 5000.
The dev server is accessible at the `LOCALHOST_URL` you configured, proxied through the `BROWSERSYNC_PORT`. For example, if your `.env` has `LOCALHOST_URL=http://soloframe-evo.local` and `BROWSERSYNC_PORT=5000`, your dev URL is `http://soloframe-evo.local` with BrowserSync overlay on port 5000.
### Building for Production
@@ -291,27 +275,27 @@ This compiles Tailwind CSS with `--optimize` enabled, which minifies the output
Understanding the directory layout helps you know where to find things and where to put new files.
```
VDI-Starter-v5/
├── acf/ # ACF Pro field group JSON (auto-synced)
```plain
SoloFrame-Evo/
├── acf/ # SCF/ACF Pro field group JSON (auto-synced)
│ └── group_*.json # One file per field group
├── bin/
│ ├── .watch.js # BrowserSync dev server script
│ └── .utils.js # Shared build utilities (Tailwind compilation)
│ └── .utils.js # Shared build utilities (Tailwind compilation)
├── content/
│ └── basic-wp-test-content.xml # Sample content for testing
├── docs/ # Documentation (this guide lives here)
├── lib/ # PHP utility classes (auto-loaded)
│ ├── activation.php # Theme activation routine (pages, plugins, settings)
│ ├── class-acf.php # ACF JSON load/save path configuration
│ ├── class-acf.php # SCF/ACF JSON load/save path configuration
│ ├── class-breadcrumbs.php # Breadcrumb navigation helper
│ ├── class-enqueue.php # Frontend/backend/editor asset enqueueing
│ ├── class-menuitems.php # Custom menu item handling
│ ├── class-menuitems.php # Custom menu item handling
│ ├── class-resources.php # Resource management
│ ├── extras.php # Miscellaneous helper functions
│ ├── extras.php # Miscellaneous helper functions
│ ├── helpers.php # Template helper functions
│ ├── hooks.php # Theme hooks (menus, sidebars, cleanup, SVG uploads)
│ ├── search-features.php # Enhanced search functionality
│ ├── search-features.php # Enhanced search functionality
│ └── show-template.php # Template debugging (shows which template is loaded)
├── static/
│ ├── dist/
@@ -350,7 +334,7 @@ VDI-Starter-v5/
│ ├── page-children/
│ └── section/
├── tests/
│ └── site-a11y.spec.js # Playwright accessibility tests
│ └── site-a11y.spec.js # Playwright accessibility tests
├── .env.example # Environment variable template
├── composer.json # PHP dependencies (PHPCS + WPCS)
├── functions.php # Theme bootstrap (loads all lib/*.php files, registers ACF blocks)
@@ -373,7 +357,7 @@ foreach ( glob( __DIR__ . '/lib/*.php' ) as $filename ) {
This means adding a new file to `lib/` automatically includes it. No manual `require` statements are needed. However, be aware that files are loaded in alphabetical order. If one file depends on something defined in another, you may need to rename files with numeric prefixes to control load order.
### How ACF Blocks Are Registered
### How SCF/ACF Blocks Are Registered
The `regACFBlocks()` function in `functions.php` scans the `views/blocks/` directory at runtime:
@@ -398,21 +382,21 @@ Each subdirectory that contains a `block.json` file is registered as a Gutenberg
The Tailwind entry point is `styles/theme.css`. It imports sub-stylesheets using CSS `@import` directives:
```css
@import "tailwindcss"; /* Tailwind v4 framework */
@import "./base/index.css"; /* Base styles */
@import "./navigation/index.css";/* Navigation styles */
@import "./fonts/lineicons.css"; /* Icon font */
@import "./base/break-out.css"; /* Break-out utility */
@import "./components/index.css";/* Component styles */
@import "./blocks/index.css"; /* Block-specific styles */
@plugin "@tailwindcss/typography"; /* Typography plugin */
@import "tailwindcss"; /* Tailwind v4 framework */
@import "./base/index.css"; /* Base styles */
@import "./navigation/index.css"; /* Navigation styles */
@import "./fonts/lineicons.css"; /* Icon font */
@import "./base/break-out.css"; /* Break-out utility */
@import "./components/index.css"; /* Component styles */
@import "./blocks/index.css"; /* Block-specific styles */
@plugin "@tailwindcss/typography"; /* Tailwind Typography plugin */
```
When you create a new block or component, add its styles to the appropriate subdirectory and make sure it is imported through the corresponding `index.css` file.
---
## Creating Custom ACF Blocks
## Creating Custom SCF/ACF Blocks
To create a new ACF block, use the `boilerplate` directory as a starting point:
@@ -424,7 +408,7 @@ To create a new ACF block, use the `boilerplate` directory as a starting point:
2. Edit `views/blocks/my-block/block.json`:
- Change `"name"` to `"acf/my-block"`
- Change `"title"` to a human-readable name like `"My Block (VDI)"`
- Change `"title"` to a human-readable name like `"My Block"`
- Update `"description"`, `"icon"`, and `"keywords"` as appropriate
- If this block should only be nested inside another block, add a `"parent"` array (see `button/block.json` for an example)
@@ -432,7 +416,7 @@ To create a new ACF block, use the `boilerplate` directory as a starting point:
4. If the block needs ACF field groups, create them in the WordPress admin under **Custom Fields > Field Groups** and associate them with the block. ACF will save the field group JSON to the `acf/` directory, which you should commit to version control.
5. Add block-specific styles in `styles/blocks/` and import them through `styles/blocks/index.css`.
5. Add block-specific styles in `my-block.css`.
The block will be automatically discovered and registered on the next page load because `regACFBlocks()` scans the directory on every `init` hook.
@@ -502,12 +486,13 @@ The compilation pipeline is: `styles/theme.css` (entry point with `@import` dire
**Symptom:** The block inserter in the Gutenberg editor does not show custom blocks like "Homepage Hero" or "Section".
**Solution:** ACF Pro must be installed and activated. Blocks are registered by scanning `views/blocks/*/block.json` on the `init` hook. Without ACF Pro, `register_block_type()` still runs, but ACF blocks require the ACF plugin to provide field data and rendering.
**Solution:** SCF (installed by default on theme activation) or ACF Pro must be installed and activated. Blocks are registered by scanning `views/blocks/*/block.json` on the `init` hook. Without SCF/ACF Pro, `register_block_type()` still runs, but blocks require the SCF/ACF plugin to provide field data and rendering.
Also check that:
- The block directory contains a valid `block.json` file.
- The block directory is not named `boilerplate` (this is excluded by design).
- ACF Pro is activated (not just installed).
- SCF/ACF Pro is activated (not just installed).
### Menus Are Not Rendering
@@ -566,24 +551,24 @@ Check `wp-content/mu-plugin-install.log` for detailed error messages. Each plugi
## Quick Reference
| Command | Purpose |
|---------------------|--------------------------------------------------------------------|
| `npm run start` | Start BrowserSync dev server with live reload (alias for `watch`) |
| `npm run watch` | Start BrowserSync dev server with live reload |
| `npm run build` | Compile Tailwind CSS for production (minified, optimized) |
| `composer lint` | Run PHP_CodeSniffer against WordPress coding standards |
| `composer fix` | Auto-fix PHP_CodeSniffer violations |
| `npx playwright test` | Run Playwright end-to-end tests |
| Command | Purpose |
| --------------------- | -------------------------------------------------------------------- |
| `npm run start` | Start BrowserSync dev server with live reload (alias for `watch`) |
| `npm run watch` | Start BrowserSync dev server with live reload |
| `npm run build` | Compile Tailwind CSS for production (minified, optimized) |
| `composer lint` | Run PHP_CodeSniffer against WordPress coding standards |
| `composer fix` | Auto-fix PHP_CodeSniffer violations |
| `npx playwright test` | Run Playwright end-to-end tests |
| File | Purpose |
|-----------------------------------|------------------------------------------------------|
| `.env` | Local environment config (`LOCALHOST_URL`, `BROWSERSYNC_PORT`) |
| `styles/theme.css` | Tailwind CSS entry point (edit this to add imports) |
| `static/dist/theme.css` | Compiled CSS output (generated, do not edit manually)|
| `views/blocks/*/block.json` | ACF block registration files |
| `lib/activation.php` | Theme activation routine (creates pages, installs plugins) |
| `lib/class-enqueue.php` | Frontend/backend/editor asset loading |
| `lib/hooks.php` | Menu registration, sidebars, theme support, cleanup |
| `functions.php` | Theme bootstrap (auto-loads all `lib/*.php` files) |
| `theme.json` | WordPress theme configuration (colors, typography, layout) |
| `acf/group_*.json` | ACF field group definitions (version-controlled) |
| File | Purpose |
| ----------------------------------- | -------------------------------------------------------------- |
| `.env` | Local environment config (`LOCALHOST_URL`, `BROWSERSYNC_PORT`) |
| `styles/theme.css` | Tailwind CSS entry point (edit this to add imports) |
| `static/dist/theme.css` | Compiled CSS output (generated, do not edit manually) |
| `views/blocks/*/block.json` | ACF block registration files |
| `lib/activation.php` | Theme activation routine (creates pages, installs plugins) |
| `lib/class-enqueue.php` | Frontend/backend/editor asset loading |
| `lib/hooks.php` | Menu registration, sidebars, theme support, cleanup |
| `functions.php` | Theme bootstrap (auto-loads all `lib/*.php` files) |
| `theme.json` | WordPress theme configuration (colors, typography, layout) |
| `acf/group_*.json` | ACF field group definitions (version-controlled) |