Skip to content

K
kpp
Commit cffe5a4a authored by Nikolay Gromov's avatar Nikolay Gromov
Browse files
Options

Описание: поправил

parent a4b75906
Show whitespace changes
Inline Side-by-side
Showing with 95 additions and 51 deletions
README.md
View file @ cffe5a4a
...@@ -16,11 +16,11 @@ ...@@ -16,11 +16,11 @@
## Команды ## Команды
`npm start` — сборка проекта **без библиотеки блоков**, слежение. `npm start` — запуск сервера разработки (сборка **без библиотеки блоков**).
`npm run wlib` — сборка проекта с библиотекой блоков, слежение. `npm run wlib` — запуск сервера разработки (сборка проекта с библиотекой блоков).
`npm run deploy` — cборка проекта (с библиотекой) и отправка содержимого папки сборки на gh-pages (не сработает, если проект не имеет репозитория на github.com). `npm run deploy` — cборка проекта (с библиотекой) и отправка содержимого папки сборки на gh-pages (не сработает, если проект не имеет репозитория на github.com).
## Структура ## Структура
...@@ -38,14 +38,30 @@ src/ # Исходники ...@@ -38,14 +38,30 @@ src/ # Исходники
``` ```
## Как начать новый проект c этим репозиторием
```bash
# Клонировать в новую папку
git clone https://github.com/nicothin/NTH-start-project.git new-project
# Зайти в папку
cd new-project
# Убрать историю разработки
rm -rf .git
# Отредактировать config.js, LICENSE, README.md, package.json
# Установить зависимость
npm i
# Запустить сервер разработки
npm start
```
## Как это работает ## Как это работает
При `npm start` (запускается дефолтная задача gulp): При `npm start` запускается дефолтная задача gulp:
1. Создаётся глобальный объект `nth` с настройками проекта. 1. Очищается папка сборки (`build/`).
5. Очищается папка сборки (`build/`).
5. Записывается `src/pug/mixins.pug` и компилируются файлы страниц (`src/pages/**/*`). 5. Записывается `src/pug/mixins.pug` и компилируются файлы страниц (`src/pages/**/*`).
5. Из скомпилированных страниц извлекаются все классы уровня БЭМ-блока и записываются в `nth.blocksFromHtml`. 5. Из скомпилированных html-файлов извлекаются все классы уровня БЭМ-блока, чтобы взять в сборку css и javascript только нужные файлы.
5. Генерируются спрайты, в папку сборки копируются доп. файлы и картинки. 5. Генерируются спрайты, в папку сборки копируются доп. файлы и картинки.
5. Записывается `src/scss/style.scss`, в котором: 5. Записывается `src/scss/style.scss`, в котором:
- Импорты файлов из `config.js#addStyleBefore`. - Импорты файлов из `config.js#addStyleBefore`.
...@@ -55,31 +71,52 @@ src/ # Исходники ...@@ -55,31 +71,52 @@ src/ # Исходники
- `require` файлов из `config.js#addJsBefore`. - `require` файлов из `config.js#addJsBefore`.
- `require` файлов БЭМ-блоков, использующихся на проекте (если их js-файлы существуют). - `require` файлов БЭМ-блоков, использующихся на проекте (если их js-файлы существуют).
- `require` файлов из `config.js#addJsAfter`. - `require` файлов из `config.js#addJsAfter`.
5. Компилируются и обрабатываются PostCSS-ом стили (`src/scss/style.scss`), собирается скрипт (`src/js/entry.js`). 5. Компилируются и обрабатываются PostCSS-ом стили (`src/scss/style.scss`), собирается javascript (`src/js/entry.js`).
5. Запускается локальный сервер и слежение за файлами для пересборки. 5. Запускается локальный сервер и слежение за файлами для пересборки.
## Как начать новый проект c этим репозиторием ## Блоки
Каждый блок лежит в `src/blocks/` в своей папке.
Возможное содержимое блока:
```bash
demo-block/ # Папка блока.
bg-img/ # Изображения для использования в стилях (не обрабатываются автоматикой).
img/ # Изображения, используемые блоком (копируются в папку сборки).
demo-block.pug # Разметка (pug-примесь, отдающая разметку блока, описание API примеси).
demo-block.scss # Стилевой файл блока.
demo-block.js # js-файл блока.
readme.md # Описание для документации, подсказки.
```
### Удобное создание нового блока
```bash
# формат: node createBlock.js ИМЯБЛОКА [доп. расширения через пробел]
node createBlock.js demo-block # создаст папку блока, demo-block.scss, подпапки img/ и bg-img/ для этого блока
node createBlock.js demo-block pug js # создаст папку блока, demo-block.scss, demo-block.pug, demo-block.js, подпапки img/ и bg-img/ для этого блока
```
1. Клонировать этот репозиторий в новую папку (`git clone https://github.com/nicothin/NTH-start-project.git new-project`, см. [шпаргалку](https://github.com/nicothin/web-development/tree/master/git#%D0%9A%D0%BB%D0%BE%D0%BD%D0%B8%D1%80%D0%BE%D0%B2%D0%B0%D0%BD%D0%B8%D0%B5-%D1%80%D0%B5%D0%BF%D0%BE%D0%B7%D0%B8%D1%82%D0%BE%D1%80%D0%B8%D1%8F)) и зайти в неё (`cd new-project`). Если блок уже существует, файлы не будут затёрты, но создадутся те файлы, которые ещё не существуют.
2. Стереть историю разработки этого репозитория (`rm -rf .git`), инициировать новый (`git init`), создать удалённый репозиторий и привязать его (`git remote add origin АДРЕС`, см. [шпаргалку](https://github.com/nicothin/web-development/tree/master/git#%D0%A3%D0%B4%D0%B0%D0%BB%D1%91%D0%BD%D0%BD%D1%8B%D0%B5-%D1%80%D0%B5%D0%BF%D0%BE%D0%B7%D0%B8%D1%82%D0%BE%D1%80%D0%B8%D0%B8)).
3. Отредактировать `LICENSE`, `README.md`, `package.json` (название проекта, автор, лицензия, необходимые пакеты и пр.) и `config.js` (нужные на проекте блоки, сторонние пакеты). Удалив пакет из `package.json`, не забудьте убрать его из `config.js`.
4. Установить зависимости (`npm i`).
5. Запустить сервер разработки (`npm start`).
## Разметка ## Разметка
Используется [pug](https://pugjs.org/api/getting-started.html). HTML никак не обрабатывается. Используется [pug](https://pugjs.org/api/getting-started.html).
По умолчанию используются [наследование шаблонов](https://pugjs.org/language/inheritance.html) — все страницы (см. `src/index.pug`) являются расширениями шаблонов, в страницах описывается только содержимое «шапки», «подвала» и контентной области посредством [блоков](https://pugjs.org/language/inheritance.html#block-append-prepend). Все страницы (см. `src/pages/index.pug`) являются расширениями шаблонов из `src/pug` (см. [наследование шаблонов](https://pugjs.org/language/inheritance.html)), в страницах описывается только содержимое «шапки», «подвала» и контентной области (см. [блоки](https://pugjs.org/language/inheritance.html#block-append-prepend)).
Каждый блок (в `src/blocks/`) может содержать pug-файл с одноименной примесью, который будет взят includ-ом в файле `src/pug/mixins.pug`. Каждый блок (в `src/blocks/`) может содержать одноимённый pug-файл с одноименной примесью, который при старте сервера разработки будет взят includ-ом в файл `src/pug/mixins.pug`.
## Стили ## Стили
Диспетчер подключений (`src/scss/style.scss`) формируется автоматически, писать в него что-либо руками бессмысленно: при старте автоматизации файл будет перезаписан. Диспетчер подключений (`src/scss/style.scss`) формируется автоматически при старте сервера разработки.
Каждый блок (в `src/blocks/`) может содержать одноимённый scss-файл со стилями этого блока. Если блок используется в разметке (или упомянут в `config.js#alwaysAddBlocks`), его scss-файл будет взят в сборку стилей.
Используемый постпроцессинг: Используемый постпроцессинг:
...@@ -92,55 +129,61 @@ src/ # Исходники ...@@ -92,55 +129,61 @@ src/ # Исходники
## Скрипты ## Скрипты
Точка входа (`src/js/entry.js`) формируется автоматически, писать в него что-либо руками бессмысленно: при старте автоматизации файл будет перезаписан. Точка входа обрабатывается webpack-ом (с babel-loader). Точка входа (`src/js/entry.js`) формируется автоматически при старте сервера разработки. Точка входа обрабатывается webpack-ом (с babel-loader).
Для глобальных действий предусмотрен `src/js/script.js` (см. `config.js#addJsAfter` и `config.js#addJsBefore`). Для глобальных действий предусмотрен `src/js/script.js` (см. `config.js#addJsAfter` и `config.js#addJsBefore`).
Каждый блок может содержать одноимённый js-файл. При условии использования блока в разметке (или упоминания в `config.js#alwaysAddBlocks`) такой js-файл будет взят в сборку. Каждый блок (в `src/blocks/`) может содержать одноимённый js-файл. Если блок используется в разметке (или упомянут в `config.js#alwaysAddBlocks`), его js-файл будет взят в сборку стилей.
### Модульная сетка (flexbox) ## Модульная сетка (flexbox)
По умолчанию в сборку берётся [файл с примесями](https://github.com/nicothin/NTH-start-project/blob/master/src/scss/mixins/grid-mixins.scss), возвращающими правила модульной сетки. Никаких селекторов в CSS не добавляет, нужно писать семантические селекторы и вызывать примеси, передавая им настройки сетки. Настройки по умолчанию вынесены в переменные (`$grid-columns: 12;` и `$grid-gutter-width: 30px;`). По умолчанию в сборку берётся [файл с примесями](https://github.com/nicothin/NTH-start-project/blob/master/src/scss/mixins/grid-mixins.scss), возвращающими правила модульной сетки. Cелекторов в CSS не добавляет, нужно писать семантические селекторы и вызывать примеси. Настройки по умолчанию вынесены в переменные (`$grid-columns: 12;` и `$grid-gutter-width: 30px;`).
Посмотреть примеры и попробовать вживую можно в [этом примере с codepen.io](https://codepen.io/nicothin/pen/aJEOwE?editors=1100). - Любое кол-во колонок, в т.ч. разная колоночность на разных ширинах вьюпорта.
- Любые промежутки между колонками, в т.ч. разные на разных ширинах вьюпорта.
```scss
.promo {
## Блоки &__inner {
@include container(); // это контейнер, padding по умолчанию (из переменной)
}
Каждый блок лежит в `src/blocks/` в своей папке. &__grid {
@include row();// это прямой родитель сетки, margin по умолчанию (из переменной)
}
Возможное содержимое блока: &__img {
@include col(); // узкий вьюпорт, 100% ширина и padding по умолчанию
```bash @include col(md, 5); // MD-вьюпорт (786 по умолчанию) ширина 5 колонок и padding по умолчанию
demo-block/ # Папка блока. }
bg-img/ # Изображения для использования в стилях (не обрабатываются автоматикой сборки).
img/ # Изображения, используемые блоком и обрабатываемые автоматикой сборки.
demo-block.pug # Разметка (pug-примесь, отдающая разметку блока, описание API примеси).
demo-block.scss # Стилевой файл блока.
demo-block.js # js-файл блока.
readme.md # Описание для документации, подсказки.
```
## Подключение блоков
Если блок (css-класс блока) использован в разметке, то блок будет взят в сборку.
Если нужно взять в сборку блок без использования его класса в разметке, нужно упомянуть блок в `config.js#alwaysAddBlocks`.
&__text {
@include col(); // узкий вьюпорт, 100% ширина и padding по умолчанию
@include col(md, 7); // MD-вьюпорт (786 по умолчанию) ширина 7 колонок и padding по умолчанию
}
}
## Удобное создание нового блока ```
Предусмотрена команда для быстрого создания файловой структуры нового блока. По умолчанию создаются: scss-файл и подпапки `img`, `bg-img`
```bash ```scss
# формат: node createBlock.js ИМЯБЛОКА [доп. расширения через пробел] .row
node createBlock.js block-test # создаст папку блока, block-test.scss, подпапки img/ и bg-img/ для этого блока // Родитель. Указаны промежутки между ячейками: XS|SM|MD|LG|XL|XXL;
node createBlock.js block-test pug js # создаст папку блока, block-test.scss, block-test.pug, block-test.js, подпапки img/ и bg-img/ для этого блока @include row($grid-gutter-width, 10px, 12px, 16px, 20px, 26px);
&__element {
@include col(); // малые ширины — 12 из 12, промежутки по умолчанию
@include col(sm, 6, $grid-columns, 10px); // SM (480 по умолчанию) — 6 из 12, промежутки 10px
@include col(md, 4, $grid-columns, 12px); // MD (768 по умолчанию) — 4 из 12, промежутки 12px
@include col(lg, 3, $grid-columns, 16px); // LG (992 по умолчанию) — 3 из 12, промежутки 16px
@include col(xl, 2, $grid-columns, 20px); // XL (1200 по умолчанию) — 2 из 12, промежутки 20px
@include col(xxl, 1, $grid-columns, 26px); // XXL (1800 по умолчанию) — 1 из 12, промежутки 26px
}
}
``` ```
Если блок уже существует, файлы не будут затёрты, но создадутся те файлы, которые ещё не существуют. Посмотреть примеры и попробовать вживую можно в [этом примере с codepen.io](https://codepen.io/nicothin/pen/aJEOwE?editors=1100).
## Нравится проект? ## Нравится проект?
......
config.js
View file @ cffe5a4a
...@@ -10,6 +10,7 @@ let config = ...@@ -10,6 +10,7 @@ let config =
], ],
"alwaysAddBlocks": [ "alwaysAddBlocks": [
"sprite-svg", "sprite-svg",
"object-fit-polyfill",
], ],
"addStyleBefore": [ "addStyleBefore": [
"src/scss/variables.scss", "src/scss/variables.scss",
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment