Install the world famous Gulp build tool
npm install gulp -g
Install all of the dependencies for Gulp, Postcss and BrowserSync
Your browser should open a new page at http://localhost:3000 containing links to the page views. These views will update in the browser automatically as you edit with BrowserSync. Gulp must be running at all times in order to build and display the html files.
More information on BrowserSync can be found on their website.
A minifies version of Magma has been added to the /dist/css folder along with a local version of the Magma Font. These are maintained statically in the /dist folder and are not subject to the Gulp build process.
Magma's color variables are exported directly into the Gulp (gulpfile.js) build process via ./variables.js
var cssVariables = require('./variables.js');
The repo is divided into two section:
- /dist, where the distribution lives
- /src, where all of the source code lives.
As you should not edit the distribution, all work should be done in /src.
The CSS for the site can be divided into two sections: /layout and /content. The layout css consists of a number of files whose CSS is used in the presentation of the sections within the layout.html file. These files are mapped directly to the html files found in src/html/layout. The layout CSS is used in all of the files.
The content.css file includes all of the CSS used in the presentation of the src/html/content files. Together with the src/css/layout CSS files, it is used to build the src/css/purchase-options.css which is the consolidated CSS file for the site.
All of these CSS files are watched by Gulp and are build using the 'build-css' task.
Like the CSS, the HTML can be divided into two main sections: /layout and /content. The layout folder consists of all of the files required to build the layout.html page. The /content folder consists of all of the HTML files required to generate the content of the pages along with a /components folder that contains all of smaller components needed to generate those views. The /components HTML pages are widely shared across the site.
The layout.html page is built by using the layout-src.html page and the HTML files from the /layout folder. This is accomplished by the 'build-layout' task in the Gulp file.
The index.html page consists of static links to all the views being generated for the site. It is generated by the 'build-index' task in the Gulp file.
The /content pages are generated by wrapping all of the HTML pages inside /content with layout.html. The content is inserted via gulp-wrap using the <%= contents %> tag along with the 'layout' task in the Gulp file. All of these files are then generated and make up the bulk of the /dist HTML pages.
All images are added to the src/images folder and are replicated into the dist/images folder by 'images' task in the Gulp file.
Gulp is a great tool and usually works very well but like everything it experiences some upsets from time to time. I have found the following tips to be helpful in the dev environment:
Keep all CSS local. If you're depending on CSS hosted on a CDN, this will slow BrowserSync down and allow for gaps in the build process. For this reason I have static versions of Magma and Magma Fonts in the dist/css folder.
Understand what's going on underneath the hood. The CSS build process can be complicated and uses a variety of Postcss plugins and libraries to make for easier/better/faster development. These packages are all listed at the top of the Gulp file and their corresponding repos can be found on NPM and Github along with documentation for their use.
Occasionally, Gulp will miss a watched file and it is necessary to save out another file to generate the build. This can be annoying and cumbersome if BrowserSync isn't updating the view fast enough.