Files and folders structure

Chisel uses a two-tier architecture that separates core theme functionality from project-specific customizations. This allows the core Chisel files to be updated automatically while preserving your custom code.

Top‑level files

File	Purpose
`style.css`	Theme base stylesheet with theme metadata
`theme.json`	Global styles, colors, typography & Gutenberg settings
`functions.php`	Theme bootstrap; autoloads classes from core/ and custom/
`webpack.config.js`	Webpack configuration extending chisel-scripts
`package.json`	NPM dependencies and scripts
`composer.json`	PHP dependencies (Timber, etc.)

Template entry points

Standard WordPress template files that prepare context and load Twig templates:

index.php, single.php, page.php, archive.php
search.php, author.php, 404.php
header.php, footer.php
woocommerce.php — WooCommerce template loader

Coding standards configuration

File	Purpose
`phpcs.xml`	PHP CodeSniffer rules
`twig_cs.php`	Twig coding standards config
`.twig-cs-fixer.php`	Twig CS Fixer configuration
`prettier.config.mjs`	Prettier code formatting
`stylelint.config.mjs`	Stylelint CSS/SCSS linting
`.eslintrc.cjs`	ESLint JavaScript linting
`lint-staged.config.mjs`	Lint-staged pre-commit config
`.editorconfig`	Editor formatting consistency

Other files

screenshot.jpg — Theme screenshot for WP admin
README.md — Theme documentation
.nvmrc — Node version specification
.gitignore — Git ignore patterns

Directories

core/ — Base Chisel functionality

Important: Files in core/ are automatically updated when you run npm run update-chisel. Do not modify these files directly— use the custom/ folder instead.

The core/ directory contains the base theme functionality organized by responsibility:

core/
├── Ajax/ # AJAX endpoint implementations
│ └── LoadMoreEndpoint.php
├── Controllers/ # REST/AJAX controllers
│ └── AjaxController.php
├── Enums/ # PHP 8.1 enums for type safety
│ ├── AcfOptionsPageType.php
│ └── BlocksType.php
├── Factories/ # Registration factories
│ ├── RegisterAcfOptionsPage.php
│ ├── RegisterBlocks.php
│ ├── RegisterCustomPostType.php
│ └── RegisterCustomTaxonomy.php
├── Helpers/ # Static helper utilities
│ ├── AcfHelpers.php
│ ├── AjaxHelpers.php
│ ├── AssetsHelpers.php
│ ├── BlocksHelpers.php
│ ├── CacheHelpers.php
│ ├── CommentsHelpers.php
│ ├── DataHelpers.php
│ ├── GravityFormsHelpers.php
│ ├── ImageHelpers.php
│ ├── ThemeHelpers.php
│ ├── WoocommerceHelpers.php
│ └── YoastHelpers.php
├── Interfaces/ # PHP interfaces
│ └── AjaxEndpointInterface.php
├── Plugins/ # Plugin integrations
│ ├── GravityForms/
│ ├── Woocommerce/
│ └── Yoast/
├── Timber/ # Timber/Twig extensions
│ ├── Cache.php
│ ├── ChiselImage.php
│ ├── ChiselPost.php
│ ├── ChiselProduct.php
│ ├── ChiselProductCategory.php
│ ├── ChiselTerm.php
│ └── Components.php
├── Traits/ # Reusable PHP traits
│ ├── Hooks.php
│ ├── HooksSingleton.php
│ ├── PageBlocks.php
│ ├── Rest.php
│ └── Singleton.php
└── WP/ # Core WordPress integration
├── Acf.php
├── AcfBlocks.php
├── Assets.php
├── Blocks.php
├── Comments.php
├── CustomPostTypes.php
├── CustomTaxonomies.php
├── Sidebars.php
├── Site.php
├── Theme.php
└── Twig.php

