marmelad

Заготовка фронтенд проекта для продвинутых и начинающих 🤘. Хорошо подходит для поддержания единой структуры проектов в команде и легкого переиспользования готовых блоков между проектами, благодаря БЭМ подходу к организации файловой структуры и данных проекта.

Зависимости marmelad устанавливаются один раз и в будущем только обновляются, т.е. нет необходимости устанавливать кучу npm зависимостей для каждого проекта. Как следствие, экономия дискового пространства и возможность создания и работы в проектах без интернета.

Содержание

Установка
Marmelad CLI
Marmelad TCI
Структура проекта
Шаблоны/Блоки
- Lagman
Данные для шаблонов/блоков
- incw расширение
Сборка стилей
- Post CSS плагины
Bootstrap
- Bootstrap как донор

Внимание

Вам нужно установить java для работы с node-w3c-validator.

Установка

Не пытайтесь установить marmelad путём копирования файлов сборщика с Windows на Linux. Для разных ОС устанавливаются разные зависимости. Пользуйтесь доступными способами для установки.

Проблемы установки глобальных модулей для macOS и Linux

По умолчанию npm устанавливает пакеты локально в ваших проектах. Вы также можете установить установочные пакеты глобально (например, npm install -g <package>) (полезно для приложений командной строки). Однако недостатком этого является то, что вам нужно получить root-права (или использовать sudo) для возможности глобальной установки.

Ознакомьтесь с руководством NPM для установки глобальных модулей Resolving EACCES permissions errors when installing packages globally

Установка из npm

npm i marmelad -g

Установка для разработчиков

git clone https://github.com/solversgroup/marmelad.git
cd marmelad
npm i
npm link # sudo npm link для linux

Установка для определённого проекта

Такой тип установки подходит, когда заказчик требует определённую структуру размещения файлов проекта, либо работа сборщика нуждается в переделке под проектные требования. Там может быть всё что угодно 😱.

Установка для определённого проекта производится также, как и Установка для разработчиков, отличается только в запуск.

Для инициализируя/запуская marmelad необходимо указать путь до исполняемого файла marmelad.

# node C:\marmelad\bin\marmelad.js 
node <путь до директории клона>\bin\marmelad.js

Marmelad CLI

После установки из npm или для разработчиков, marmelad станет доступен в командной строке/терминале вашей системы как marmelad и mmd.

Для справки по командам marmelad необходимо ввести в консоль/терминал:

# без параметров 
marmelad # или mmd 
# или 
marmelad --help # или mmd --help 
 
Usage: marmelad [options] [command]
 
Заготовка фронтенд проекта для продвинутых и начинающих 🤘
 
Options:
  -v, --version                     output the version number
  -h, --help                        display help for command
 
Commands:
  init [options] [dir]              initialize new project
  dev [options]                     run development server
  cp <name>                         create new page
  cb [options] <name>               create new block
  mv [options] <oldName> <newName>  rename block
  lint                              lint project
  dist                              Release tasks for project
  pack [options] [name]             Archive project source code (default:tar.gz)
  help [command]                    display help for command
 
Commands help:
  marmelad [command] --help
  mmd [command] --help
 
Source files:
  <marmelad installed directory>\marmelad\bin\marmelad.js
Version:
  <marmelad version>

`init [options]` инициализация

Инициализация проходит в 3 этапа:

Копирование базовой заготовки с учётом переданных аргументов
Копирование в корень нового проекта вспомогательных файлов
Инициализация git репозитория в новом проекте

Для инициализации нового проекта, предназначена команда mmd init [options] [dir].

В случае, когда не передан параметр для папки инициализации, проект инициализируется в текущей директории открытой в терминале.

-c, --css - заменяет значение ключа app.css в settings.marmelad.js при копировании заготовки нового проекта. Далее этот ключ используется для команды создания блока mmd cb, для создания файлов css препроцессоров, с расширением установленным в app.css в settings.marmelad.js. Для добавления поддержки в проект на старом проекте после обновления до актуальной версии marmelad, необходимо добавить в settings.marmelad.js в объект app свойство css со значением/расширением требуемого css препроцессора.

-t, --test - необходим только для тестирования, в разработке проектов никакого смысла он не имеет.

--bootstrap - инициализирует новый проект с bootstrap, копируя его в базовую заготовку.

--bootstrap donor - автоматически включает bootstrap как донор.

