README.md

Theme Readme

Build 🛠

Install the following node modules (npm) for compiling sass and minifing Javascript.

1. Install node modules globally: npm install -g gulp-cli

2. Install node modules in the same directory as this readme file.

yarn add autoprefixer browser-sync gulp gulp-sass gulp-postcss gulp-sourcemaps gulp-uglify postcss sass yarn-upgrade-all --dev

3. gulp-local.env file:

   • Duplicate gulp-local.env.sample.js file and rename it gulp-local.env.js.
   • Change vaules in file as needed.

4. Run script: gulp or gulp watch.

Linting 🧼

We'll also be linting our sass and Javascript in order to produce well written and consistent code.

1. Install node modules in the same directory as this readme file.

yarn add stylelint stylelint-config-sass-guidelines stylelint-config-standard standard --dev

Required lint files (should be added during initial theme setup):

• .eslintrc.json
• .stylelint.json
• .stylelintignore

To do a global lint on the SCSS files run: npx stylelint "scss/**/*.scss". To fix found errors add the --fix flag.

Sublime: install the following packages using package control:

• SublimeLinter
• SublimeLinter-contrib-standard
• SublimeLinter-eslint
• SublimeLinter-stylelint

VS Code: install the following extensions:

• ESLint
• stylelint

Workspace setting should be located at the root of this project's repo: /.vscode/settings.json

{
  "eslint.workingDirectories": [
    "htdocs/themes/THEMENAME"
  ],
  "stylelint.packageManager": "yarn",
  "stylelint.configBasedir": "htdocs/themes/THEMENAME",
  "stylelint.configFile": "htdocs/themes/THEMENAME/.stylelintrc.json",
  "stylelint.snippet": [
    "sass",
    "scss"
  ],
  "stylelint.validate": [
    "sass",
    "scss"
  ]
}

Fragment

// Browsersync notify
#__bs_notify__ {
  /* Move notification to bottom-left */
  color: $white !important;
  font-size: rem(15) !important;
  font-weight: 500;
  text-shadow: 0 -1px 0 $black;
  border-top-right-radius: 8px !important;
  border-bottom-left-radius: 0 !important;
  background-color: rgba($black, 0.8) !important;
  box-shadow:
    inset 0 1px 0 0 rgba($white, 0.3),
    inset -1px 0 0 0 rgba($white, 0.3),
    0 -1px 0 0 rgba($black, 0.75),
    1px 0 0 0 rgba($black, 0.75);
  top: auto !important;
  right: auto !important;
  bottom: 0 !important;
  left: 0 !important;
  padding: 20px 25px !important;
  backdrop-filter: blur(3px);
}

gitignore

node_modules
gulp-local.env.js

gulp-local.env.sample.js

/**
 * browsersync proxy env settings
 * https://www.browsersync.io/docs/options
 *
 * Duplicate file and rename it 'gulp-local.env.js'.
 * Change values below as needed.
 */

module.exports = {
  port: 3110,
  url: 'http://local.example.test',
  open: false,
  browser: 'google chrome',
  notify: true,
  ghostMode: false
}

gulpfile (multipaths).js

'use strict'

// Load modules
const gulp = require('gulp')
const autoPrefixer = require('gulp-autoprefixer')
const browserSync = require('browser-sync').create()
const notify = require('gulp-notify')
const sass = require('gulp-sass')
const sourceMaps = require('gulp-sourcemaps')
const uglify = require('gulp-uglify')

// paths
const path = {
  bs: {
    port: 3113,
    uiport: 3013,
    url: 'local-wp.cednc.org'
  },
  styles: {
    watch: '../scss/**/*.scss'
  },
  scripts: {
    src: [
      '../js/navigation.js',
      '../js/script.js'
    ],
    dest: '../js/min/',
    watch: '../js/*.js'
  }
}

const multiPaths = {
  public: {
    styles: {
      src: '../scss/style.scss',
      dest: '../'
    }
  },
  admin: {
    styles: {
      src: '../scss/style-admin.scss',
      dest: '../'
    }
  },
  acf: {
    styles: {
      src: '../scss/acf/style.scss',
      dest: '../template-parts/blocks/css'
    }
  }
}

// browserSync watch
function browsersync () {
  browserSync.init({
    port: path.bs.port,
    proxy: path.bs.url,
    reloadDebounce: 1000,
    open: false,
    notify: false,
    ghostMode: false,
    ui: {
      port: path.bs.uiport
    }
  })
}

function reload (done) {
  browserSync.reload()
  done()
}

// Scss : expanded, nested, compact or compressed
function styles (done) {
  Object.keys(multiPaths).forEach(val => { // <- NEW
    gulp.src(multiPaths[val].styles.src) // <- NEW
      .pipe(sourceMaps.init())
      .pipe(sass({
        outputStyle: 'compact'
      }).on('error', function (err) {
        console.log(err.toString())
        this.emit('end')
      }))
      .pipe(autoPrefixer({
        overrideBrowserslist: ['last 2 versions']
      }))
      .pipe(sourceMaps.write('./'))
      .pipe(gulp.dest(multiPaths[val].styles.dest)) // <- NEW
      .pipe(browserSync.stream())
      .pipe(notify({ message: 'Scss compiled', onLast: true }))
  }) // <- NEW

  done()
}