core/
├── Ajax/ # AJAX endpoint implementations
│ └── LoadMoreEndpoint.php
├── Controllers/ # REST/AJAX controllers
│ └── AjaxController.php
├── Enums/ # PHP 8.1 enums for type safety
│ ├── AcfOptionsPageType.php
│ └── BlocksType.php
├── Factories/ # Registration factories
│ ├── RegisterAcfOptionsPage.php
│ ├── RegisterBlocks.php
│ ├── RegisterCustomPostType.php
│ └── RegisterCustomTaxonomy.php
├── Helpers/ # Static helper utilities
│ ├── AcfHelpers.php
│ ├── AjaxHelpers.php
│ ├── AssetsHelpers.php
│ ├── BlocksHelpers.php
│ ├── CacheHelpers.php
│ ├── CommentsHelpers.php
│ ├── DataHelpers.php
│ ├── GravityFormsHelpers.php
│ ├── ImageHelpers.php
│ ├── ThemeHelpers.php
│ ├── WoocommerceHelpers.php
│ └── YoastHelpers.php
├── Interfaces/ # PHP interfaces
│ └── AjaxEndpointInterface.php
├── Plugins/ # Plugin integrations
│ ├── GravityForms/
│ ├── Woocommerce/
│ └── Yoast/
├── Timber/ # Timber/Twig extensions
│ ├── Cache.php
│ ├── ChiselImage.php
│ ├── ChiselPost.php
│ ├── ChiselProduct.php
│ ├── ChiselProductCategory.php
│ ├── ChiselTerm.php
│ └── Components.php
├── Traits/ # Reusable PHP traits
│ ├── Hooks.php
│ ├── HooksSingleton.php
│ ├── PageBlocks.php
│ ├── Rest.php
│ └── Singleton.php
└── WP/ # Core WordPress integration
├── Acf.php
├── AcfBlocks.php
├── Assets.php
├── Blocks.php
├── Comments.php
├── CustomPostTypes.php
├── CustomTaxonomies.php
├── Sidebars.php
├── Site.php
├── Theme.php
└── Twig.php

custom/ — Project-specific customizations

The custom/ directory is where you add all project-specific code. Files here extend or override core functionality and are never overwritten by Chisel updates

custom/
├── app/              # PHP classes (namespace: Chisel\WP\Custom\)
│   ├── Timber/       # Custom Timber classes
│   │   └── ChiselPost.php
│   └── WP/           # Custom WordPress classes
│       ├── Acf.php           # ACF options pages
│       ├── Ajax.php          # Custom AJAX routes
│       ├── Assets.php        # Custom styles/scripts
│       ├── CustomPostTypes.php  # CPTs and taxonomies
│       ├── Site.php          # Timber context & classmaps
│       └── Twig.php          # Custom Twig functions/filters
├── views/            # Twig template overrides
│   └── README.md
└── functions.php     # Bootstrap for custom classes

custom/
├── app/              # PHP classes (namespace: Chisel\WP\Custom\)
│   ├── Timber/       # Custom Timber classes
│   │   └── ChiselPost.php
│   └── WP/           # Custom WordPress classes
│       ├── Acf.php           # ACF options pages
│       ├── Ajax.php          # Custom AJAX routes
│       ├── Assets.php        # Custom styles/scripts
│       ├── CustomPostTypes.php  # CPTs and taxonomies
│       ├── Site.php          # Timber context & classmaps
│       └── Twig.php          # Custom Twig functions/filters
├── views/            # Twig template overrides
│   └── README.md
└── functions.php     # Bootstrap for custom classes

Key points:

Classes in custom/app/ use the Chisel\WP\Custom\ namespace
Custom views override files with the same name in views/
Register customizations via filters in the respective custom class

src/ — Theme source assets

All authored code that gets compiled by the build system:

