Подправил описания и задачи

README.md

@@ -50,7 +50,7 @@
 
 ### Стили
 
-Файл-диспетчер подключений (`.src/scss/style.scss`) формируется автоматически на основании указанных в `./package.json` блоков и доп. файлов.
+Файл-диспетчер подключений (`.src/scss/style.scss`) формируется автоматически на основании указанных в `./package.json` блоков и доп. файлов. Писать в этот файл что-либо руками бессмысленно: при старте автоматизации файл будет перезаписан.
 
 
 
@@ -74,50 +74,68 @@ demo-block/               # Папка блока
 
 
 
-### Удобное создание нового блока
+### Подключение блоков
 
-Предусмотрена команда бля быстрого создания файловой структуры нового блока.
+Настройки подключаемых файлов указаны в `./package.json`, в секции `configProject`.
 
-```bash
-# формат: node createBlock.js [имя блока] [доп. расширения через пробел]
-node createBlock.js block # создаст папку блока, block.html, block.scss и подпапку img/ для этого блока
-node createBlock.js new-block js pug # создаст папку блока, new-block.html, new-block.scss, new-block.js, new-block.pug и подпапку img/ для этого блока
-```
+`blocks` — объект с блоками, используемыми на проекте. Каждый блок — отдельная папка с файлами, по умолчанию лежат в `./src/blocks/`.
 
-Если блок уже существует, файлы не будут затёрты, но создадутся те файлы, которые ещё не существуют.
+Каждое подключение блока — массив, который можно оставить пустым или указать файлы элементов или модификаторов, если они написаны в виде отдельных файлов. В обоих случаях в обработку будут взяты одноименные стилевые файлы, js-файлы и картинки из папки `img/` блока.
 
+`addCssBefore` — массив с дополнительными стилевыми файлами, которые будут взяты в компиляцию ПЕРЕД стилевыми файлами блоков.
 
+`addCssAfter` — массив с дополнительными стилевыми файлами, которые будут взяты в компиляцию ПОСЛЕ стилевых файлов блоков.
 
-### Подключение блоков
+`addJsBefore` — массив js-файлов, которые будут взяты в обработку (конкатенация/сжатие) ПЕРЕД js-файлами блоков.
+
+`addJsAfter` — массив js-файлов, которые будут взяты в обработку (конкатенация/сжатие) ПОСЛЕ js-файлаов блоков.
+
+`addImages` — массив дополнительных изображений, добавляемый ПЕРЕД массивом изображений из блоков (внимание: при совпадении имен файлов, файлы из блоков имею бОльший приоритет и затрут файлы из этого массива)
+
+`copiedCss` — массив css-файлов, которые копируются в папку сборки, подпапку `css/`
+
+`copiedJs` — массив js-файлов, которые копируются в папку сборки, подпапку `js/`
+
+**ВНИМАНИЕ!** Это JSON. Это строгий синтаксис, у последнего элемента в любом контексте не должно быть запятой в конце строки.
 
-Настройки подключаемых файлов указаны в `./package.json`, в секции `configProject`:
+#### Пример секции в `./package.json`
 
 ```json
-"blocks": {
+"configProject": {
+  "blocks": {
     "page-header": [],
     "page-footer": [
       "__extra-element",
       "--extra-modifier"
     ]
-},
-"addCssBefore": [
+  },
+  "addCssBefore": [
     "./src/scss/variables.scss"
-],
-"addCssAfter": [
+  ],
+  "addCssAfter": [
     "./src/scss/print.scss"
-],
-"addJsBefore": [
-  "./src/js/jquery.3.1.1.min.js"
-],
-"addJsAfter": [
+  ],
+  "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/"
-],
+  ],
+  "addImages": [
+    "./src/img/*.{jpg,jpeg,gif,png,svg}"
+  ],
+  "copiedCss": [],
+  "copiedJs": [],
+  "dirs": {
+    "srcPath": "./src/",
+    "buildPath": "./build/",
+    "blocksDirName": "blocks"
+  }
+}
 ```
 
-При указанной записи в обработку будут взяты следующие папки и файлы (в указанной последовательности):
+В обработку будут взяты:
 
 ```bash
 css:
@@ -128,7 +146,8 @@ css:
    './src/blocks/page-footer/page-footer--extra-modifier.scss',
    './src/scss/print.scss' ],
 js:
- [ './src/js/jquery.3.1.1.min.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',
@@ -142,17 +161,32 @@ img:
 
 
 
+### Удобное создание нового блока
+
+Предусмотрена команда бля быстрого создания файловой структуры нового блока.
+
+```bash
+# формат: node createBlock.js [имя блока] [доп. расширения через пробел]
+node createBlock.js block # создаст папку блока, block.html, block.scss и подпапку img/ для этого блока
+node createBlock.js new-block js pug # создаст папку блока, new-block.html, new-block.scss, new-block.js, new-block.pug и подпапку img/ для этого блока
+```
+
+Если блок уже существует, файлы не будут затёрты, но создадутся те файлы, которые ещё не существуют.
+
+
+
 ## Назначение папок
 
 ```bash
