This repository contains boilerplate code, and references to more boilerplate code via submodules, for developing custom WordPress themes and plugins using a common foundation. It is intended to streamline my workflow by starting with a common set of tools and customisations that I have developed and refined over the years, and continue to do so with every new project. It is a living work-in-progress, with lots of TODOs and bits that are scrappy or not yet fully functional, but it is a solid foundation for my own work and I publish it here in the spirit of open source in case it is useful to other developers.
- Prerequisites
- Common submodules
- Other required plugins
- Initial setup
- Development
- Miscellaneous development notes
- Warranty (lack thereof)
- Contributing
- Git
- Node.js
- Gulp installed globally (Gulp 5+ with gulp-cli 3+)
- Local development environment set up with WordPress installed and running
- Intermediate to advanced knowledge of WordPress, PHP, HTML, SCSS, JS, etc as it pertains to developing custom themes and plugins according to the requirements that brought you here. While a fair bit of boilerplate layout and design stuff is included for common requirements, if you don't want to write code this isn't the starterkit for you.
Repositories common to many sites (including those not developed by me, if available via GitHub) are included as submodules for easier updating.
- Advanced Custom Fields Pro
- Advanced Editor Tools (also known as TinyMCE Advanced) is included in this repo because at the time of writing, it isn't available on GitHub to use as a submodule.
Note: If working on the starterkit itself using a fresh installation using Local By Flywheel, ensure you initialise it as multisite during the setup process in Local.
- Initialise it as a Git repo
git init
- Create a basic
.gitignorefile to avoid committing pretty much anything initially (this is temporary and will be overwritten by this repo's.gitignore)
conf
logs
setup
.idea
debug.log
local-xdebuginfo.php
app/public/
- Do an initial commit
git add .gitignore
git commit -m "Initial commit"
- Allow pulling this repo into the non-empty install directory by adding it as the upstream:
git remote add upstream /~https://github.com/doubleedesign/doublee-wordpress-starterkit
- Pull in this main repo[1]
git pull upstream develop --allow-unrelated-histories --ff --strategy-option=theirs
- Delete the default theme folders if you haven't already
rm -rf app/public/wp-content/themes/twentytwenty*
- Pull in the submodules for your chosen branch with:
git submodule update --init
- Ensure the submodules are up-to-date with the latest commits:
git submodule update --remote
See the Development section below.
[1]. --strategy-option=theirs (equivalent to -X theirs) automatically resolves any merge conflicts preferring the files in this repo; if you're working with a fresh install, that would only be the temporary .gitignore from step 2, as intended. Skip this if you expect conflicts you want to resolve manually.
For new projects, run the setup script and follow the prompts to do a find-and-replace across the client theme and client plugin boilerplates and rename the relevant files and folders with the client/project name.
::warn:: This script has not yet been updated for the WIP overhaul of the block theme. // TODO
Note: The file paths are set up for Local by Flywheel. Update them accordingly if you have a different setup.
node setup/setup.js
- Install ACF Pro and enter licence key
- Import TinyMCE settings from
setup/tinymce-settings.jsonin your selected theme. - Add logo, Font Awesome kit ID and external fonts to be loaded in the
<head>in the global options in the admin (the page will be labelled with your site name) - Update any cloud-hosted font paths within the client theme folder
- Add favicon in Settings > General Settings (the native one, where you set your site name)
cdinto the client theme folder and install dependencies (npm install)- Update
theme-vars.jsonin client theme - Run Gulp scripts to generate stylesheets, bundle scripts, etc.
- Activate your child theme
- As needed, install Ninja Forms + extensions, WooCommerce + extensions, etc.
- Add client-specific
screenshot.pngto your child theme folder
To work on the starterkit itself, follow the [Initial Setup][#initial-setup] steps above, then:
- Allow pulling this repo into the non-empty install directory by adding it as the origin:
git remote add origin /~https://github.com/doubleedesign/doublee-wordpress-starterkit
- Fetch the latest:
git fetch origin
- Reset local
developto matchorigin/develop:
git reset --hard origin/develop
- Delete the default theme folders if you haven't already
rm -rf app/public/wp-content/themes/twentytwenty*
- If appropriate, create and check out a new branch for your work:
git checkout -b my-new-feature
- Pull in the submodules:
git submodule update --init
See ./storybook/README.md for details on setting up Storybook to develop and test theme components in an isolated fashion.
In addition to standard npm install of dependencies, here's some quick reminders of the scripts to run for the submodules and Storybook symlinks:
Update all submodules:
./update-submodules.shTo open an admin PowerShell instance from WSL:
current_dir=$(wslpath -w $(pwd))powershell.exe -Command "Start-Process powershell -ArgumentList '-NoProfile -ExecutionPolicy Bypass -NoExit -Command Set-Location -LiteralPath \"${current_dir}\"' -Verb RunAs"Then in PowerShell, to delete and recreate the symlinks for Storybook:
cd storybook./scripts/symlinks.ps1The reason for deleting and re-creating them is that Git treats them as a generic file, not a proper symlink, and checking they exist will return true in that case even though they're not right. (Possibly a Windows-only issue, but it's a PowerShell script, so...)
- Run
gulp theme-jsonagain - Run
gulp variablesagain before runninggulp theme,gulp components, gulp modules, orgulp blocks` again
- Note that file paths in
.gitmodules,.gitignore, and any future automated scripts use Flywheel's directory structure where the WordPress install is inapp/public/so may need to be updated for other setups - Check Node version against range in
package.json(due to Gulp compatibility) - Make sure
_variables.scssis generated before trying to generate any other styles - If WP is loading old colours, make sure you have updated
theme.json(usinggulp theme-jsonunless that would overwrite changes in which case update the file manually) Unsupported gulp versionerror: You may need to uninstall and reinstall Gulp globally, and restart your terminal for the change to be recognised.
Because the branches have some different submodules, you may encounter issues when switching between them and need to clean up the ones that aren't needed in the current branch. I have included a Bash script - ./update_submodules.sh - that clears the Git module cache and re-initialises the submodules for the current branch. It also checks out the latest commit for each submodule, helping ensure they stay up-to-date.
There isn't one.
I have developed this starterkit for my own use, and written this documentation primarily for my future self. Sometimes I build a bunch of WordPress sites close together, and other times I might go 6 months between new builds, so I put all of this together for my own efficiency and consistency. In the spirit of open source, have posted it here for the benefit of other developers to pay it forward in tribute to how I benefitted from the likes of Brandon Jones's Super Skeleton and Ole Fredrik Lie's FoundationPress earlier in my career, and continue to benefit from other open source developers' work.
WordPress is no longer my full-time career and so I unfortunately cannot consistently dedicate time to this open source work outside of what directly benefits me and my clients. Suggestions, feature requests, bug reports, and general feedback are very welcome (I'd love to hear if you find this useful!) and I will endeavour to respond when I have time cand capacity, but ultimately use of this kit (including the referenced submodules) is at your own risk and the results are your own responsibility.
Now to pivot from the "can't help ya" negativity of the warranty section above, I would like to emphasise that feedback is absolutely welcome (I just can't promise if or when I'll action it). If you do find this kit and/or its associated submodules that I developed or forked and modified useful and add features, fix bugs, improve the existing functionality, etc., I would appreciate it if, in the spirit of open source, you would contribute it back via pull request in the relevant repository (i.e., either here or in the submodule's repo).
If you are not able to make the change yourself, please feel free to raise the suggestion / report the bug by creating an issue in the relevant repository.
Thank you for reading, thanks in advance for any contributions or feedback you may have, and happy coding!