Стартовый проект с gulp

Команда	Результат
`npm i`	Установить зависимости
`npm start`	Запустить сборку, сервер и слежение за файлами
`npm start ЗАДАЧА`	Запустить задачу с названием ЗАДАЧА (список задач в `./gulpfile.js`)
`npm start check:favicons:update`	Проверка актуальности данных генератора favicon
`folder=src/img npm start img:opt`	Оптимизация изображений из папки `./src/img` (или любой другой)
`npm run build`	Сборка проекта без карт кода (сжатый вид, как результат работы)
`npm run deploy`	Сборка проекта без карт кода и отправка содержимого папки сборки на github-pages
`npm run test:style`	Проверка стилевой составляющей проекта stylelint
`npm start test:pug`	Проверка pug-файлов проекта форкнутым gulp-pug-lint

Предполагается, что все команды вы выполняете в bash (для OSX и Linux это самый обычный встроенный терминал, для Windows это, к примеру, Git Bash). В Windows установку пакетов (npm i) нужно выполять в терминале, запущенном от имени администратора.

Как начать новый проект c этим репозиторием

Клонировать этот репозиторий в новую папку (git clone https://github.com/nicothin/NTH-start-project.git new-project, см. шпаргалку) и зайти в неё (cd new-project).
Стереть историю разработки этого репозитория (rm -rf .git), инициировать новый (git init), создать удалённый репозиторий и привязать его (git remote add origin АДРЕС, см. шпаргалку).
Отредактировать README.md, package.json (название проекта, автор, лицензия, сторонние пакеты и пр.) и projectConfig.json (нужные на проекте блоки, сторонние пакеты). Удалив пакет из package.json, не забудьте убрать его из сборки в projectConfig.json.
Установить зависимости (npm i).
Запустить сервер разработки (npm start).

Если при вызове npm start ничего не происходит, смотрите ./projectConfig.json (вероятно, он содержит синтаксическую ошибку, проверить можно линтером).

Парадигма

Именование классов по БЭМ, разметка в pug и стилизация Sass. См. Как работать с CSS-препроцессорами и БЭМ
Каждый БЭМ-блок в своей папке внутри ./src/blocks/ (.scss, и .pug файлы обязательны).
Список использованных в проекте БЭМ-блоков и доп. файлов указан в ./projectConfig.json. Это главный конфигурационный файл проекта.
Есть глобальные файлы: стилевые (стили печати), js (по умолчанию пуст), шрифты, картинки.
Диспетчер подключения стилей ./src/scss/style.scss генерируется автоматически при старте любой gulp-задачи (на основе данных из ./projectConfig.json).
Список pug-примесей ./src/pug/mixins.pug генерируется автоматически при старте любой gulp-задачи (на основе данных из ./projectConfig.json).
Перед созданием коммита запускается проверка стилевых файлов, входящих в коммит и всех pug-файлов. При наличии ошибок коммит не происходит (ошибки будут выведены в терминал).
Есть механизм быстрого создания нового блока: node createBlock.js new-block (создаёт файлы, папки, прописывает блок в ./projectConfig.json).

Разметка

Используется pug. HTML никак не обрабатывается.

По умолчанию используются наследование шаблонов — все страницы (см. ./src/index.pug) являются расширениями шаблонов, в страницах описывается только содержимое «шапки», «подвала» и контентной области посредством блоков.

К.О. подсказывает, что если какие-то области («подвал»?) одинаковы на всех страницах, то их стоит писать в файле шаблона, а не в файлах страниц.

Стили

Файл-диспетчер подключений (./src/scss/style.scss) формируется автоматически на основании указанных в ./projectConfig.json блоков и доп. файлов. Писать в ./src/scss/style.scss что-либо руками бессмысленно: при старте автоматизации файл будет перезаписан.

Используемый постпроцессинг:

autoprefixer
css-mqpacker
postcss-import
postcss-inline-svg
gulp-cleancss (только в режиме сборки без карт кода)
postcss-object-fit-images (в паре с полифилом)
postcss-image-inliner

Для postcss-image-inliner указано ограничение на размер файла в 5 Кб, файлы ищутся в src/blocks/**/bg-img/. Чтобы избежать конфликтов имен, добавляйте к именам изображений префикс (имя блока), например: src/blocks/mega-block/bg-img/mega-block__avatar.png

Модульная сетка (flexbox)

По умолчанию в сборку берётся файл с примесями, возвращающими правила модульной сетки. Никаких селекторов в CSS не добавляет, нужно писать семантические селекторы и вызывать примеси, передавая им настройки сетки. Настройки по умолчанию вынесены в переменные ($grid-columns: 12; и $grid-gutter-width: 30px;).

Посмотреть примеры и попробовать вживую можно в этом примере с codepen.io.

Блоки

Каждый блок лежит в ./src/blocks/ в своей папке. Каждый блок — как минимум, папка и одноимённые scss- и pug-файл.

Возможное содержимое блока:

demo-block/               # Папка блока
  img/                    # Изображения, используемые блоком и обрабатываемые автоматикой сборки
  bg-img/                 # Изображения для использования в стилях (не обрабатываются автоматикой сборки)
  demo-block.pug          # **Обязательный**. Разметка (pug-примесь, отдающая разметку блока, описание API примеси)
  demo-block.scss         # **Обязательный**. Стилевой файл блока
  demo-block.js           # js-файл блока
  demo-block--mod.scss    # Отдельный стилевой файл БЭМ-модификатора блока
  demo-block--mod.js      # js-файл для отдельного БЭМ-модификатора блока
  readme.md               # Описание для документации, подсказки

Подключение блоков

Список используемых блоков и доп. файлов указан в ./projectConfig.json. Список файлов и папок, взятых в обработку можно увидеть в терминале, если раскомментировать строку console.log(lists); в gulpfile.js.

ВНИМАНИЕ! ./projectConfig.json — это JSON. Это строгий синтаксис, у последнего элемента в любом контексте не должно быть запятой в конце строки.

`blocks`

Объект с блоками, используемыми на проекте. Каждый блок — отдельная папка с файлами, по умолчанию лежат в ./src/blocks/.

Каждое подключение блока — массив, который можно оставить пустым или указать файлы элементов или модификаторов, если они написаны в виде отдельных файлов. В обоих случаях в обработку будут взяты одноименные стилевые файлы, pug-файл, js-файлы и картинки из папки img/ блока.

Пример, подключающий 3 блока:

"blocks": {
  "page": [],
  "page-header": [],
  "page-footer": []
}

`addCssBefore`

Массив с дополнительными стилевыми файлами, которые будут взяты в компиляцию ПЕРЕД стилевыми файлами блоков.

Пример, берущий в компиляцию переменные, примеси, функции и один дополнительный файл из папки зависимостей (он будет преобразован в css-импорт, который при постпроцессинге (postcss-import) будет заменен на содержимое файла).

"addCssBefore": [
  "./src/scss/variables.scss",
  "./src/scss/mixins.scss",
  "./src/scss/functions.scss",
  "../../node_modules/owl.carousel/dist/assets/owl.carousel.css"
],

`addCssAfter`

Массив с дополнительными стилевыми файлами, которые будут взяты в компиляцию ПОСЛЕ стилевых файлов блоков.

"addCssAfter": [
  "./src/scss/print.scss"
],

`singleCompiled`

Массив стилевых файлов, которые будут скомпилированы независимо.

Пример: указанный файл будет скомпилирован в папку сборки как blocks-library.css

"singleCompiled": [
  "./src/scss/blocks-library.scss"
],

`addJsBefore`

Массив js-файлов, которые будут взяты в обработку (конкатенация/сжатие) ПЕРЕД js-файлами блоков.

Пример, добавляющий в список обрабатываемых js-файлов несколько зависимостей:

"addJsBefore": [
  "./node_modules/jquery/dist/jquery.min.js",
  "./node_modules/jquery-migrate/dist/jquery-migrate.min.js",
  "./node_modules/nouislider/distribute/nouislider.js"
],

`addJsAfter`

Массив js-файлов, которые будут взяты в обработку (конкатенация/сжатие) ПОСЛЕ js-файлов блоков.

Пример, добавляющий в конец списка обрабатываемых js-файлов глобальный скрипт.

"addJsAfter": [
  "./src/js/global-script.js"
],

`addImages`

Массив дополнительных изображений, добавляемый ПЕРЕД массивом изображений из блоков (внимание: при совпадении имен файлов, файлы из блоков имеют более высокий приоритет и затрут файлы из этого массива).

"addImages": [
  "./src/img/*.{jpg,jpeg,gif,png,svg,ico}"
],

`copiedCss`

Массив css-файлов, которые копируются в папку сборки, подпапку css/

`copiedJs`

Массив js-файлов, которые копируются в папку сборки, подпапку js/

Пример `./projectConfig.json`

{
  "blocks": {
    "page-header": [],
    "page-footer": [
      "__extra-element",
      "--extra-modifier"
    ]
  },
  "addCssBefore": [
    "./src/scss/variables.scss"
  ],
  "addCssAfter": [
    "./src/scss/print.scss"
  ],
  "singleCompiled": [],
  "addJsBefore": [
    "./node_modules/jquery/dist/jquery.min.js",
    "./node_modules/jquery-migrate/dist/jquery-migrate.min.js"
  ],
  "addJsAfter": [
    "./src/js/global-script.js"
  ],
  "addImages": [
    "./src/img/*.{jpg,jpeg,gif,png,svg}"
  ],
  "copiedCss": [],
  "copiedJs": [],
  "dirs": {
    "srcPath": "./src/",
    "buildPath": "./build/",
    "blocksDirName": "blocks"
  }
}

В результате в обработку будут взяты (в указанной последовательности):

css:
 [ './src/scss/variables.scss',
   './src/blocks/page-header/page-header.scss',
   './src/blocks/page-footer/page-footer.scss',
   './src/blocks/page-footer/page-footer__extra-element.scss',
   './src/blocks/page-footer/page-footer--extra-modifier.scss',
   './src/scss/print.scss' ],
js:
 [ './node_modules/jquery/dist/jquery.min.js',
   './node_modules/jquery-migrate/dist/jquery-migrate.min.js',
   './src/blocks/page-header/page-header.js',
   './src/blocks/page-footer/page-footer.js',
   './src/blocks/page-footer/page-footer__extra-element.js',
   './src/blocks/page-footer/page-footer--extra-modifier.js',
   './src/js/global-script.js' ],
img:
 [ './src/img/*.{jpg,jpeg,gif,png,svg}',
   './src/blocks/page-header/img/*.{jpg,jpeg,gif,png,svg}',
   './src/blocks/page-footer/img/*.{jpg,jpeg,gif,png,svg}' ]
pug:
 [ './src/blocks/page-header/page-header.pug',
   './src/blocks/page-footer/page-footer.pug' ]

Удобное создание нового блока

Предусмотрена команда для быстрого создания файловой структуры нового блока. По умолчанию создаются: scss- и pug-файл, readme.md блока и его подпапки img и bg-img

# формат: node createBlock.js ИМЯБЛОКА [доп. расширения через пробел]
node createBlock.js block-test # создаст папку блока, block-test.pug, block-test.scss, подпапки img/ и bg-img/ для этого блока

Если блок уже существует, файлы не будут затёрты, но создадутся те файлы, которые ещё не существуют.

Назначение папок

build/          # Папка сборки, здесь работает сервер автообновлений.
src/            # Исходные файлы
  blocks/       # - блоки проекта
  css/          # - можно положить добавочные css-файлы (нужно подключить в copiedCss, иначе игнорируются)
  fonts/        # - можно положить шрифты проекта (будут автоматически скопированы в папку сборки)
  img/          # - можно положить добавочные картинки (нужно подключить в addImages, иначе игнорируются)
  js/           # - можно положить добавочные js-файлы (нужно подключить в addJsBefore, addJsAfter или copiedJs, иначе игнорируются)
  pug/          # - примеси, шаблоны pug
  scss/         # - стили (файл style.scss скомпилируется, прочие нужно подключить в addCssBefore, addCssAfter или singleCompiled, иначе они будут проигнорированы)
  index.pug     # - главная страница проекта
  blocks-demo.pug # - библиотека блоков

inquiring/NTH-start-project

Стартовый проект с gulp

Как начать новый проект c этим репозиторием

Парадигма

Разметка

Стили

Модульная сетка (flexbox)

Блоки

Подключение блоков

blocks

addCssBefore

addCssAfter

singleCompiled

addJsBefore

addJsAfter

addImages

copiedCss

copiedJs

Пример ./projectConfig.json