// Minify JS
function scripts (done) {
  gulp.src(path.scripts.src)
    // .pipe(sourceMaps.init())
    .pipe(uglify()).on('error', function (err) {
      console.log(err.toString())
      this.emit('end')
    })
    // .pipe(sourceMaps.write('./'))
    .pipe(gulp.dest(path.scripts.dest))
    .pipe(browserSync.stream())
    .pipe(notify({ message: 'JS uglified', onLast: true }))

  done()
}

function watchfiles () {
  gulp.watch(path.styles.watch, gulp.series(styles))
  gulp.watch(path.scripts.watch, gulp.series(scripts, reload))
}

gulp.task('styles', styles)
gulp.task('scripts', scripts)
gulp.task('default', gulp.parallel(styles, scripts))
gulp.task('watch', gulp.parallel(browsersync, watchfiles))

gulpfile.js

// Load modules
const gulp = require('gulp')
const autoprefixer = require('autoprefixer')
const browserSync = require('browser-sync').create()
const postcss = require('gulp-postcss')
const sass = require('gulp-sass')(require('sass'))
const sourceMaps = require('gulp-sourcemaps')
const uglify = require('gulp-uglify')
const localenv = require('./gulp-local.env')

// paths
const path = {
  styles: {
    src: ['./path/to/files/assets/scss/style.scss'],
    dest: './path/to/css/',
    watch: './path/to/files/assets/scss/**/*.scss'
  },
  scripts: {
    src: ['./path/to/files/assets/js/main.js'],
    dest: './path/to/files/assets/js/min/',
    watch: './path/to/files/assets/js/*.js'
  }
}

// browserSync notify messages
const bsMessage = {
  sassComplete: 'Sass compiled successfully 🎉',
  sassError: 'Sass error! <small>⚠️</small>',
  jsComplete: 'JS uglified successfully 🎉 ...reloading',
  jsError: 'Javascript error! <small>⚠️</small>',
  successTime: 3000,
  errorTime: 5000
}

// browserSync watch
function browsersync () {
  browserSync.init({
    port: localenv.port,
    proxy: localenv.url,
    open: localenv.open,
    browser: localenv.browser,
    notify: localenv.notify,
    ghostMode: localenv.ghostMode,
    ui: false
  })
}

// Scss : expanded, compressed
function styles (done) {
  let isSuccess = true
  gulp.src(path.styles.src)
    .pipe(sourceMaps.init())
    .pipe(sass({
      outputStyle: 'expanded'
    }).on('error', function (err) {
      console.log(err.toString())
      browserSync.notify(bsMessage.sassError, bsMessage.errorTime)
      isSuccess = false 
      this.emit('end')
    }))
    .pipe(postcss([autoprefixer()]))
    .pipe(sourceMaps.write('./'))
    .pipe(gulp.dest(path.styles.dest))
    .on('end', function () {
      if (isSuccess) {
        browserSync.notify(bsMessage.sassComplete, bsMessage.successTime)
      }
    })
    .pipe(browserSync.stream())

  done()
}

// Minify JS
function scripts (done) {
  let isSuccess = true
  gulp.src(path.scripts.src)
    .pipe(sourceMaps.init())
    .pipe(uglify())
    .on('error', function (err) {
      console.log(err.toString())
      browserSync.notify(bsMessage.jsError, bsMessage.errorTime)
      isSuccess = false 
      this.emit('end')
    })
    .pipe(sourceMaps.write('./'))
    .pipe(gulp.dest(path.scripts.dest))
    .on('end', function () {
      if (isSuccess) {
        browserSync.notify(bsMessage.jsComplete, bsMessage.successTime)
        browserSync.reload()
      }
    })
    .pipe(browserSync.stream())

  done()
}

// watch files
function watchfiles () {
  gulp.watch(path.styles.watch, gulp.series(styles))
  gulp.watch(path.scripts.watch, gulp.series(scripts))
}

gulp.task('styles', styles)
gulp.task('scripts', scripts)
gulp.task('default', gulp.parallel(styles, scripts))
gulp.task('watch', gulp.parallel(browsersync, watchfiles))

package.json

{
  "name": "project-name",
  "version": "0.1.0",
  "description": "Project description goes here...",
  "repository": {
    "type": "git",
    "url": "https://github.com/repo.git"
  },
  "author": "DesignHammer, LLC",
  "license": "GPL-2.0 AND MIT",
  "homepage": "https://designhammer.com",
  "scripts": {
    "styles": "gulp styles",
    "scripts": "gulp scripts",
    "watch": "gulp watch"
  },
  "browserslist": [
    "> 0.2%",
    "last 2 version",
    "Firefox ESR",
    "not dead"
  ]
}