wp-theme-starter
Tools
Open Source
PHP
WordPress
The Mozaik WordPress Theme Boilerplate
This is a WordPress theme starter-kit meant to offer a first-class developer experience.
Contents
- Full Feature List
- Important Prerequisites
- Development Guidelines
- Standard Theme Development Process
- Reading Recommendations
- License
- FAQ
Full Feature List
- Separate development theme and auto-generated clutter-free production (built) theme
- Easy enough to port already existing themes over to it
-
gulp build process
-
Dev Mode
- Auto browser refresh/injection on save (even for php files!) powered by BrowserSync
- JavaScript module bundling, chunking and sourcemaps powered by Webpack
- JavaScript ES6+ support via Babel
- JavaScript linting via eslint
- SCSS/SASS compilation and sourcemaps powered by libsass
- SCSS linting via scss-lint (waiting for first stable release of scss-lint)
- CSS prefixing via autoprefixer
- SVG sprite generation via svg-sprite
<li class="task-list-item"> Production Mode</p> <ul class="contains-task-list"> <li class="task-list-item"> Minified CSS via cssmin </li> <li class="task-list-item"> Uglify, dedupe JS via Webpack </li> <li class="task-list-item"> Theme image optimization via imagemin </li> <li class="task-list-item"> SVG optimization via svgmin </li> </ul> </li> <li class="task-list-item"> Build process easily extendable </li> </ul>
-
Dev Mode
- NPM and Bower workflows supported
-
Theme Helpers Library (For more details check out the library’s README)
-
Responsive images specification implementation
-
Helper function to print WordPress media by attachment id using responsive background images,
the picture element or img-srcset-sizes - Responsive images polyfill via picturefill
- Builtin lazyload helper supported by aFarkas/lazysizes
-
Helper function to print WordPress media by attachment id using responsive background images,
<li class="task-list-item"> BEM Style simplified customizable/extendable nav-menu-walker </li> <li class="task-list-item"> BEM Style simplified customizable/extendable pagination renderer that easily supports custom queries </li> <li class="task-list-item"> BEM Style simplified customizable/extendable breadcrumbs renderer that is based on a given menu </li> <li class="task-list-item"> Utility classes to make it easier working with SVGs and SVG Sprites </li> </ul>
-
Responsive images specification implementation
- Battle tested. Used in a multitude of small and large scale projects!
Important Prerequisites
Dev Environment
- Have node and npm installed on your system (node@5.0.0)
- Have gulp globally installed (gulp@^3.9.0)
-
You can use
nvm
to manage the node versions installed on your computer -
You can use
npm-check-updates
to update the node modules in your theme (Note that updating may break things, so be careful)
Windows
On Windows you may need to do some of the following if you run into trouble when running npm install
in this project:
- Install Python – Install version 2.7 of Python and add it to your path or/and create a PYTHONPATH environment variable.
- Install Visual Studio (Express Edition is fine) – We will need this for some of modules that are compiled when installing Theme Starter. Download VS Express, get one of the versions that has C++ – Express 2013 for Windows Desktop for example.
- Set Visual Studio Version Flags – We need to tell node-gyp (something that is used for compiling addons) what version of Visual Studio we want to compile with. You can do this either through an environment variable GYP_MSVS_VERSION. If you are using Express, you have to say GYP_MSVS_VERSION=2013e.
Thanks to Ryanlanciaux
WordPress
- Read the WordPress theme development guidelines
- Understand the WordPress template hierarchy
- Understand the WordPress Loop
- Understand how WordPress helps with Data Validation/Sanitization
- Read up on the following WordPress core APIs:
- Understand when you should use a Custom Functionality Plugin instead of implementing functionality within a theme
JavaScript
- This project uses webpack to provide support for modular JS, read up on the functionality & tools it provides
CSS
- The boilerplate assumes you are using SCSS to write your styles and compiles to CSS using Libsass
- Autoprefixer is used for adding the correct vendor prefixes to the final generated CSS
Development Guidelines
- Avoid committing the built theme to the project repository
-
Avoid committing the
wp-uploads
directory to the project repository - Avoid making changes directly to the built theme — Always use the build process
- In production avoid uploading the theme development directory to a public server
-
It is good practice to enable
WP_DEBUG
in yourwp-config.php
file, but only during development
Standard Theme Development Process
Setup
- Install WordPress and clear it of unnecessary default themes & plugins
-
Clone/Download the contents of this repository into a directory in your WordPress
wp-content/themes
directory (eg: “my-theme_dev”) this will be your “dev theme” -
Open the terminal and navigate to the dev theme, eg:
cd wp-content/themes/<my-theme>_dev
- (Note: The next steps require nodejs @5.0.0 and gulpjs @^3.9.0)
-
Run
npm install
to install all dev dependencies -
Change the
project.config.js
file with your new theme’s…