Themes for the Better web site and the iOS app (as well as styles/templates common to both).

Better Themes

These are the themes used by the Better Builder while generating the data for the site and the iPhone/iPad app.

Files in the /common folder are used as a base when building for either environment. The /site and /app folders have specialised styles and templates that extend and override the ones in the /common folder.


Pages are created based on the contents of page.html, which might include other templates as partials.


All files in the /images, /styles, /scripts, and /fonts folders are copied over to the same folders in the root directory of the generated data and will be accessible via those same URL fragments from the local server.

Testing locally.

Better Builder will automatically pick up your changes as you save and rebuild your local data.

Saving your changes by pushing to production

If you have commit rights, you can push to production with:


Or, to manually do what the save convenience script does:

git push live master


If you have commit rights to the content repository, just run the deployment script:


This will create a tag (you will have to enter a tag mesage when prompted, describing the release) and push it to production. Please make sure that you have already committed your changes and pushed them to production either via git push live master or by running the ./save script, which does the same thing.


TL;DR: Develop and test locally in your own branch (named with the URL of the issue you are addressing; see below for details), or your own fork, and create a merge request once you’re ready to submit your changes.

A. Search for existing issues & discuss your proposed changes with the community

  1. Check the issues first to make sure that other people are not already working on similar functionality so you don’t duplicate work. You might be able to help out with an existing initiative.
  2. Open a new issue and discuss your proposed changes before commiting too much work into it. The community might have valuable input.

B. Develop locally

  1. Make sure Better Builder is installed and running locally. The Better Builder installation will create a fully offline development and testing environment for you. (You can find your local Better installation at ~/ on your development machine.)
  2. Create a local branch for your changes based on the URL of the issue ticket you opened (e.g., `git checkout -b ""). Branches not linked to issues will not be accepted for merge requests.
  3. In your branch, make your changes and update the theme. (You can find the themes folder in your local Better installation at ~/ on your development machine.)

C. Test locally

  1. Merge your changes into master
  2. Push to the local development repository: git push origin master (Better Builder — see B1, above — will automatically pick up your changes and regenerate the content.)
  3. Test out the result by running the Better iOS app in the iOS Simulator for the app theme and in the browser at http://localhost:3000 for the site theme.
  4. If you’re not happy with the changes, go back to B.

D. Submit your changes

Once you’re happy with your changes, submit them to the project. Make sure your commit message closes the issue you opened (e.g., git commit -am "Summary of changes. Closes #<issue-number>.").

If you have commit rights:
1. `./save` (or run `git push live master` which does the same thing)
2. `./deploy` to create a new tag and push it to production, thereby triggering a rebuild of the Better data.
If you do not have commit rights:
1. `git push live master` to push to your own fork
2. Submit a merge request

Once your changes have been approved by someone with deployment privileges, they will be included in the next release.

Thank you in advance for your effort and for contributing to the community.


News items

When grouping multiple updates in one major update, make a list within the list item and title with a group-name class.

<ul class='posts-list'>
    <li class='h-entry major-update'>
        <time class='dt-published' datetime='2016-07-07'>7th Jul, 2016</time>
        <h2 class='group-name'>Group Name</h2>
                <h3 class='p-name'>Update Title #1</h3>
                <p class='p-summary'>Summary text.</li>
                <h3 class='p-name'>Update Title #2</h3>
                <p class='p-summary'>Summary text.</p>
                <h3 class='p-name'>Update Title #3</h3>
                <p class='p-summary'>Summary text.</p>

CSS formatting

 Tabs not spaces! (except inside comments, for legibility)
 One empty line between each group of rules

    on their own line: like this;

    @media queries are indented below their matching element
            like: this;

comma, separated, selectors, on, one, line
    like: this;

    background: #000;
    color: #fff;
    display: block;

CSS comments

 *                      Sections are styled like this                       *

/* ↓ comments on CSS rules are like this, on a separate line, above the rule itself */

 comments on groups of CSS rules (and long comments) are like this, with the start and end on their own lines

 *      Note        *

 A special note about the CSS in this section is styled like this, so it doesn’t stand out as much as the section heading comments, and we don’t have to worry about formatting each line.