src/
├── blocks/           # Native WordPress blocks
│   └── accordion/
│       ├── block.json
│       ├── edit.js
│       ├── save.js
│       ├── view.js
│       ├── style.scss
│       ├── editor.scss
│       └── index.js
├── blocks-acf/       # ACF blocks
│   └── slider/
│       ├── block.json
│       ├── slider.twig
│       ├── style.scss
│       ├── script.js
│       └── acf-json/
├── design/           # SCSS design tokens
│   ├── settings/
│   └── tools/
├── scripts/          # JavaScript modules
│   ├── app.js           # Frontend entry
│   ├── admin.js         # Admin entry
│   ├── editor.js        # Editor entry
│   ├── login.js         # Login page entry
│   ├── modules/         # JS modules
│   │   ├── load-more.js
│   │   ├── main-nav.js
│   │   ├── slider.js
│   │   └── utils.js
│   └── editor/          # Editor-specific modules
└── styles/           # SCSS organized by ITCSS layers
    ├── main.scss        # Main entry
    ├── admin.scss       # Admin styles
    ├── editor.scss      # Editor styles
    ├── login.scss       # Login page styles
    ├── woocommerce.scss # WooCommerce styles
    ├── gravity-forms.scss
    ├── generic/         # Resets, normalize
    ├── elements/        # HTML element styles
    ├── objects/         # Layout patterns
    ├── components/      # BEM components
    ├── blocks/          # Block-specific styles
    ├── widgets/         # Widget styles
    ├── utilities/       # Utility classes
    ├── vendor/          # Third-party styles
    ├── woo/             # WooCommerce SCSS
    ├── wp-admin/        # Admin-specific
    └── wp-editor/       # Editor-specific

src/
├── blocks/           # Native WordPress blocks
│   └── accordion/
│       ├── block.json
│       ├── edit.js
│       ├── save.js
│       ├── view.js
│       ├── style.scss
│       ├── editor.scss
│       └── index.js
├── blocks-acf/       # ACF blocks
│   └── slider/
│       ├── block.json
│       ├── slider.twig
│       ├── style.scss
│       ├── script.js
│       └── acf-json/
├── design/           # SCSS design tokens
│   ├── settings/
│   └── tools/
├── scripts/          # JavaScript modules
│   ├── app.js           # Frontend entry
│   ├── admin.js         # Admin entry
│   ├── editor.js        # Editor entry
│   ├── login.js         # Login page entry
│   ├── modules/         # JS modules
│   │   ├── load-more.js
│   │   ├── main-nav.js
│   │   ├── slider.js
│   │   └── utils.js
│   └── editor/          # Editor-specific modules
└── styles/           # SCSS organized by ITCSS layers
    ├── main.scss        # Main entry
    ├── admin.scss       # Admin styles
    ├── editor.scss      # Editor styles
    ├── login.scss       # Login page styles
    ├── woocommerce.scss # WooCommerce styles
    ├── gravity-forms.scss
    ├── generic/         # Resets, normalize
    ├── elements/        # HTML element styles
    ├── objects/         # Layout patterns
    ├── components/      # BEM components
    ├── blocks/          # Block-specific styles
    ├── widgets/         # Widget styles
    ├── utilities/       # Utility classes
    ├── vendor/          # Third-party styles
    ├── woo/             # WooCommerce SCSS
    ├── wp-admin/        # Admin-specific
    └── wp-editor/       # Editor-specific

views/ — Twig templates

views/
├── base.twig              # Base layout template
├── index.twig             # Archive/index template
├── single.twig            # Single post template
├── page.twig              # Page template
├── 404.twig               # 404 template
├── archive.twig           # Archive template
├── author.twig            # Author archive
├── search.twig            # Search results
├── components/            # Reusable components
│   ├── header.twig
│   ├── footer.twig
│   ├── logo.twig
│   ├── main-nav.twig
│   ├── pagination.twig
│   ├── post-item.twig
│   └── slider.twig
├── objects/               # Object templates (icons, etc.)
├── partials/              # Partial templates
├── sidebar-*.twig         # Sidebar templates
└── woocommerce/           # WooCommerce templates
    ├── archive-product.twig
    ├── single-product.twig
    ├── content-product.twig
    ├── content-product-cat.twig
    └── linked-products.twig

