asuh / sage-starter

The best starter theme with a modern front-end development workflow. Based on Sage, HTML5 Boilerplate, gulp, Bower, and Bootstrap.

Sage Starter

Sage Starter is a starter theme based on Roots Sage theme version 8.6, which references HTML5 Boilerplate, Gulp, and Bower that will help you make better websites.

• Homepage: https://github.com/asuh/sage-starter/
• Source: https://github.com/roots/sage
• Documentation: https://roots.io/sage/docs/
• Twitter: @asuh

Requirements

Prerequisite	How to check	How to install
Node.js >= 6.9.x	node -v	nodejs.org
gulp-cli >= 2.0.0	gulp -v	npm install -g gulp-cli
Bower >= 1.3.12	bower -v	npm install -g bower
Optional
PHP >= 7.x.x	php -v	php.net

PHP is optional, but use the latest PHP version that's available.

For more installation notes, refer to the Install gulp and Bower section in this document.

Features

• gulp build script that compiles both Sass and Less, checks for JavaScript errors, optimizes images, and concatenates and minifies files
• BrowserSync for keeping multiple browsers and devices synchronized while testing, along with injecting updated CSS and JS into your browser while you're developing
• Bower for front-end package management
• asset-builder for the JSON file based asset pipeline
• ARIA roles and microformats

Installation

Clone the git repo - git clone https://github.com/asuh/sage-starter.git and then rename the directory to the name of your theme or website.

Theme development

Sage Starter uses gulp as its build system and Bower to manage front-end packages.

Bower is outdated and not recommended since the mid-2010s, but will remain in this starter project for the time being.

Install gulp and Bower

Building this project requires node.js. For best results, update to the latest version of npm: npm i -g npm@latest. I personally recommend using NVM.

From the command line:

1. Install gulp-cli and Bower globally with npm i -g gulp bower
2. Navigate to the theme directory, then run npm i
3. Run bower install

You now have all the necessary dependencies to run the build process.

Available gulp commands

• gulp — Compile and optimize the files in your assets directory
• gulp watch — Compile assets when file changes are made
• gulp --production — Compile assets for production (no source maps).

Using BrowserSync

To use BrowserSync during gulp watch you need to update devUrl at the bottom of assets/manifest.json to reflect your local development hostname.

For example, if your local development URL is http://project-name.test you would update the file to read:

...
  "config": {
    "devUrl": "http://project-name.test"
  }
...

If your local development URL looks like http://localhost:8888/project-name/ you would update the file to read:

...
  "config": {
    "devUrl": "http://localhost:8888/project-name/"
  }
...

SVG support

Sage Starter has built-in SVG support! The preferred method for using SVG as implemented is an SVG sprite.

Usage

Make sure each SVG has an ID.

<svg xmlns="http://www.w3.org/2000/svg">
    <symbol id="twitter" viewBox="0 0 64 64">
        <title>Twitter</title>
        <path etc.../>
    </symbol>
</svg>

Save any SVG files you want to use into /assets/images/sprite and the build process will combine all of those images into /assets/images/sprite/sprite.svg.

To use in markup, apply the ID to an SVG's Use element.

<svg role="img" title="Twitter">
    <use xlink:href="map.svg#twitter"/>
</svg>

Check out SVG For Everybody for IE and <=Edge 12 support of SVG sprites.

Documentation

Sage theme's original documentation is available at https://docs.roots.io/sage/8.x/installation/. These instructions aren't consistent with Sage Starter but provide historical context for installation and running Gulp.

Contributing

Contributions are welcome and encouraged from everyone!

sage-starter's Issues

Dependabot needs permission to see asset-builder

Dependabot couldn't resolve your project's dependencies as it couldn't access asset-builder.

You can provide additional git credentials in your Dependabot dashboard by clicking into the account menu (in the top right) and selecting 'Config variables'. If you use a custom token for the host github.com make sure it has read access to this repo, too.

View the update logs.

Gulp Production

Running gulp --production generates the assets with random characters appended to the file, however, the links to those files are broken when running gulp --production watch. Do we have to manually included the assets.json file in our page, then how? Or is there something else I'm missing?

Dependabot needs permission to see asset-builder

Dependabot couldn't resolve your project's dependencies as it couldn't access asset-builder.

You can provide additional git credentials in your Dependabot dashboard by clicking into the account menu (in the top right) and selecting 'Config variables'. If you use a custom token for the host github.com make sure it has read access to this repo, too.

View the update logs.

Readme checks

You have a misspelling in your Readme.
/assets/images/sprites should be /assets/images/sprite otherwise it won't produce the sprite.

Your example needs updating, too.
<use xlink:href="map.svg#twitter"/> should be <use xlink:href="dist/images/sprite/sprite.svg#twitter"/>

Dependabot needs permission to see asset-builder

Dependabot couldn't resolve your project's dependencies as it couldn't access asset-builder.

You can provide additional git credentials in your Dependabot dashboard by clicking into the account menu (in the top right) and selecting 'Config variables'. If you use a custom token for the host github.com make sure it has read access to this repo, too.

View the update logs.

Bootstrap 4

Anyone who wants to make this work with Bootstrap will have to make some changes. You will need to downgrade gulp-sass version to 2.3.2 and add the bootstrap scss code manually to main.scss. Maybe BS4.0 dropped bower support.

PHP support?

Cannot GET /

Does this Gulp Boilerplate support PHP files? Or is gulp-connect-php and http-proxy required? I'm using MAMP Pro. Inside the gulpfile.js I specified .php wherever .html was present.

  "config": {
    "devUrl": "http://sage-starter.dev:8888"
  }