Команда | Результат |
---|---|
npm i |
Установить зависимости |
npm start |
Запустить сборку, сервер и слежение за файлами |
npm start ЗАДАЧА |
Запустить задачу с названием ЗАДАЧА (список задач в gulpfile.js ) |
npm run build |
Сборка проекта без карт кода (сжатый вид, как результат работы) |
npm run deploy |
Сборка проекта без карт кода и отправка содержимого папки сборки на github-pages (для корректного сообщения адреса просмотра введите его в ./package.json ) |
npm run test:style |
Проверка стилевой составляющей проекта stylelint |
npm run test:orpho |
Поиск ошибок и опечаток в .html и .md файлах в ./src с помощью yaspeller |
Если при вызове npm start
ничего не происходит, смотрите ./projectConfig.json
, он содержит синтаксическую ошибку. Проверить можно линтером
Парадигма
- Используется именование классов, файлов и переменных по БЭМ.
- Список использованных в проекте БЭМ-блоков и доп. файлов указан в
./projectConfig.json
. - Каждый БЭМ-блок в своей папке внутри
./src/blocks/
(стили, js, картинки, разметка; обязателен только стилевой файл). - Есть глобальные файлы: стилевые, js, шрифты, картинки.
- Диспетчер подключения стилей
./src/scss/style.scss
генерируется автоматически при старте любой gulp-задачи. - Для разметки можно использовать микрошаблонизацию. А можно и не использовать.
- Перед созданием коммита запускается проверка стилевых файлов и проверка орфографии в
.html
и.md
файлах, входящих в коммит.
ЧАВО
Есть вопрос — задайте его в issues.
Стили
Файл-диспетчер подключений (.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 указано ограничение на размер файла в 10 Кб, файлы ищутся в src/blocks/**/img_to_bg/
. Чтобы избежать конфликтов имен, добавляйте к именам изображений префикс (имя блока), например: src/blocks/mega-block/img_to_bg/mega-block__avatar.png
Блоки
Каждый блок лежит в ./src/blocks/
в своей папке. Каждый блок — как минимум, папка и одноимённый scss-файл.
Возможное содержимое блока:
demo-block/ # Папка блока
img/ # Изображения, используемые блоком и обрабатываемые автоматикой сборки
some-folder/ # Какая-то сторонняя папка, не обрабатываемая автоматикой
demo-block.scss # Стилевой файл блока
demo-block--mod.scss # Отдельный стилевой файл БЭМ-модификатора блока
demo-block.js # js-файл блока
demo-block--mod.js # js-файл для отдельного БЭМ-модификатора блока
demo-block.html # Варианты разметки (как документация блока или как вставляемый микрошаблонизатором фрагмент)
readme.md # Какое-то пояснение
Подключение блоков
Список используемых блоков и дополнительных подключаемых файлов указан в ./projectConfig.json
. Список файлов и папок, взятых в обработку можно увидеть в терминале, если раскомментировать строку console.log(lists);
в gulpfile.js
.
blocks
Объект с блоками, используемыми на проекте. Каждый блок — отдельная папка с файлами, по умолчанию лежат в ./src/blocks/
.
Каждое подключение блока — массив, который можно оставить пустым или указать файлы элементов или модификаторов, если они написаны в виде отдельных файлов. В обоих случаях в обработку будут взяты одноименные стилевые файлы, 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/
ВНИМАНИЕ! Это JSON. Это строгий синтаксис, у последнего элемента в любом контексте не должно быть запятой в конце строки.
./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}' ]
Удобное создание нового блока
Предусмотрена команда для быстрого создания файловой структуры нового блока.
# формат: node createBlock.js ИМЯБЛОКА [доп. расширения через пробел]
node createBlock.js block-1 # создаст папку блока, block-1.html, block-1.scss и подпапку img/ для этого блока
node createBlock.js block-2 js pug # создаст папку блока, block-2.html, block-2.scss, block-2.js, block-2.pug и подпапку img/ для этого блока
Если блок уже существует, файлы не будут затёрты, но создадутся те файлы, которые ещё не существуют.
Назначение папок
build/ # Папка сборки, здесь работает сервер автообновлений.
src/ # Исходные файлы
_include/ # - фрагменты html для вставки на страницы
blocks/ # - блоки проекта
css/ # - можно положить добавочные css-файлы (нужно подключить в copiedCss, иначе игнорируются)
fonts/ # - можно положить шрифты проекта (будут автоматически скопированы в папку сборки)
img/ # - можно положить добавочные картинки (нужно подключить в addImages, иначе игнорируются)
js/ # - можно положить добавочные js-файлы (нужно подключить в addJsBefore, addJsAfter или copiedJs, иначе игнорируются)
scss/ # - стили (style.scss скомпилируется, прочие нужно подключить в addCssBefore, addCssAfter или singleCompiled, иначе они будут проигнорированы)
index.html # - главная страница проекта
blocks-demo.html # - библиотека блоков
Комментирование для разработчиков
Для html-файлов можно использовать комментарии вида <!--DEV Комментарий -->
— такие комментарии не попадут в собранный html.