Инструкция по использованию - LiJanet/gmk GitHub Wiki

Разделы

Структура проекта
Установка программ для сборки
Исходники
Сборка
Репозиторий
Загрузка на хостинг

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

Основные ресурсы

Эти ресурсы хранятся в репозитории, изменения в них отслеживаются; каждый отслеживаемый ресурс хранит историю изменений, текущую версию, статус. Именно из этих файлов собирается конечный продукт.

src/ - исходники проекта (подробнее).
package.json - дескриптор модуля, там указываются имя модуля, версия, список необходимых вспомогательных модулей и другая служебная информация. Есть отличная демка.
gulpfile.js - центральный скрипт сборщика.
gulp/ - дополнительные плагины сборщика.
README.md - текст в формате Markdown, предназначен для описания содержимого репозитория. Именно его содержимое видно на главной странице под списком с файлами.
.gitignore - служебный файл репозитория, содержащий список игнорируемых ресурсов. Изменения в игнорируемых ресурсах никак не влияют на состояние репозитория, его версию, статус и т.д.

Производные/временные ресурсы

Эти ресурсы не хранятся в репозитории (все из них перечислены в .gitignore), т.к. являются результатом обработки основных.

node_modules/ - установленные вспомогательные модули для проекта. Несмотря на то, что необходимые модули устанавливаются автоматически, удалять эту папку не рекомендуется, т.к. количество модулей может быть весьма внушительным, и их пере-установка может занять некоторое время, или даже обернуться проблемами. Подробнее об установке.
tmp/ - временная промежуточная папка для сборки. Смело можно удалять, даже с запущенным на горячую сервером (только не прямо в тот момент, когда происходит сборка ;) ).
dist/ - конечная папка с собранным продуктом, после сборки здесь окажутся файлы, необходимые для загрузки на хостинг. Между циклами сборки можно не хранить.

Установка программ для сборки

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

Установка Node.js

Node.js - виртуальная машина для выполнения Javascript-кода, необходима для запуска скриптов сборки.

Пакет установки можно скачать здесь.

Для Windows/Mac установятся и сам node и его менеджер пакетов npm.
Для Ubuntu необходимо установить раздельно nodejs, его менеджер пакетов npm и пакет-зеркало для совместимости имен nodejs-legacy

sudo apt-get install nodejs
sudo apt-get install nodejs-legacy
sudo apt-get install npm

Проверить корректность установки можно командами

node -v
npm -v

Обе команды должны выдать вразумительный ответ без ошибок (номер используемой версии).

Установка git

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

Установщик можно скачать здесь. Ubuntu пользователи выполняют

sudo apt-get install git

Проверить корректность установки

git --version

Установка модулей проекта

Модули проекта находятся в управлении менеджером пакетов npm, и все операции по установке дополнительных модулей будут осуществлять с его помощью. Дополнительные модули проекта установятся непосредственно в его директорию согласно списку зависимостей из package.json, однако некоторые модули необходимо установить глобально на уровне системы, а именно node-gyp и gulp.

При установке любого модуля устанавливаются также и все модули, которые ему необходимы. Таким образом, устанавливаемый модуль может развернуться во внушительное дерево зависимых модулей. В процессе установки отображается индикатор прогресса, а по его завершении выдается отчет о списке установленных модулей (как раз в виде дерева), возможно со списком предупреждений WARN или ошибок ERR/ERROR. Установка модуля прошла успешно, если в отчете нет ошибок.

Установка `node-gyp`

sudo npm install node-gyp -g

или для пользователей Windows

npm install node-gyp -g

Установка `gulp`

Данный проект использует gulp версии 4.0, официально не имеющий собственного релиза (пора бы уже, с 2015 года), поэтому при установке явно указывается ветка с нужной версией

sudo npm install gulpjs/gulp#4.0 -g

или для пользователей Windows

npm install gulpjs/gulp#4.0 -g

Проверить установку

gulp -v

Установка остальных модулей

Важно! Остальные модули должны быть установлены непосредственно в папку проекта по списку, указанному в дескрипторе package.json. Разумеется, для этого уже нужны исходники проекта. Рекомендуется скачать их с помощью git.

Важно! Команда по установке модулей должна быть выполнена непосредственно в папке проекта, в ее корне.

npm install

Исходники

Все исходники проекта разделены на 4 категории

data/ - данные, используемые для наполнения страниц
templates/ - шаблоны страниц, а также общие фрагменты
css/ - стили страниц и отдельных фрагментов
img/ - картинки

Данные

Каждый файл данных преобразуется в страницу с тем же именем, расширением .html и тем же путем относительно папки data/ (страницы размещаются относительно корня). Все файлы данных имеют расширение .json и используют формат JSON.

TL;DR

JSON файл содержит структуру в виде объекта

{               // фигурные скобки
  "key": value  // двойные кавычки обязательны
}

или списка

[               // квадратные скобки
  value, value, value
]

key здесь - любая строка, ключ для получения значения. Во всех случаях value может быть

"строка"         // просто строка, двойные кавычки обязательны
123.5e+4         // число
true             // логическое значение true/false
null             // null-литерал ("ничего")
value            // любая другая структура JSON

Важным свойством JSON является рекурсивность, т.е. все структуры могут быть вложены друг в друга как угодно много раз.

Данные, хранимые в JSON, работают в тандеме с шаблоном, их отображающим. Взаимодействие построено на том, что шаблон ожидает наличие непустых значений в определенном формате на конкретных заранее договоренных ключах (key). Как правило, объект на конечной странице развернется в некоторую секцию, список развернется в последовательность секций или элементов, примитивное значение отобразится как есть на своем месте. Неизвестные (лишние) данные шаблон просто проигнорирует.