[dir] - позволяет инициализировать проект в указанной папке. Например, mmd init new-and-awesome -t scss.

`dev [options]` старт сборки

Внимание если при запуске сборки вы видите ошибку code: 'MODULE_NOT_FOUND', то, скорее всего marmelad запускается в директории без предварительно созданного (mmd init) пустого marmelad проекта.

dev стандартный запуск
dev -a запуск сервера с парольной защитой, логин и пароль генерируются автоматически
dev -a <login>@<password> запуск сервера с парольной защитой, логин и пароль устанавливаются вручную
dev --build одноразовая сборка проекта без запуска слежения за изменениями и пересборки
dev --proxy-mod режим сборки статики + проксирование уже живого сайта с копированием необходимых ресурсов (css,js) в определённую директорию рабочего сайта

dev --proxy-mod ошибка Error: Missing positive glob означает что вы не прописали в конфиге директории для копирования, по умолчанию они закомментированы.

`cp <name>` создание страницы

Файл страницы создаётся в директории marmelad/_pages, в имени файла расширение не указывается.

`cb <name> [options]` создание блока

Файлы блока создаются в директории marmelad/_blocks.

#.tci 
cb new-block --t html,js

Создаст одноимённый блок, содержащий в себе все необходимые технологии.

# marmelad/_blocks 
new-block
  ├─ new-block.html  # шаблон 
  └─ new-block.js    # скрипты

Параметр --t позволяет указывать конкретно какие технологии необходимо создать. По сути в этот параметр можно перечислить через зяпятую сколько угодно форматов.

Формат для стилей указывать необязательно, если он не будет указан, то команда создаст файл с форматом стилей, который указан в settings.marmelad.js -> app.css.

`mv <oldName> <newName> [options]` переименование блока

Переименовать блок и все вхождения имени блока внутри файлов блока, в случае необходимости. Команда доступна в файле .tci.

# переименование файлов блока 
mv old-block-name new-block-name
 
# переименование файлов блока и все вхождения внутри файлов блока 
mv old-block-name new-block-name --hard
 
# холостой запуск с просмотром планируемых изменений в файлах 
mv old-block-name new-block-name --dry --hard

`lint` W3C валидатор

Запуск W3C валидатора на уже собранном проекте.

Запуск W3C валидатора необходимо выполнять только после сборки проекта, иначе результаты валидации будут некорректны.

mmd dev --build && mmd lint

`dist` релизные задачи

Экспериментальная команда, пока никаких опций передать нельзя. Работает только с итоговыми файлами проекта, исходники никак не будут затронуты.

Форматирование HTML-кода страниц проекта в папке сборки (static)
Обжатие JS/CSS файлов и замена на обжатые в HTML шаблонах (обжимаются файлы без .min в названии)
Прописывание хешей для подключаемых файлов, для сброса кэша
Сортировка атрибутов HTML элементов

mmd dev --build && mmd dist

`pack [name] [options]` архивирование проекта

Упаковывает файлы проекта в tgz или zip архив.

pack tgz архив
pack -z, --zip zip архив
pack -f, --folders [marmelad,static] упаковать только определённые директории в архив
pack --nodt не подставлять дату и время создания в имя архива (отлючено по умолчанию)
pack custom-name кастомное имя для архива, иначе имя архива позаимсвуется у корневой папки проекта

pack           # project_11072019-153012.tgz 
pack my-name   # my-name_11072019-153012.tgz 
pack -z        # project_11072019-153012.zip 
pack -f static # project_11072019-153012.tgz только директория static 
pack --nodt    # project.tgz без даты и времени в названии (отключено по умолчанию)

Marmelad TCI

TCI (text command interface) - добавлен в шаблон вёрстки и дублирует CLI команды marmelad (cp, cb), т.е. нет необходимости переходить в другую консоль/терминал, и в там уже выполнять доп. действия.

Теперь для этого есть файл .tci, все команды вводятся без префиксов mmd или marmelad.

Структура проекта