-build/          # Сюда собирается проект, здесь работает сервер автообновлений.
+build/          # Папка сборки, здесь работает сервер автообновлений.
 src/            # Исходные файлы
-  _include/     # - фрагменты html для самого верха (секция head) и самого низа (перед закрывающим body) страницы
-  blocks/       # - блоки (компоненты) проекта
-  css/          # - можно положить добавочные css-файлы
-  img/          # - можно положить добавочные картинки
-  js/           # - можно положить добавочные js-файлы
-  scss/         # - папка с диспетчером подключений стилей и глобальными файлами
+  _include/     # - фрагменты html для вставки на страницы
+  blocks/       # - блоки проекта
+  css/          # - можно положить добавочные css-файлы (нужно подключить в copiedCss, иначе игнорируются)
+  fonts/        # - можно положить шрифты проекта (будут автоматически скопированы в папку сборки)
+  img/          # - можно положить добавочные картинки (нужно подключить в addImages, иначе игнорируются)
+  js/           # - можно положить добавочные js-файлы (нужно подключить в addJsBefore или addJsAfter, иначе игнорируются)
+  scss/         # - стили (всё, кроме style.scss нужно подключить в addCssBefore или addCssAfter, иначе оно будет проигнорировано)
   index.html    # - главная страница проекта
 ```
 

gulpfile.js

@@ -24,7 +24,6 @@ const newer = require('gulp-newer');
 let pjson = require('./package.json');
 let dirs = pjson.configProject.dirs;
 let lists = getFilesList(pjson.configProject);
-// console.log('---------- Файлы и папки, взятые в работу:');
 console.log(lists);
 
 // Запишем стилевой файл диспетчер подключений
@@ -87,7 +86,8 @@ gulp.task('style', function () {
 });
 
 // Копирование добавочных CSS, которые хочется иметь отдельными файлами
-gulp.task('copy:css', function() {
+gulp.task('copy:css', function(callback) {
+  if(pjson.configProject.copiedCss.length) {
     return gulp.src(pjson.configProject.copiedCss)
       .pipe(postcss(postCssPlugins))
       .pipe(cleanss())
@@ -98,6 +98,10 @@ gulp.task('copy:css', function() {
       }))
       .pipe(gulp.dest(dirs.buildPath + '/css'))
       .pipe(browserSync.stream());
+  }
+  else {
+    callback();
+  }
 });
 
 // Копирование изображений
@@ -114,8 +118,8 @@ gulp.task('copy:img', function () {
 });
 
 // Копирование JS
-gulp.task('copy:js', function () {
-  console.log('---------- Копирование отдельных JS-файлов');
+gulp.task('copy:js', function (callback) {
+  if(pjson.configProject.copiedJs.length) {
     return gulp.src(pjson.configProject.copiedJs)
       .pipe(size({
         title: 'Размер',
@@ -123,6 +127,10 @@ gulp.task('copy:js', function () {
         showTotal: false,
       }))
       .pipe(gulp.dest(dirs.buildPath + '/js'));
+  }
+  else {
+    callback();
+  }
 });
 
 // Копирование шрифтов
@@ -256,7 +264,8 @@ gulp.task('build', function (callback) {
     'sprite:svg',
     ['style', 'js', 'copy:css', 'copy:img', 'copy:js', 'copy:fonts'],
     'html',
-    callback);
+    callback
+  );
 });
 
 // Отправка в GH pages (ветку gh-pages репозитория)

src/_include/README.md

+
 Файлы, вставляемые внутрь других HTML-файлов при сборке страниц.

src/css/readme.md

 
 Дополнительные CSS-файлы, которые отчего-то, «не тянут» на полноценные БЭМ-блоки.
 
-Укажите эти файлы в `package.json` для попадания их в обработку.
+Укажите эти файлы в `package.json` для попадания их в обработку (см. `./README.md`).

src/img/readme.md

 
 Какие-то общие изображения проекта (контентные, к примеру).
 
-Укажите эту папку в `package.json` для попадания графических файлов в обработку.
+Укажите эту папку в `package.json` для попадания графических файлов в обработку (см. `./README.md`).

src/js/readme.md

 
 Дополнительные JS-файлы, которые отчего-то, «не тянут» на полноценные БЭМ-блоки.
 
-Укажите эти файлы в `package.json` для попадания их в обработку.
+Укажите эти файлы в `package.json` для попадания их в обработку (см. `./README.md`).

src/scss/readme.md

+
+`style.scss` генерируется автоматически, не пишите туда ничего.
+
+Прочие файлы игнорируются, если не упомянуты в `./package.jspn` (см. `./README.md`).