Craft Setup

Using Blendid with CraftCMS:

An aggregate of all the information from the repo about using Blendid with Craft. To init a Craft CMS project with Blendid, run this command at the root of your project:

yarn run blendid -- init-craft

This task will do a few things:

• create a config directory with path-config.json and task-config.js
• add the Gulp Rev plugin to the craft/plugins directory
• create a src directory with the expected asset folders (fonts, javascripts, stylesheets, etc)
• blendid is already configured to compile everything to /public/assets and will not touch files outside of that directory
• blendid will watch the craft/templates folder for any changes

You will still need to:

• set your local development URL in task-config.js
• enable the Gulp Rev plugin in the Craft Admin
• (optional) set your destination directory in the Gulp Rev plugin settings, should you chose to change it in Blendid's path-config.json
• Use the gulp_rev Twig filter to convert file paths to versioned file paths

After the previous steps, your folder structure should look like this:

CraftSite
    |-- config
    |   |-- path-config.json
    |   |-- task-config.js
    |-- craft
    |   |-- app
    |   |-- config
    |   |-- plugins
    |       |-- gulprev
    |   |-- storage
    |   |-- templates
    |-- public (after compiling assets)
    |   |-- assets
    |   |   |-- fonts
    |   |   |-- images (icons end up here too)
    |   |   |-- javascripts
    |   |   |-- stylesheets
    |   |-- Other Craft Files We Don't Want To Clobber...
    |-- src
        |-- fonts
        |-- icons
        |-- images
        |-- javascripts
        |-- stylesheets

Blendid Customization Considerations:

Upon running yarn run blendid Blendid will clobber the contents of the destination directory set in the dest object in your config/path-config.json file, which by default is set to the public/assets/ directory. Since Craft uses public to store some files, it is not advised that you change your destination directory to /public, so that those Craft-specific files do not get, well, clobbered.

This also prevents issues with local Craft asset sources which typically live in the /public directory as well.

Removed Tasks

By default, Blendid will disable the html task and the static task when using init-craft.

Since Craft is handling our HTML templating and Blendid is configured to watch /craft/templates, the html task is completely unnecessary.

The static task has been removed as well, since files in the root of /public are now preserved. Feel free to post an issue for the return of this task should you hit any issues without it.

Existing Tasks

Javascripts:

By default Blendid won't output your compiled JavaScript files to the destination folder when running yarn run blendid, but they are compiled and live-updated via BrowserSync + WebpackDevMiddleware + WebpackHotMiddleware. So don't be alarmed if those files are not present when developing locally. Try out yarn run blendid -- build to see your production-ready compiled files, including JavaScript.

If things aren't building correctly, make sure you included the space between the -- and build!

By default, this will compile to /public/assets/javascripts. You can update this path in path-config.json.

Stylesheets

By default, this will compile your .sass and .scss files to /public/assets/stylesheets. You can update this path in path-config.json.

Images

By default, this will move any image files in src/images to /public/assets/images and will version those files. You can update this path in path-config.json.

Craft will manage most of your images which are used as content, so images processed by Blendid are typically logos or images which are baked into the design of the site you are building.

Fonts

By default, this will move any font files in src/fonts to /public/assets/fonts and will version those files. You can update this path in path-config.json.

If you're using a font hosting service or system fonts and don't need this task, you can always remove it by following these steps:

• delete the fonts object in path-config.json
• set the fonts object in task-config.json to false
• remove the /src/fonts directory

Icons:

By default, this will take all svg files in src/icons (which should each be a single icon), compile them into one svg file, and move that file to /public/assets/images with a versioned file name. You can update this path in path-config.json.

If using this task, it is recommended that you read the documentation on the svgSprite task for both set-up and usage.

If you're using your own custom method of including icons, you can always remove the icons task by following these steps:

• delete the icons object in path-config.json
• set the icons object in task-config.json to false
• remove the /src/icons directory

Asset revisions(from the Readme):

Use the Gulp Rev Craft Plugin to include the proper gulp-revisioned version of an asset in your Twig templates.

Manually Installing the Plugin

If you used the yarn run blendid -- init-craft command, then the plugin should already exist in /craft/plugins and you can skip the first step below!

To install the plugin:

• Copy and paste the node_modules/blendid/extras/craft/gulprev directory and its contents into /craft/plugins
• Enable the plugin in your Craft admin panel in Settings => Plugins
• (optional) Use the plugin's settings to change your destination directory, if not /public/assets

Usage:

<link rel="stylesheet" href="{{ 'assets/stylesheets/app.css' | gulp_rev }}">

The output of the Twig filter defaults to the given string/path unless rev-manifest.json exists. When rev-manifest.json exists, then the string is replaced with the revisioned asset path.

Important Notes:

• By default, the plugin looks for your rev-manifest.json file in /public/assets/rev-manifest.json.
• To customize the path to your rev-manifest.json, go to /admin/settings/plugins/gulprev in the Craft Admin and change the setting for the file path.
• Make sure rev-manifest.json does not exist when running the default blendid task (when files are not versioned). This will cause an error since the versioned file will not exist.

If you prefer to work without revisions you can disable it by changing the production config object in task-config.js to rev: false and you can skip using the Gulp Rev plugin.