This post describes a super simple and time saving Yeoman workflow to build WordPress themes. To make this post work for you, you should have a basic understanding of nodejs, nodes package manager npm, Yeoman workflows, Grunt and SASS/SCSS. Ones you have all up and running, you will create a Yeoman WordPress starter theme in no time. But it is not only a theme it comes with a bunch of features:
- A fully funtional WordPress theme with a working grunt development environment.
- The generated theme is tested against the Theme check and Theme Forest check plugins and runs without errors, warnings or recommendations, is visually tested with Testdata for the theme unit test, runs without errors or warnings in debug mode and follows the WordPress coding standards a 100%
- A pre-filled HTML documentation
Getting started
Getting started with nodejs, npm and Yeoman is well described elsewhere, so instead of repeating all of it you will get some links that worked for me. To go on, you should have the current version of nodejs, npm and yeoman running. Than you can easily install our generator from the npm registry. Note that on some setups you will have to run this command with super-user permissions:
npm install -g generator-wp-theme
Now you have installed the generator you can generate your first starter theme. As you might want to test it in your WordPress development environment, you should go to a running WordPress installations themes directory and run:
yo wp-theme
Thats it! Just answer some simple questions in the terminal and the installation should run through without errors and installing the theme plus all needed local node modules.
Developing with the Yeoman WordPress theme
First of all the generated starter theme provides you with a solid base of WordPress theme templates, following among others WordPress theme directory and ThemeForest standard requirements. The functions.php file sets your theme up to support all required functions like a custom header and background. All should be ready to make your adjustments to build a perfect theme.
SASS/SCSS setup
The themes style.css file is compiled from a bunch of SCSS-files. To get a layout grid and some nice mixins the bourbon and neat libraries are build in. The SCSS-file names should be self-explaining, however a short overview in including order follows:
- vendor/normalize
- Includes the normalizing css.
- vendor/bourbon/bourbon
- Includes the great bourbon mixin library.
- _base.scss
- Defines the main colors of the themes and basic HTML-element styling.
- _grid-settings.scss
- Defines and includes the base setup for the themes grid. The default grid is bourbons neat.
- _typography.scss
- Defines all fonts, typography related mixins and HTML-element styles. Defines even some font-size variables.
- _components.scss
- Here should be placed the basic mixins and placeholders for the theme.
- _wp-base.scss
- Defines some basic WordPress classes, like sticky, alignleft or bypostauthor.
- _header.scss
- Contains the header styles.
- _navigation.scss
- Contains the navigation styles.
- _content.scss
- Contains the basic content styles for posts and pages.
- _post-formats.scss
- Extends the content styling with styling for multiple WordPress post formats.
- _footer.scss
- Contains the footer styles.
Grunt tasks
The generated Yeoman WordPress theme provides a working Grunt configuration. All Grunt related assets like the gruntfile.js and the package.js are placed in the grunt directory. The Yeoman generator has already setup Grunt for the theme and installed all node modules in grunt/node_modules. If you want to install manually, go to the grunt directory and run
npm install --save-dev
All Grunt tasks are called from the grunt directory. You can manage the following available tasks, by running these commands:
- grunt
- Is running the default task-list, which is the same as running grunt jshint, grunt uglify and grunt sass.
- grunt jshint
- Checks the JavaScript files and gives you some hints.
- grunt uglify
- Takes the JavaScript files and concatenates and minifies it to one file: js/scripts.min.js, which is included in the theme.
- grunt sass:dev
- Is compiling all the scss files to one expanded style.css in the themes root directory.
- grunt sass:prod
- Is compiling all the scss files to one compressed style.css in the themes root directory.
- grunt watch
- Watches the scss and js files for changes and runs the above tasks automatically, plus giving you a cross-OS desktop notice on success.
- grunt dist
- Runs grunt uglify and grunt sass:prod, takes all the production relevant theme files and places them in the dist directory under the themes root. Now the dist directory contains a production ready theme, which can be uploaded to a live server.
- grunt phpcs
- Requires PHP CodeSniffer with WordPress standard installed in the development environment.
Checks the themes php files against the WordPress coding standards.
Documentation
In case you want to upload your theme to some marketplace or theme directory, Yeoman WordPress theme generator even creates a HTML-documentation for you. The documentation is based on the Theme forrest documentation template It’s located in the doc directory and already covers some base information about your theme. You just have to complete it with your specific information and your theme is documented as well.
Now, make themes!
With the Yeoman WordPress theme generator (generator-wp-grunted-theme), you should get everything you need, to build great themes. Be welcome to let me know if you have done so, or even better if you want to add a important task, find a bug or have an improvement idea.
Good job Daniel!
How about to generate a worpdress installation ?
Do you use something like yopress ?
I am thinking of creating my own yomen generator to suit better my environment.
Thanks
Thanks Gus,
I develop all themes in one WordPress installation, so I don’t use YeoPress. It seems to be a very good and advanced generator, though. My approach with my Yeoman WordPress theme generator is to get me to the point where I can directly start development on my theme idea, without the trouble of setting up the whole grunt/scss/doc structure.
There might be some other generators for a full stack WordPress environment out there, but let me know when you have done your own, would be great to have a look at it …
I was bumping my head for days to get best practice for utilizing yeoman in my next wordpress theme project, and here is a good starter! thanks for your great post and sharing all these stuff. I will check it out soon.
Awesome stuff ! Any chance of adding support for Modernizr and Compass ?
Hi Chris, I’m working on a new release, which includes Modernizr. Haven’t decided on Compass yet. You thinking about a prompt in the generator, asking if you want to use Bourbon or Compass?
Hi Chris,
I’m encountering some Issues after generating the theme.
1 – Everything goes okay, when I set the generated theme as the wp default and I go to see it, I get this error all over the wp-installation:
Parse error: parse error, expecting `”identifier (T_STRING)”‘ or `'(” in /Library/WebServer/Documents/wordpress/wp-content/themes/new-theme-name/functions.php on line 30
Any ideas?
Thanks,
Mike
Hi,
not sure really, can’t reproduce your issue. Did you use some kind of non-alphanumeric chars in the themes name or the identifier? If you want me to look at it, just make a gist of your generated functions.php file and post the link here or write me a message on twitter @danielauener.
All the best!
Daniel
Yeah some kind of prompt when setting up the theme would be perfect. Also just to say i’ve been using this for a couple of WordPress projects now and it’s really great so thanks for the good work.
Hi Chris,
thanks for the feedback! I’ll let you know when I release the new version.
Thanks again
Daniel
Really well done, TY!
Having looked at the resulting output, it shouldn’t be too tricky for me to modify to include some pet tools, Compass, Susy, grunt-contrib-compass, load-grunt-tasks.
I’ve enjoyed working with the Underscores theme, as it really does start from zero, but will test this set-up to consider switching.
Continued success,
Robin
Thanks Robin. As it happens I’m just working on the next release, which will include Underscores and roots as optional starter themes, as well as compass as optional pre-processor. So stay tuned, I will let you know when it’s released.
Hi, Daniel!
Very inspired!
Does generator-wp-theme already supports Roots/Underscores?
Cool!! Looking forward.
@Daniel
Great post. Mind me asking how you’re doing with including Underscores? Cheers!
It’s on the way. I hope to finish the new release within the next to weeks.
Thanks for creating this. I will be using it with our team to streamline new wordpress themes.
Great job! Thanks a ton!
I having trouble using phpcs though..
Works fine in command line but can’t get it to work through grunt…
I got a warning Object ../*.php has no method ‘join’
Any guess? I tried a –verbose and is says [File]:no files
dir path is good (tried a few different ones), got php files in it.. I’m kind of lost.
Any suggestion would be much appreciated
I was scratching my head since yesterday, but I had to post a comment to finally find the solution 5 mins later:
in the phpcs task, the dir setting must be an array:
[ ‘../classes/*.php’ ]
If anyone has the same issue, I hope it will help
Cheers!
Thanks for pointing that out. I’m working hard on the next release and will include your adjustment.
Hi Daniel,
Do you plan to add image min.js to the generator?
Dave Maran
Not right now I’m afraid, but I’ll add it to my possible updates list.
I love this! Thank you so much. Just a quick note that after installing phpcs (including the fix above) and running it it gives me a bunch of errors and warnings. Mostly about spacing using tabs not spaces.
Do you need to include some kind of config for phpcs to ignore certain errors for it to work here?
I’ve used the WordPress coding standards module for phpcs. I found it relatively easy to adjust for certain projects.
Is there any plan to add Autoprefixir, or can that be easily added to the grunt configuration on my own?
Please tell me there is a potential update to this generator or an alternative solution you’re using as it’s 100% EXACTLY what I need.
Hi Daniel,
Just a quick note to say this is awesome, thanks! I had been looking into creating my own custom generator and your’s gives me a grwat head start.
Kepp up the good work!
Pete
Does this still work? Getting all sorts of errors trying to install and run. Perfect for what I was going to build myself.