├─ marmelad
│  ├─ _blocks                   # блоки 
│  │   └─ some-block            # блок для примера 
│  │       ├─ some-block.html   # шаблон блока 
│  │       ├─ some-block.js     # скрипты блока 
│  │       ├─ some-block.styl   # стили блока 
│  │       └─ some-block.json   # данные блока 
│  ├─ _pages                    # страницы 
│  ├─ bootstrap                 # bootstrap, если нужен 
│  ├─ iconizer                  # SVG-иконки для SVG-спрайта 
│  │   ├─ colored               # цветные SVG-иконки 
│  │   └─ icons                 # монохромные SVG-иконки 
│  ├─ snippets                  # сниппеты BEML для редакторов 
│  ├─ static                    # статика для вёрстки 
│  ├─ styles                    # стили, styl или scss 
│  ├─ .editorconfig             # конфиг для редактора 
│  ├─ .tci                      # TCI команды marmelad 
│  ├─ data.marmelad.js          # глобальные данные 
│  └─ settings.marmelad.js      # настройки сборки 
└─ static                       # итоговая сборка

Шаблоны/Блоки

Шаблонизатор nunjucks
БЭМ именование в HTML обеспечивает posthtml-bem

Lagman

Предназначен для оптимизации сборки шаблонов HTML на больших проектах, с большим кол-вом страниц.

Lagman строит связи/зависимости страниц от блоков или блоков от страниц. Что позволяет шаблонизатору понимать для какой из страниц изменился блок, и пересобирать HTML только тех страниц, в которых он используется.

Для правильной работы модуля, требуется строгое следовние правилам сборки блоков и страниц.

Блок должен содержать разметку БЭМ, с обязательным атрибутом block:

<div block="block-name" mods="red">
  ...
</div>

Этот атрибут позволяет установить связь между страницей и блоком. В случае если этого атрибута нет в разметке блока, то, этот блок автоматичестки исключается из списка слежения за изменениями, и перестаёт запускать пересборку страниц в которых он используется.

Данные для шаблонов/блоков

Данные для блока доступны в шаблонах по ключу с названием блока (если файл данных для блока создан и хоть чем-то заполнен), либо из data.marmelad.js (глобальные данные). Названия/ключи собственных данных блока преобразуются в camelCase.

`incw` расширение

incw - это расширение позволяющее подключать шаблоны блоков с передачей в шаблон отдельных данных, без указания расширения файла блока.

