{"id":15170810,"url":"https://github.com/nicothin/nth-start-project","last_synced_at":"2025-10-01T05:30:54.967Z","repository":{"id":4006235,"uuid":"51305620","full_name":"nicothin/NTH-start-project","owner":"nicothin","description":"Startkit for HTML / CSS / JS pages layout.","archived":true,"fork":false,"pushed_at":"2023-01-07T13:54:48.000Z","size":7185,"stargazers_count":616,"open_issues_count":21,"forks_count":214,"subscribers_count":56,"default_branch":"master","last_synced_at":"2024-10-01T06:34:04.668Z","etag":null,"topics":["bem","css","gulp","hot-reload","html","postcss","postcss-image-inliner","pug","scss","start","starter","starter-kit","starter-project","starterkit"],"latest_commit_sha":null,"homepage":"https://nicothin.pro/NTH-start-project/blocks-demo.html","language":"Pug","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"wtfpl","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/nicothin.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2016-02-08T15:21:27.000Z","updated_at":"2024-09-23T19:06:07.000Z","dependencies_parsed_at":"2023-01-11T16:34:28.732Z","dependency_job_id":null,"html_url":"https://github.com/nicothin/NTH-start-project","commit_stats":null,"previous_names":[],"tags_count":7,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nicothin%2FNTH-start-project","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nicothin%2FNTH-start-project/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nicothin%2FNTH-start-project/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nicothin%2FNTH-start-project/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/nicothin","download_url":"https://codeload.github.com/nicothin/NTH-start-project/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":234827057,"owners_count":18892884,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bem","css","gulp","hot-reload","html","postcss","postcss-image-inliner","pug","scss","start","starter","starter-kit","starter-project","starterkit"],"created_at":"2024-09-27T08:23:08.763Z","updated_at":"2025-10-01T05:30:54.474Z","avatar_url":"https://github.com/nicothin.png","language":"Pug","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Стартовый проект с gulp  ![Test Status](https://travis-ci.org/nicothin/NTH-start-project.svg?branch=master) [![devDependencies Status](https://david-dm.org/nicothin/NTH-start-project/dev-status.svg)](https://david-dm.org/nicothin/NTH-start-project?type=dev) [![dependencies Status](https://david-dm.org/nicothin/NTH-start-project/status.svg)](https://david-dm.org/nicothin/NTH-start-project)\n\n\n## Парадигма\n\n- **Именование классов по БЭМ**, разметка в [pug](https://pugjs.org/), стилизация [Sass](http://sass-lang.com/). См. [как работать с CSS-препроцессорами и БЭМ](http://nicothin.github.io/idiomatic-pre-CSS/).\n- **Каждый БЭМ-блок в своей папке** внутри `src/blocks/`. Имена файлов в такой папке должны совпадать с именем блока. См. ниже про Блоки.\n- **Есть файл конфигурации**, определяющий попадание в сборку дополнительных файлов и неиспользованных в разметке блоков. Смотри `config.js`.\n- **Можно использовать глобальные файлы**:\n    - `src/js/script.js` — общий js, берётся в сборку по умолчанию,\n    - `src/scss/print.scss` — стили печати, не берутся в сборку по умолчанию (см. `config.js`).\n- **Список pug-примесей `src/pug/mixins.pug` генерируется автоматически** и содержит `include` существующих pug-файлов всех блоков.\n- **Диспетчер подключения стилей `src/scss/style.scss` генерируется автоматически** и содержит импорты стилевых файлов использованных в разметке блоков и импорты доп. файлов, указанных в `config.js`.\n- **Входная точка обработки js (`src/js/entry.js`) генерируется автоматически** и содержит `require` js-файлов использованных в разметке блоков и доп. файлов, указанных в `config.js`.\n- **Используется кодгайд** (относительно жёсткий), его проверка делается перед коммитом или вручную (`npm run test`), ошибки выводятся в терминал.\n- **Есть механизм быстрого создания нового блока**: `node createBlock.js new-block` (создаёт папки и scss-файл). После имени нового блока можно дописать нужные расширения.\n\n\n## Установка\n\nТребуются установленный [git](https://git-scm.com/) и [Node.js (LTS)](https://nodejs.org/en/).\n\n1. Открыть терминал, попасть в папку проектов, клонировать этот репозиторий: `git clone https://github.com/nicothin/NTH-start-project.git my-new-project` (где `my-new-project` — папка для нового проекта).\n2. Перейти в папку нового проекта (в этом примере — `cd my-new-project`).\n3. Удалить историю разработки: `rm -rf .git`\n4. Установить зависимости проекта: `npm i` (может быть долго, особенно на Windows).\n\n\n## Команды\n\n```bash\nnpm start          # запуск сервера разработки (сборка БЕЗ библиотеки блоков)\nnpm start deploy   # отправка содержимого папки сборки на gh-pages (нужен репозиторий на github.com)\nnpm run build      # сборка БЕЗ библиотеки блоков и без запуска сервера разработки\nnpm run wlib       # запуск сервера разработки (сборка проекта с библиотекой блоков)\nnpm run test       # проверка всех pug-, scss- и js-файлов на соответствие правилам (см. .pug-lintrc, .stylelintrc и eslintrc соответственно)\nnpm run test:pug   # проверить только pug-файлы\nnpm run test:style # проверить только scss-файлы\nnpm run test:js    # проверить только js-файлы\n```\n\n\n## Структура\n\n```bash\nbuild/       # Папка сборки (результат работы над проектом)\nsrc/         # Исходники\n  blocks/    # Блоки (подпапки с блоками)\n  favicon/   # Фавиконки (копирование прописать в config.js)\n  fonts/     # Шрифты (копирование прописать в config.js, подключение в src/blocks/page/page.scss)\n  img/       # Общие для всех блоков изображения (копирование прописать в config.js)\n  js/        # Общие js-файлы, в т.ч. точка сборки для webpack и общие модули\n  pages/     # Страницы проекта (при компиляции: src/pages/index.pug → build/index.html)\n  pug/       # Служебные pug-файлы (шаблоны страниц, примеси)\n  scss/      # Служебные стилевые файлы (диспетчер подключений, переменные, примеси)\n```\n\n\n## Как это работает\n\nПри `npm start` запускается дефолтная задача gulp:\n\n1. Очищается папка сборки (`build/`).\n5. Записывается файл `src/pug/mixins.pug` с includ-ами pug-файлов всех блоков.\n5. Компилируются файлы страниц (из `src/pages/**/*.pug` в `build/*.html`).\n5. Из скомпилированных html-файлов извлекаются все классы уровня БЭМ-блока. На основании этого списка будут построены диспетчер подключения стилей и список всех js-файлов проекта.\n5. Генерируются спрайты (если блоки спрайтов используются), в папку сборки копируются картинки блоков и доп. файлы из секции `addAssets` файла `config.js`.\n5. Записывается диспетчер подключения стилей `src/scss/style.scss`, в котором:\n    - Импорты файлов из секции `addStyleBefore` файла `config.js`. По умолчанию — SCSS-переменные и примеси.\n    - Импорты файлов БЭМ-блоков, упомянутых в секции `alwaysAddBlocks` файла `config.js`. Таким образом, можно взять в сборку любой блок, даже если его css-класс не упоминается в разметке страниц.\n    - Импорты файлов БЭМ-блоков, использующихся в разметке.\n    - Импорты файлов из секции `addStyleAfter` файла `config.js`.\n5. Записывается входная точка обработки скриптов `src/js/entry.js`, в которой:\n    - `require` файлов из секции `addJsBefore` файла `config.js`.\n    - `require` файлов БЭМ-блоков, использующихся в разметке.\n    - `require` файлов БЭМ-блоков, упомянутых в секции `alwaysAddBlocks` файла `config.js`.\n    - `require` файлов из секции `addJsAfter` файла `config.js`.\n5. Компилируется диспетчер подключения стилей (`src/scss/style.scss`). Результат обрабатываются плагинами PostCSS.\n6. Обрабатывается входная точка Javascript (`src/js/entry.js`). Используется Webpack.\n5. Запускается локальный сервер и слежение за файлами для пересборки.\n\n\n## Блоки\n\nКаждый блок лежит в `src/blocks/` в своей папке.\n\nВозможное содержимое блока:\n\n```bash\ndemo-block/        # Папка блока.\n  img/             # Изображения, используемые этим блоком (копируются в папку сборки).\n  demo-block.pug   # Разметка (pug-примесь, отдающая разметку этого блока, описание API примеси).\n  demo-block.scss  # Стилевой файл этого блока (без стилей других блоков).\n  demo-block.js    # js-файл блока (без скриптов других блоков).\n  readme.md        # Описание для документации, подсказки.\n```\n\n\n### Особенный блок `page`\n\nНа теге `\u003chtml\u003e` по умолчанию прописан класс `page`, что делает одноимённый блок «глобальным». В стилях этого блока прописываются:\n\n- подключение сторонних шрифтов,\n- смена боксовой модели,\n- cтили шаблона (см. `src/pug/layout.pug`),\n- стилизация тегов по умолчанию (аналог Normalize.CSS).\n\n\n### Удобное создание нового блока\n\n```bash\n# формат: node createBlock.js ИМЯБЛОКА [доп. расширения через пробел]\nnode createBlock.js demo-block        # создаст папку блока, demo-block.scss, подпапку img/ для этого блока\nnode createBlock.js demo-block pug js # создаст папку блока, demo-block.scss, demo-block.pug, demo-block.js, подпапку img/ для этого блока\n```\n\nЕсли блок уже существует, файлы не будут затёрты, но создадутся те файлы, которые ещё не существуют.\n\n\n## Сторонние npm-модули\n\nЕсли нужно взять в сборку сторонний модуль, то после его установки (к примеру — `npm i package-name`) нужно:\n\n1. Прописать `require` в js-файле проектного блока (там же писать всё, что касается работы с этим модулем). Если сторонний модуль нужен без привязки к какому-либо проектому блоку, прописать `require` в `src/js/script.js` (см. пример в файле).\n2. Если нужно брать в сборку стилевые файлы модуля, прописать их в секции `addStyleBefore` файла `config.js` (пример в файле).\n3. Если нужно брать в сборку дополнительные файлы модуля, прописать их в `addAssets` файла `config.js` с указанием в какую папку их копировать (пример в файле).\n\n\n## Разметка\n\nИспользуется [pug](https://pugjs.org/api/getting-started.html).\n\nВсе страницы (см. `src/pages/index.pug`) являются расширениями шаблонов из `src/pug` (см. [наследование шаблонов](https://pugjs.org/language/inheritance.html)), в страницах описывается только содержимое «шапки», «подвала» и контентной области (см. [блоки](https://pugjs.org/language/inheritance.html#block-append-prepend)).\n\nКаждый блок (в `src/blocks/`) может (не обязан) содержать одноимённый pug-файл с одноименной примесью, который при старте сервера разработки будет взят includ-ом в файл `src/pug/mixins.pug`.\n\n\n## Стили\n\nДиспетчер подключений (`src/scss/style.scss`) формируется автоматически при старте сервера разработки.\n\nКаждый блок (в `src/blocks/`) может содержать одноимённый scss-файл со стилями этого блока. Если блок используется в разметке (или упомянут в `config.js#alwaysAddBlocks`), его scss-файл будет взят в сборку стилей.\n\nИспользуемый постпроцессинг:\n\n1. [autoprefixer](https://github.com/postcss/autoprefixer)\n2. [css-mqpacker](https://github.com/hail2u/node-css-mqpacker)\n3. [postcss-import](https://github.com/postcss/postcss-import)\n4. [postcss-inline-svg](https://github.com/TrySound/postcss-inline-svg)\n\n### Стилевой код-гайд\n\nАвтопроверка с [stylelint](https://stylelint.io/) и плагинами. См. `.stylelintrc`.\n\n1. БЭМ-именование: `__` — разделитель элемента, `--` — разделитель модификатора.\n2. Один Блок = один стилевой файл.\n3. Очередность селекторов:\n    - Инклуды примесей\n    - Стилевые правила сущности\n    - Медиаусловия\n    - Псевдоселекторы и псевдоэлементы\n    - Сторонние вложенные селекторы\n    - Элементы блока\n    - Модификаторы блока\n\n\n## Скрипты\n\nТочка входа (`src/js/entry.js`) формируется автоматически при старте сервера разработки. Точка входа обрабатывается webpack-ом (с babel-loader).\n\nДля глобальных действий предусмотрен `src/js/script.js` (см. `config.js#addJsAfter` и `config.js#addJsBefore`).\n\nКаждый блок (в `src/blocks/`) может (не обязан) содержать одноимённый js-файл. Если блок используется в разметке (или упомянут в `config.js#alwaysAddBlocks`), его js-файл будет взят в сборку стилей.\n\n### Инлайн-скрипт\n\nПо умолчанию в шаблоне (`src/pug/layout.pug`) прописана вставка в `\u003chead\u003e` скрипта `src/js/head-script.js`, в котором для узла `\u003chtml\u003e` указано:\n\n- Убрать класс `no-js` и добавить класс `js`.\n- Добавить класс с указанием названия браузера и ОС.\n- Добавить класс `touch` или `no-touch`, в зависимости от типа интерфейса.\n- Добавить кастомное свойство `--vh` со значением в 1% высоты вьюпорта (значение пересчитывается при изменении размеров).\n\n\n## Нравится проект?\n\nСтавьте звезду репозиторию и/или [угостите меня кофе](https://money.yandex.ru/to/41001252765094), переведя сколь угодно символическую сумму.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnicothin%2Fnth-start-project","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnicothin%2Fnth-start-project","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnicothin%2Fnth-start-project/lists"}