We’re not just about looks. We take great care in the design of our code struc­ture and nam­ing conventions.

This sec­tion has all the nuts n’ bolts for get­ting the site set­up on your sys­tem, where to find things, and how stick with our code standards.

Set­up


Run­ning locally

Loud­er Than Ten is built with Craft CMS, which requires a basic PHP & MySQL serv­er. We use Mamp Pro to host local­ly with lit­tle fuss, but you can use any PHP/​MySQL set­up as long as it meets Craft’s require­ments.

If you want to make any code updates, you’ll want to set­up the full site on your local machine:

Front-end set­up

If you want to update the CSS or Javascript, you’re also going to need to set­up a few front-end libraries.

Project struc­ture


Here’s how the Loud­er Than Ten site is organized:

/​public_​html

This is where all com­piled sta­t­ic assets live. Find images and font files here, as well as all com­piled and mini­fied CSS and JavaScript. Don’t edit these CSS and JS files. Your changes will be over­writ­ten by the preprocessor.

/​source

This con­tains all of the pre-com­piled Sass and Javascript files. This is where you will write your CSS and JavaScript.

/​craft

The Craft CMS folder.

/​craft/​templates

Where the Twig-based Craft tem­plates reside. These are the tem­plates that make the website.

/​craft/​plugins

Where all Craft plu­g­ins get installed.

Ver­sion control


We use Git to man­age our ver­sion con­trol. It keeps track of all our code changes and stores them in a cen­tral Github repository.

We make heavy use of branch­es and ver­sion num­bers to help track of progress and allow fea­ture devel­op­ment with­out inter­fer­ing with our Mas­ter pro­duc­tion branch.

Here’s a quick break­down of our ver­sion­ing and branch­ing philosophy:

Branch­ing

We loose­ly fol­low Vin­cent Driessen’s approach to Git ver­sion­ing. Here’s our quick n’ dirty overview:

mas­ter

The mas­ter branch should always be bug free (yeah right) and ready to deploy to the pro­duc­tion serv­er. We nev­er make direct changes in this branch and only merge fea­tures and updates into it after they’ve been thor­ough­ly tested.

dev

The dev branch is where we merge our fea­tures into for test­ing and pre­view­ing and gets deployed to our dev serv­er. No work should ever be done on this branch.

fea­ture-branch­es

Fea­ture branch­es are copied from the dev branch. These should be named after the fea­ture we are devel­op­ing. This is where the work gets done. Com­mit often, push to ori­gin, and reg­u­lar­ly pull updates from the dev branch to ensure you’re work­ing with the lat­est code. When a fea­ture is fin­ished and ready for test­ing, we merge it back into dev. These should be named low­er­case with hyphens sep­a­rat­ing the words and pre­fixed with feature/​.

hot­fix­es

These are quick bug fix­es and updates that need to be imme­di­ate­ly pushed live. A hot fix branch name should be pre­fixed with hotfix/​ and copied direct­ly from mas­ter. Once the change is com­plete, it should be merged back into mas­ter as well as dev to make sure the entire project gets the fix.

Ver­sion numbers

We loose­ly fol­low the Seman­tic Ver­sion­ing approach to our releases.

Major ver­sion (x.)

In our case, the major ver­sion gets changed with major site over­hauls or redesigns.

Minor ver­sion (1.x)

We reg­u­lar­ly make a list of all the fea­tures we want to imple­ment in the next release. We bump this when these fea­tures are com­plete, imple­ment­ed, and merged into mas­ter.

Patch ver­sion (1.1.x)

We update this every­time we push some­thing to mas­ter that isn’t part of the planned fea­ture release. This might include bug fix­es, or unplanned changes or adjust­ments (aka hotfixes).

Markup


We use stan­dard HTML5 for markup with a sim­pli­fied ver­sion of BEM syn­tax to name class­es. This sets an easy stan­dard for oth­ers to adopt and keeps the library tight, mod­u­lar, and free of speci­fici­ty issues.

Here’s the basic syntax:

