Skip to content

thingsym/wp-theme-boilerplate

Repository files navigation

WP Theme Boilerplate

Next Generation WordPress Theme Starter Kit

Features

  • Improve template hierarchy and directory layout
  • Implement WordPress Theme Autoloader
  • Implement class based theme functions
  • Implement Theme hooks
  • Support the Block Editor Gutenberg
  • Generate your starter theme on Theme Starter script
  • Theme development environment on npm scripts
  • Theme testing environment on composer scripts

Getting Started

1. clone WP Theme Boilerplate with change directory name to Theme Slug

git clone https://github.com/thingsym/wp-theme-boilerplate.git mytheme

or

Download archive file (zip or tar.gz) form GitHub Releases page

Note: Change folder name to Theme Slug

2. run Theme Starter script with passing Theme name

Note: Run only once. Note: Theme name does case-sensitive.

cd mytheme

bash bin/setup.sh --theme 'Mytheme'

or (via npm)

npm run setup -- --theme 'Mytheme'

3. delete bin/setup.sh

4. update the theme header in style.css

5. update or delete README.md

6. create Git repository and first commit

git init
git add .
git commit -m "initial commit"

7. build Theme development environment

npm install

8. make your WordPress theme

9. Good luck

Requirements

Optional requirements

Directory Layout

|- bin/                           # scripts
|    |- setup.sh                  # Theme Starter script
|    |- install-wp-tests.sh       # install script for WordPress testing environment
|    |- reset-wp-tests.sh         # reset script for WordPress testing environment
|    |- uninstall-wp-tests.sh     # uninstall script for WordPress testing environment
|
|- css/                     # stylesheet files
|    |- block-editor-style.css
|    |- editor-style.css
|    |- style-rtl.css
|    |- style.css
|    |- style.min.css
|
|- functions/               # PHP classes and functional php files
|    |- custom-header/
|    |- customizer/
|    |- entry-meta/
|    |- post-thumbnail/
|    |- setup/
|    |- template/
|    |- theme-hook/
|    |- autoload.php        # WordPress Theme Autoloader
|    |- loadup.php
|
|- js/                      # Javascript files
|
|- languages/               # Translation files
|
|- node_modules/            # npm modules
|
|- src/                     # assets for development
|    |- js/               # javascript files
|    |- scss/               # scss files
|
|- templates/               # template files and partial files
|    |- content/            # content part files
|    |- page-header/            # page header part files
|    |- parts/              # partial files
|    |- sidebar/            # sidebar part files
|    |- 404.php
|    |- archive.php
|    |- index.php
|    |- page.php
|    |- search.php
|    |- single.php
|
|- tests/                   # testing suite files
|    |- js/                 # Javascript testing suite
|    |- phpunit/            # PHP testing suite
|
|- vendor/                  # Composer dependencies
|
|- .editorconfig            # Editor config settings
|- .gitignore               # gitignore config settings
|- .travis.yml
|- composer.json            # Composer package file for theme testing and using PHP libraries
|- functions.php            # WordPress functionality file
|- index.php                # WordPress file
|- LICENSE                  # LICENSE file
|- package.json             # npm package file for theme development
|- phpcs.ruleset.xml        # PHP_CodeSniffer config settings
|- phpmd.ruleset.xml        # PHPMD config settings
|- phpstan.neon             # PHPStan config settings
|- phpunit.xml              # PHPUnit config settings
|- README.md                # this file
|- readme.txt               # theme readme file for your starter theme
|- screenshot.png           # Screenshot image file
|- style.css                # main stylesheet file, only theme header
|- webpack.config.js        # webpack config settings

Template hierarchical

The top priority template hierarchy is the templates directory.

For example, the template hierarchy of the top page is as follows:

  1. templates/front-page.php
  2. front-page.php
  3. templates/home.php
  4. home.php
  5. templates/index.php
  6. index.php

Theme hooks

Theme hooks adds an action through the add_action function.

add_action( 'wp_theme_boilerplate/theme_hook/site/header', [ $this, 'header' ] );

Note: Replace wp_theme_boilerplate with your_theme_slug

Site

  • your_theme_slug/theme_hook/site/header/before
  • your_theme_slug/theme_hook/site/header
  • your_theme_slug/theme_hook/site/header/after
  • your_theme_slug/theme_hook/site/content/before
  • your_theme_slug/theme_hook/site/content/after
  • your_theme_slug/theme_hook/site/footer/before
  • your_theme_slug/theme_hook/site/footer
  • your_theme_slug/theme_hook/site/footer/after