{# ручная передача данных в шаблон #}
{% incw 'имя шаблона без расширения', {title: 'Example', subtitle: 'An example component'} %}
 
{# передача данных в шаблон из переменной #}
{% incw 'имя шаблона без расширения', app.lang %}

Данные переданные в incw доступны внутри шаблона по ключу _ctx.

{# подключение шаблона #}
{% incw 'avatar', { image: 'IMAGE URL', name: 'USERNAME'} %}
 
{# в шаблоне #}
<div block="incw-template">
  <img src="{{ _ctx.image }}" alt="">
  <span>{{ _ctx.name }}</span>
</div><!-- incw-template -->

Вложенные incw не получают _ctx родительского блока, только глобальные данные. Для передачи конкретных данных в вложенный incw необходимо передать данные явно для вкладываемого incw.

Сборка стилей

Сборка поддерживает stylus, scss, sass.

Post CSS плагины

Bootstrap

Сборка bootstrap включается в settings.marmelad.js настройкой app.bts.use: true, все файлы собираются в корне сборке, в директории bootstrap.

Bootstrap как донор

Сборка bootstrap как донор включается в settings.marmelad.js настройкой app.bts.donor: true, при этом app.bts.use должен быть в false.

В случае использования bootstrap как донора для сборки стилей, файлы скриптов bootstrap копируются в директорию сборки js/vendors. Файлы стилей уже встраиваются так как вы их настроете, т.е. изменение файлов стилей bootstrap запускает сборку основных стилей, не запуская отдельную сборку стилей для bootstrap.

Iconizer

Iconizer претерпел изменения в плане способах его подключения и использования в шаблонах.

Использование Iconizer

В шаблоне

{{ _icon('marmelad', { tag: 'span' }) }}

На выходе

<span class="svg-icon svg-icon--marmelad colored" aria-hidden="true" focusable="false">
  <svg class="svg-icon__link">
    <use xlink:href="#marmelad"></use>
  </svg>
</span>

Опции Iconizer

{{ _icon('<name>', {
  tag: 'div',
  type: 'icons',
  class: '',
  mode: 'inline',
  url: '',
}) }}

Функция icon из settings.marmelad.js -> iconizer передаётся в шаблонизатор nunjucks под именем _icon.

Типы SVG-спрайта

icons - монохромные иконки, вырезаются все лишние атрибуты оформления
colored - цветные иконки, вырезается только тег title

Пример использования цветной SVG-иконки

Для подключения цветной иконки необходимо добавить атрибут type="colored"

{{ _icon('marmelad', { type: 'colored' }) }}

Режимы подключения SVG-спрайта

inline - спрайт внедряется в HTML-код страницы
external - используется как отдельный файл, через обращение по URL его размещения

Миграция для Iconizer 5+

В settings.marmelad.js, необходимо удалить:

paths.iconizer
app.svgSprite

const paths = {
  // удалить
  iconizer: {
    ...
  },
};
 
const app = {
  // удалить
  svgSprite: {
    ...
  },
};

Добавить новый объект в settings.marmelad.js

const iconizer = {
  cssClass: 'main-svg-sprite',
  mode: 'inline', // external отдельный подключаемый файл спрайта (default:inline)
  dest: path.join(paths.dist, 'img'), // путь для собираемых спрайтов
  url: 'img', // путь до подключаемого спрайта iconizer.dest без paths.dist
  srcIcons: path.join(folders.marmelad, folders.iconizer.src, 'icons'),
  srcColored: path.join(folders.marmelad, folders.iconizer.src, 'colored'),
  icon: (name, opts) => {
    opts = Object.assign({
      tag: 'div',
      type: 'icons',
      class: '',
      mode: 'inline',
      url: '',
    }, opts);
 
    let external = '';
    let typeClass = '';
 
    if (opts.mode === 'external') {
      external = `${opts.url}/sprite.${opts.type}.svg`;
    }
 
    if (opts.type !== 'icons') {
      typeClass = ` svg-icon--${opts.type}`;
    }
 
    opts.class = opts.class ? ` ${opts.class}` : '';
 
    return `
      <${opts.tag} class="svg-icon svg-icon--${name}${typeClass}${opts.class}" aria-hidden="true" focusable="false">
        <svg class="svg-icon__link">
          <use xlink:href="${external}#${name}"></use>
        </svg>
      </${opts.tag}>
    `;
  },
  plugin: {
    mode: {
      symbol: { // symbol mode to build the SVG
        example: false, // Build sample page
      },
    },
    svg: {
      xmlDeclaration: false, // strip out the XML attribute
      doctypeDeclaration: false, // don't include the !DOCTYPE declaration
    },
  },
};

и не забыть добавить его в экспорт настроек

module.exports = {
  // добавить
  iconizer,
};

Задержка отдачи контента сервером `latencyRoutes`

В settings.marmelad.js app.bsSp необходимо добавить настройки для задержки отдачи сервером контента

// пример, для новых проектов по умолчанию задержка для /api
latencyRoutes: [
  {
    route: '/css',
    latency: 3000,
    active: true,
  },
],

Лицензия

MIT

Кодекс Поведения участника

Прочтите Кодекс Поведения участника

Логотип был взят и изменён, из набора иконок автора Jelly beans распространяемого под лицензией CC 3.0 BY с www.flaticon.com

В начало 🔝

marmelad

marmelad

Содержание

Внимание

Установка

Проблемы установки глобальных модулей для macOS и Linux

Установка из npm

Установка для разработчиков

Установка для определённого проекта

Marmelad CLI

init [options] инициализация

dev [options] старт сборки

cp <name> создание страницы

cb <name> [options] создание блока

mv <oldName> <newName> [options] переименование блока

lint W3C валидатор

dist релизные задачи

pack [name] [options] архивирование проекта

Marmelad TCI

Структура проекта

Шаблоны/Блоки

Lagman

Данные для шаблонов/блоков

incw расширение

Сборка стилей

Post CSS плагины

Bootstrap

Bootstrap как донор

Iconizer

Использование Iconizer

Опции Iconizer

Типы SVG-спрайта

Пример использования цветной SVG-иконки

Режимы подключения SVG-спрайта

Миграция для Iconizer 5+

Задержка отдачи контента сервером latencyRoutes

Лицензия

Кодекс Поведения участника

Readme

Keywords

Package Sidebar

Install

Repository

Homepage

DownloadsWeekly Downloads

Version

License

Unpacked Size

Total Files

Last publish

Collaborators

`init [options]` инициализация

`dev [options]` старт сборки

`cp <name>` создание страницы

`cb <name> [options]` создание блока

`mv <oldName> <newName> [options]` переименование блока

`lint` W3C валидатор

`dist` релизные задачи

`pack [name] [options]` архивирование проекта

`incw` расширение

Задержка отдачи контента сервером `latencyRoutes`

Weekly Downloads