Пример файла данных `contacts.json`

{
    "template": "contacts",            // имя корневого шаблона
    "id": "contacts-page",             // id body-элемента
    "activeContacts": true,            // указание на активный пункт главного
    "title": "ГидроМонтажКомплект",    // заголовок страницы (вкладки в браузере)
    "contacts": [                      // список контактов
      {                                // 1-ый
        "type": "earphone",            // тип контакта, влияет на иконку
        "value": [                     // список значений
          "+375 29 1234567",
          "+375 17 2134567"
        ]
      }, {
          "type": "envelope",
          "value": "[email protected]"   // для одного значения список можно опустить
      }, {
          "type": "map-marker",
          "value": "г.Минск, ул.Тимирязева, д.72, корп.1"
      }
    ],
    "a": {                             // неизвестный ключ проигнорируется шаблоном
        "type": "pencil",
        "value": [
           "банк СуперМегаВклад",
           "код банка 743",
           "УНП 123456789",
           "р/с 9876543210987"
        ]
    }
}

Конкретно для страницы контактов тип контакта - прямо указанное имя иконки bootstrap, можно использовать любую из имеющихся. Рекомендуется использовать не более 4 секций контактов одновременно (при большем числе лишние будут переползать на новую строку).

Шаблоны

Этот проект использует шаблоны Mustache. По сути, это HTML со вставками для включения фрагментов. Шаблоны хранятся в папке templates/ с расширением .mustache.

Могут понадобиться изменения в файлах

head.mustache - добавление метаданных, дополнительных сторонних библиотек
main-menu.mustache - контакты в шапке сайта (не добавляйте больше 3), меню
footer.mustache - основной почтовый адрес, дублированное меню
map.mustache - карта на странице контактов. Для построения использован конструктор яндекс-карт, статическая версия карты.

Стили

Стили к страницам собираются из SASS исходников. Все файлы из папки css/ в итоге компилируются в CSS, склеиваются в один файл и ужимаются (точный порядок действий контролируется активным профилем)

Цветовая схема

Отдельного внимания заслуживает colors.scss. Этот файл задает цвета основных элементов сайта на основе трех базовых цветов.

$primary-color: #3F92D2;
$secondary-color: #4671D5;
$tertiary-color: #33CCCC;

Для подбора базовых цветов рекомендую https://colorscheme.ru/, на данный момент выбрана схема Аналогия в голубых тонах.

Картинки

В папке img/ хранятся все изображения сайта, включая логотип, баннеры, фоновые и тематические картинки. При записи ссылок на картинки как со страниц, так и в стилях используйте абсолютные пути (начинаются с /, например /img/banner.jpg).

Сборка

Сборка осуществляется с помощью модуля gulp. Основной скрипт сборки и плагины объявляют ряд задач, любая из которых может быть вызвана при запуске сборки. Команда сборки должна быть выполнена в корне проекта.

Некоторые наиболее важные задачи

gulp build      ; собирает в папку dist/ конечный продукт
gulp clean      ; очищает папки tmp/ и dist/
gulp rebuild    ; равносильна последовательному выполнению clean + build
gulp server     ; стартует локальный http-server на 8080 порту
gulp watch      ; после запуска отслеживания изменения в папке src/ тут же
                ; будут пересобираться в dist/
gulp            ; стартует задачу по умолчанию (зависит от набора выбранных профилей,
                ; на момент написания инструкции это rebuild + watch + server)

Описания профилей сборки, а также список текущих активных профилей находятся в файле gulp/config.json.

Репозиторий

Полную документацию по командам git можно найти здесь. Данная инструкция содержит минимальный набор для использования и синхронизации.

TL;DR

Все команды выполняются в корне проекта (за исключением команды скачивания)

Для скачивания репозитория локально

git clone "https://github.com/LiJanet/gmk" ваш/путь/к/папке/проекта

Для обновления из центрального репозитория в локальный

git pull

Для фиксации и сохранения локальных изменений в центральный репозиторий

git status                         ; отображает текущее состояние репозитория
git add *                          ; индексирует все измененные локально файлы
git commit -m "описание изменений" ; фиксирует индексированные изменения локально
git push                           ; сохраняет зафиксированное состояние в центральный
                                   ; репозиторий (потребуется аккаунт Git и соавторство)

Загрузка на хостинг

После сборки проекта готовый продукт будет содержаться в папке dist/. Как правило, загрузка на основной сервер заключается в доставке содержимого этой папки в соответствующую папку на сервере. Для популярных хостингов в РБ доставка производится посредством FTP (провайдер вашего хостинга должен предоставить все данные для доступа - имя пользователя, пароль, IP/адрес сервера), а папка на сервере обычно называется public_html/.

Подключение по FTP можно осуществить с помощью любого подходящего FTP-клиента.

для Windows рекомендую Total Commander
для Ubuntu рекомендую bareFTP

Изменения после загрузки могут отразиться не моментально, а с задержкой, связанной с кэшированием данных сайта. Как правило, данная задержка не превышает суток, а также провайдер хостинга может предоставлять механизм для очистки кэша.

Инструкция по использованию - LiJanet/gmk GitHub Wiki

Разделы

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

Основные ресурсы

Производные/временные ресурсы

Установка программ для сборки

Установка Node.js

Установка git

Установка модулей проекта

Установка node-gyp

Установка gulp

Установка остальных модулей

Исходники

Данные

TL;DR

Пример файла данных contacts.json

Шаблоны

Стили

Цветовая схема

Картинки

Сборка

Репозиторий

TL;DR

Загрузка на хостинг

Установка `node-gyp`

Установка `gulp`

Пример файла данных `contacts.json`