You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
This repository was archived by the owner on Sep 3, 2024. It is now read-only.
Copy file name to clipboardExpand all lines: readme.md
+9-9Lines changed: 9 additions & 9 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -10,6 +10,7 @@ Why use this project instead of any of the alternatives? A few advantages:
10
10
* You should be able to easily drop your own theme into the `src` folder and start hacking without much additional setup.
11
11
* Documentation and comments in the code assume a novice level of understanding.
12
12
* Builds on existing WordPress and Gulp best practices without doing anything too crazy.
13
+
* Includes several JS and Sass integrations to show you some of the possibilities. All of these are easily removed.
13
14
* This kind of workflow will save you a ton of time and help you make better, more readily-optimized themes once you learn how it all works.
14
15
15
16
@@ -36,7 +37,7 @@ If you're already up and running with most of the usual Node ecosystem tools thi
36
37
## SETUP
37
38
38
39
* Edit `gulpconfig.js` and, *at the very least*, change the `project` variable to match the name of your theme. If you like the way this workflow is setup you shouldn't need to edit any of the files under `gulpfile.js/tasks` just yet.
39
-
* Install all dependencies by running `npm install`. This will fetch all dependencies listed in `package.json` (which includes front-end JavaScript packages and back-end tools like Gulp plugins and [BrowserSync](http://www.browsersync.io/)).
40
+
* Install all dependencies by running `npm install`. This will fetch all dependencies listed in `package.json` (which includes front-end JavaScript packages and back-end tools like Gulp plugins and [BrowserSync](http://www.browsersync.io/)). You may see warnings about deprecated packages and what-not; that's probably fine, just keep going!
40
41
*[BrowserSync](http://www.browsersync.io/) setup: assuming you have a local development environment setup all you should need to do is enter the URL into the `proxy` setting in `gulpconfig.js`. Why use BrowserSync? It's fast, awesome, and allows for simultaneous responsive development across multiple devices.
41
42
*[LiveReload](http://livereload.com/) setup: install a browser extension for [Chrome](https://chrome.google.com/webstore/detail/livereload/jnihajbhpnppcggbcgedagnkighmdlei) or Firefox. Why use LiveReload? It does the job without complications or additional setup after the extension is installed.
42
43
* This build process assumes you're up and running with [source maps for both JavaScript and Sass](http://blog.teamtreehouse.com/introduction-source-maps). You may need to configure your browser or debugging environment to make sense of the minified files generated by Gulp!
@@ -48,7 +49,7 @@ If you're already up and running with most of the usual Node ecosystem tools thi
48
49
49
50
Previously this project shipped without a working theme included. I figured that with all the great starter themes out there (for instance, [_s](https://github.com/Automattic/_s), [Roots](https://github.com/roots/roots), and [Bones](https://github.com/eddiemachado/bones)) it wouldn't be hard to drop one in and start theming. I don't personally use any of these so I was a little surprised to discover how tricky this can be. Starter themes, despite their "bare bones" reputation, are often bulky and opinionated. Some even ship with their own build processes already in place!
50
51
51
-
It seems there is a need for what I'd call a *minimum viable theme*: a truly bare bones WordPress starter theme featuring only the essentials to get up and running, something that you can assess at a glance. For the purposes of this project I have created such a theme, tentatively named `voidx`. It isn't pretty and isn't up to [WordPress standards](https://wordpress.org/plugins/theme-check/) but it works well enough to show off some of the power of this workflow. Feel free to play with or discard it as you wish. All files under `src` can be replaced by your own files, you just have to be sure to wire things up properly in the `gulpconfig.js` file if you swap in your own stuff. I've already integrated [timeago](http://timeago.yarp.com/), a simple script to transform timestamps into something more human-readable, but this is easily removed if you don't like it (which is sort of the point of having such scaffolding, so you can easily swap stuff in and out).
52
+
It seems there is a need for what I'd call a *minimum viable theme*: a truly bare bones WordPress starter theme featuring only the essentials to get up and running, something that you can assess at a glance. For the purposes of this project I have created such a theme, tentatively named `voidx`. It isn't pretty and isn't up to [WordPress standards](https://wordpress.org/plugins/theme-check/) but it works well enough to show off some of the power of this workflow. Feel free to play with or discard it as you wish. All files under `src` can be replaced by your own files, you just have to be sure to wire things up properly in the `gulpconfig.js` file if you swap in your own stuff. Several scripts have already been integrated to show you how it's done, but these are easily if you don't like 'em (which is sort of the point of having such scaffolding, so you can easily swap stuff in and out).
52
53
53
54
There are two components worth a closer look:
54
55
@@ -84,7 +85,7 @@ Configuration is handled by a single file: `gulpconfig.js`. If you leave the dir
84
85
*[BrowserSync](http://www.browsersync.io/) settings: if you are developing on a local web server you will want to enter the URL into `browsersync.proxy` and then change `watch.watcher` to `browsersync` to take it for a test drive. You'll know it's working when you run `gulp` and a new browser opens with a live copy of your web site. Make changes to any of the Sass files and they should be shown on the page almost immediately. Of course, BrowserSync really shines when you connect a mobile device to your development server, but for that you're on your own ;)
85
86
* Script settings: draw your attention to `scripts.bundles` and `scripts.chunks`. This feature is essentially a poor man's [Browserify](http://browserify.org/) or [Webpack](https://webpack.github.io/). By defining different "chunks" (script files that combine to provide a particular feature) and "bundles" (chunks that combine to provide feature sets) you can generate an assortment of files that can be efficiently and intelligently loaded through your WordPress theme. This approach has its limitations, of course, particularly when dependencies are shared between scripts, but it should be of use to many WordPress theme developers.
86
87
87
-
Interested in adding new Gulp plugins to your build system? A full tutorial is out of scope for this project but it really shouldn't be all that hard to figure out. In brief, install a plugin with `npm install [package] --save-dev`, require it in a suitable task file, add something to the configuration file if needed, and drop it into the pipeline somewhere. Some types of plugin are particularly easy to add, for instance anything listed on the [postcss.parts](http://postcss.parts/) web site (install, require, and add to the `processor` variable in `/gulpfile.js/tasks/styles.js`).
88
+
Interested in adding new Gulp plugins to your build system? A full tutorial is out of scope for this project but it really shouldn't be all that hard to figure out. In brief, install a plugin with `npm install [package] --save-dev`, require it in a suitable task file, add something to the configuration file if needed, and drop it into the pipeline somewhere. Some types of plugin are particularly easy to add, for instance anything listed on the [postcss.parts](http://postcss.parts/) web site once you have [gulp-postcss](https://github.com/postcss/gulp-postcss) installed and configured in `/gulpfile.js/tasks/styles.js`.
88
89
89
90
90
91
@@ -111,13 +112,12 @@ A few handy tips from the [Bower documentation](https://bower.io):
111
112
112
113
## WORKING WITH SASS
113
114
114
-
* This package now supports either [gulp-ruby-sass](https://github.com/sindresorhus/gulp-ruby-sass/) (which requires [the original Ruby implementation of Sass](https://github.com/sass/sass)) or [gulp-sass](https://www.npmjs.org/package/gulp-sass) (based on the newer, experimental, and faster [libsass](https://github.com/sass/libsass), now active by default). Switch `styles.compiler` in the configuration file as needed! For reference: [Sass compatibility table](https://sass-compatibility.github.io/).
115
+
* This project now supports either [gulp-ruby-sass](https://github.com/sindresorhus/gulp-ruby-sass/) (which requires [the original Ruby implementation of Sass](https://github.com/sass/sass)) or [gulp-sass](https://www.npmjs.org/package/gulp-sass) (based on the newer and faster [libsass](https://github.com/sass/libsass), now active by default). Switch `styles.compiler` in the configuration file as needed! For reference: [Sass compatibility table](https://sass-compatibility.github.io/).
115
116
*[Sass](http://sass-lang.com/) files can be found in `/src/scss`. Gulp will not process Sass partials beginning with `_`; these need to be explicitly imported (see `style.scss` for an example). On the other hand, if you want to output any other CSS files just drop the underscore *e.g.*`editor-style.scss`.
117
+
* Stylesheets are post-processed with [cssnano](http://cssnano.co/), a [PostCSS](https://github.com/postcss/postcss) plugin with [Autoprefixer](https://github.com/ai/autoprefixer) baked in, eliminating the need for vendor prefixes.
118
+
*[Sourcemaps](http://www.html5rocks.com/en/tutorials/developertools/sourcemaps/) are generated by [gulp-sourcemaps](https://github.com/floridoo/gulp-sourcemaps) to make debugging stylesheets a snap. Note: all generated CSS is production-ready (*e.g.* minified and prefixed); sourcemaps only appear in the `build` directory.
116
119
* Packages installed with Bower or npm are in the path by default so you can `@import` Sass files directly, as seen in `style.scss`.
117
-
* The `build` folder is provisioned with regular versions of all stylesheets but `dist` only contains minified versions for production.
118
-
* This starter kit ships with [Normalize.css](https://necolas.github.io/normalize.css/) (imported into the `src/scss` directory using `gulp setup`; you might also like to explore the use of [normalize-scss](https://github.com/JohnAlbin/normalize-scss) for your project).
119
-
* Compass is *not* included as [Autoprefixer](https://github.com/ai/autoprefixer), a [PostCSS](https://github.com/postcss/postcss) plugin, eliminates the need for vendor prefixing (which is what most Sass frameworks focus on these days). Instead I have included [Scut](https://davidtheclark.github.io/scut/), a minimalist library of useful Sass mixins and functions for the post-vendor prefixing era. This is easily removed if you're not interested in using it.
120
-
*[Sourcemaps](http://www.html5rocks.com/en/tutorials/developertools/sourcemaps/?redirect_from_locale=tw) are generated by [gulp-sourcemaps](https://github.com/floridoo/gulp-sourcemaps) to make debugging stylesheets a snap.
120
+
* This starter kit ships with [Normalize.css](https://necolas.github.io/normalize.css/) (imported into the `src/scss` directory using `gulp setup`; you might also like to explore the use of [normalize-scss](https://github.com/JohnAlbin/normalize-scss) for your project) and [Scut](https://davidtheclark.github.io/scut/), a minimalist library of useful Sass mixins and functions for the post-vendor prefixing era. Both of these are easy to remove if you're not interested in them.
121
121
122
122
123
123
@@ -149,7 +149,7 @@ Let's say you run across a cool project like [Headroom.js](http://wicky.nillia.m
149
149
* Create an additional script at `src/js/headroom.js` to invoke the main script:
150
150
151
151
```language-javascript
152
-
// Invoke Headroom.js
152
+
// Invoke Headroom.js; the outer function is is an IIFE, the inner one is a shortcut to document.ready
// Script variables specific to WP AJAX Page Loader (these are separate from the main theme script variables due to the naming requirement; the object must be `PG8Data`)
61
-
// This appears and NOT in the conditional block (above) because these variables will be attached to the main script handle (which may be modified after the page loader block)
60
+
// Script variables specific to WP AJAX Page Loader (these are separate from the main theme script variables due to the naming requirement; the object *must* be `PG8Data`)
61
+
// This appears here and NOT in the conditional block (above) because these variables will be attached to the main script handle (which may be modified after the page loader block)
0 commit comments