views/
├── base.twig              # Base layout template
├── index.twig             # Archive/index template
├── single.twig            # Single post template
├── page.twig              # Page template
├── 404.twig               # 404 template
├── archive.twig           # Archive template
├── author.twig            # Author archive
├── search.twig            # Search results
├── components/            # Reusable components
│   ├── header.twig
│   ├── footer.twig
│   ├── logo.twig
│   ├── main-nav.twig
│   ├── pagination.twig
│   ├── post-item.twig
│   └── slider.twig
├── objects/               # Object templates (icons, etc.)
├── partials/              # Partial templates
├── sidebar-*.twig         # Sidebar templates
└── woocommerce/           # WooCommerce templates
    ├── archive-product.twig
    ├── single-product.twig
    ├── content-product.twig
    ├── content-product-cat.twig
    └── linked-products.twig

assets/ — Static design assets

assets/
├── fonts/           # Webfonts (.woff2)
├── icons/           # Built SVG sprite
├── icons-source/    # SVG source files
├── images/          # Theme images
└── hashes.php       # Build hash map (autogenerated)

assets/
├── fonts/           # Webfonts (.woff2)
├── icons/           # Built SVG sprite
├── icons-source/    # SVG source files
├── images/          # Theme images
└── hashes.php       # Build hash map (autogenerated)

build/ — Compiled output. Generated by npm run build:

build/
├── scripts/         # Compiled JS bundles
├── styles/          # Compiled CSS + asset manifests
├── blocks/          # Compiled native blocks
├── blocks-acf/      # Compiled ACF blocks
└── runtime.js       # Webpack runtime (dev mode indicator)

build/
├── scripts/         # Compiled JS bundles
├── styles/          # Compiled CSS + asset manifests
├── blocks/          # Compiled native blocks
├── blocks-acf/      # Compiled ACF blocks
└── runtime.js       # Webpack runtime (dev mode indicator)

Other directories:

`acf-json/`	Exported ACF field groups (global)
`patterns/`	Block patterns for the editor
`languages/`	Translation files (.mo/.po)
`.husky/`	Git hooks (pre-commit)
`.vscode/`	VS Code workspace settings
`node_modules/`	NPM dependencies
`vendor/`	Composer dependencies

Where to add things

What you’re adding	Where to put it
Custom Post Types	`custom/app/WP/CustomPostTypes.php` via `chisel_custom_post_types` filter
Custom Taxonomies	`custom/app/WP/CustomPostTypes.php` via `chisel_custom_taxonomies` filter
ACF Options Pages	`custom/app/WP/Acf.php` via `chisel_acf_options_pages` filter
AJAX Endpoints	`custom/app/WP/Ajax.php` via `chisel_ajax_routes` filter, implement in `custom/app/Ajax/`
Custom Assets	`custom/app/WP/Assets.php` via `chisel_frontend_styles` filter
Twig Functions/Filters	`custom/app/WP/Twig.php` via `chisel_twig_register_functions` action
Timber Post Class	`custom/app/Timber/ChiselPost.php`, register in `custom/app/WP/Site.php`
JavaScript	`src/scripts/modules/` and import from entry point
SCSS Styles	`src/styles/` following ITCSS layer conventions
Twig Templates	`views/` or `custom/views/` for overrides
WooCommerce Templates	`views/woocommerce/`
Static Assets	`assets/` (fonts, icons, images)
Native Blocks	`src/blocks/` — use `npm run create-block`
ACF Blocks	`src/blocks-acf/` — use `npm run create-block --variant=dynamic`
Block Patterns	`patterns/` directory

Core vs Custom: Quick reference

Instead of modifying…	Create/modify…
`core/WP/Site.php`	`custom/app/WP/Site.php`
`core/WP/Assets.php`	`custom/app/WP/Assets.php`
`core/Helpers/ImageHelpers.php`	`custom/app/Helpers/ImageHelpers.php`
`core/Timber/ChiselPost.php`	`custom/app/Timber/ChiselPost.php`

The autoloader checks custom/app/ first, allowing your custom classes to take precedence.