Content

  • your_theme_slug/theme_hook/content/prepend
  • your_theme_slug/theme_hook/content/append
  • your_theme_slug/theme_hook/content/index/prepend
  • your_theme_slug/theme_hook/content/index/append
  • your_theme_slug/theme_hook/content/page/prepend
  • your_theme_slug/theme_hook/content/page/append
  • your_theme_slug/theme_hook/content/archive/prepend
  • your_theme_slug/theme_hook/content/archive/append

Entry

  • your_theme_slug/theme_hook/entry/meta/header
  • your_theme_slug/theme_hook/entry/post_thumbnail
  • your_theme_slug/theme_hook/entry/meta/footer

Theme Starter script

Theme Starter script generate your starter theme.

Note: Run only once.

bin/setup.sh --theme 'Mytheme'

Via npm

npm run setup -- --theme 'Mytheme'

Theme development environment

Build development environment

npm install

Run npm script

npm run <task>

npm scripts task list

  • setup
  • makepot
  • msgfmt:ja
  • msgfmt
  • sass:style
  • sass:style:minify
  • sass:block-editor
  • rtlcss:rtl
  • webpack
  • build:css
  • build:js
  • build:i18n
  • build
  • lint:css
  • lint:scss
  • lint:es
  • lint:\es:fix
  • lint
  • stats:css
  • bs:server
  • bs:server:watch
  • bs:proxy
  • bs:proxy:watch
  • watch:css
  • watch:js
  • watch
  • server
  • archive:package
  • archive:zip
  • archive

Theme testing environment

Build testing environment

composer install

Run composer script

composer run <task>

composer scripts task list

  • phpcs:config-set
  • phpcs
  • phpcs:warning
  • phpcbf
  • phpmd
  • phpstan
  • phpunit
  • ci

Resources (Third-party)

Contribution

Patches and Bug Fixes

Small patches and bug reports can be submitted a issue tracker in Github. Forking on Github is another good way. You can send a pull request.

  1. Fork WP Theme Boilerplate from GitHub repository
  2. Create a feature branch: git checkout -b my-new-feature
  3. Commit your changes: git commit -am 'Add some feature'
  4. Push to the branch: git push origin my-new-feature
  5. Create new Pull Request

Changelog

[2.1.0] - 2021.01.07

  • replace scss from node-sass to dart-sass
  • fix npm scripts for dart-sass
  • add dart-sass
  • update node package
  • add GitHub actions, remove .travis.yml

[2.0.0] - 2020.08.27

  • imporve code with phpcs, phpmd and phpstan
  • update testunit configuration
  • fix composer.json

[1.9.0] - 2020.08.26

  • fix webpack.config.js, generate compressed and uncompressed files
  • fix npm scripts
  • update package.json

[1.8.0] - 2020.08.10

  • update package.json
  • assign object to variable for child theme
  • fix hooks priority

[1.7.0] - 2020.05.14

  • replace array() to short array syntax []

[1.6.0] - 2020.04.23

  • fix css header
  • fix npm scripts
  • fix setup.sh
  • move test case directory
  • bump up phpunit version 7.x
  • add version number with zip archive

[1.5.0] - 2020.03.24

  • move template parts files to page-header dir
  • add non minified javascript files for theme review
  • change javascript files bundle from webpack to minify
  • move javascript files to src/javascript/main directory
  • exclude node_modules in test scope
  • remove README.md in zip archive

[1.4.0] - 2019.11.19

  • fix Theme Starter script
  • add style-rtl.css
  • update .pot
  • fix Requires at least to 5.0
  • fix header image and logo image size
  • add archive script with npm script

[1.3.0] - 2019.10.21

  • fix test case
  • bundle javascript files
  • add webpack, replace from uglify-es
  • move javascript files to src directory
  • fix error content
  • remove paginated with archive

[1.2.0] - 2019.09.30

  • add Class Editor

[1.1.2] - 2019.09.19

  • fix site-info
  • add editor-style.scss

[1.1.1] - 2019.07.30

  • replace from uglifyjs to uglify-es
  • fix header container

[1.1.0] - 2019.07.11

  • add Composer autoloader
  • add editor-style.css
  • add test case

[1.0.0] - 2019.05.19

  • initial release

License

Licensed under GPLv2 or later

Author

thingsym

Copyright (c) 2019-2020 by thingsym