.block {} /* A component or module */
.block__element {} /* A descendent of that module */
.block--modifier {} /* A modified or alternate version of the module */

Read more about BEM syn­tax.

CSS


All of the styles are writ­ten using Sass. All source files can be found in /source/scss/.

We use a high­ly mod­u­lar approach when author­ing our SASS and break all of our pieces into files. This helps keep things orga­nized and easy to modify.

Every ele­ment group, com­po­nent, and mod­ule should have it’s own file where we define every­thing except colour.

Sass fold­ers

/source/scss/ This fold­er con­tains all of the SCSS styles in the project. The guide and Craft tem­plates both share the same CSS. What this means is that when­ev­er you make changes to your styles, they will be reflect­ed in the man­u­al as well as the site.

We’ve struc­tured our scss fold­er based on Har­ry Robert’s ITC­SS method­ol­o­gy.

app.scss

This gen­er­ates the main CSS file. It has two includes:

_​includes – base.scss

Imports the base scss vari­ables and utilites that every SCSS file requires.

1_​settings/​_​includes

Pulls in all the ele­ments, com­po­nents, and mod­ules you want to include in your projects. 

1_​settings/​_​includes – async

Pulls in only the crit­i­cal ele­ments, com­po­nents, and mod­ules you want to include in your projects. We sep­a­rate this from the above include so you can choose asyn­cro­nous­ly load CSS that appears out­side the view­port for quick­er load­ing. More info on the tech­nique at Fil­a­ment Group.

/​app/​_​scss/​1_​settings/​Con­tains the project vari­ables, font includes and a few oth­er things that set the stage.

_variables.scss Set most glob­al vari­ables in here. You can set things like base typo­graph­ic set­tings, default cor­ner radius, break­point widths, and grid units. _colors.scss We keep our colour vari­ables sep­a­rate so we can eas­i­ly experiement with mul­ti­ple colour schemes. _​includes – base.scss Imports the base scss vari­ables and utilites that every SCSS file requires. _includes.scss Use this to include or exclude the sec­tions you want in your project. We made every­thing mod­u­lar, so you can use as much or as lit­tle as you like. _livewires.scss Blanks out text inside of any ele­ment with a .con­tent class in your HTML. Include this when pre­sent­ing wire­frames to clients or your team to focus their atten­tion on lay­out and flow, rather than tex­tu­al con­tent. But hark the bro­ken record: get your con­tent in before you get into design. _font-faces.scss Add any font or icon @font-face includes to this file. /​app/​_​scss/​2_​tools/​Con­tains our handy log­ic-based SCSS tools like Mix­ins and Functions.

_mixins.scss & _functions.scss These include pow­er­ful enhace­ments to help save time. Have a browse to see what’s avail­able and how they work. /​app/​_​scss/​3_​generic/​Con­tains third par­ty styles like nor­mal­ize as well as any plu­g­in css that needs to be overridden.

/​app/​_​scss/​4_​elements/​Naked default HTML ele­ments are styled here. Avoid styling with clases. e.g. para­graphs, head­ings, form fields

/​app/​_​scss/​5_​components/​The reusable pieces that con­sist of groups of ele­ments. Start styling with class­es here. e.g. call­outs, pag­i­na­tion, code blocks

/​app/​_​scss/​6_​modules/​Major chunks that make up the main sec­tions of a tem­plate. They often con­tain com­po­nents and glob­al ele­ments, and are often used once per page. e.g. head­ers, foot­ers, lay­out modules

/​app/​_​scss/​7_​theme/​This con­tains all colour-relat­ed styles. We’ve kept all the col­or assign­ments sep­a­rate from struc­tur­al styles to make them­ing eas­i­er, faster, and less prone to errors. Optional.

/​app/​_​scss/​8_​pages/​Page-spe­cif­ic styles. We rec­om­mend keep­ing larg­er files in this sec­tion out of the main stylesheet and only call­ing them on their respec­tive pages.

/​app/​_​scss/​9_​overrides/​Any­thing that needs to sit at the bot­tom of the CSS. Put your impor­tant over­rides in here.