stacy
v2.0.0
Stacy — это генератор веб-сайтов, который объединяет контент из Contentful CMS с шаблонами Handlebars для создания страниц веб-сайта.
Стейси сопоставляет типы контента записей Contentful с шаблонами Handlebars в проекте вашего веб-сайта во взаимосвязи «один к одному» — для каждого типа записи, определенного в вашей модели контента, существует шаблон. С точки зрения Стейси, существует два типа записей: записи страниц и записи модулей . Запись страницы в сочетании с ее шаблоном создает единую страницу веб-сайта с уникальным URL-адресом. Записи модулей можно включать в страницы и другие модули с помощью полей ссылки Contentful для создания повторно используемых частей контента или просто для обеспечения структуры контента и шаблонов, разбивая ее на более мелкие части.
Что отличает Stacy от многих существующих генераторов статических веб-сайтов, так это то, что он поддерживает автоматическую публикацию веб-сайта в корзине S3 в облаке Amazon, откуда его можно обслуживать в Интернете. Стейси развертывает специальную инфраструктуру в Amazon Cloud, которую можно подключить к Contentful через функцию Webhooks. Когда контент обновляется в вашем Contentful пространстве, инфраструктура вашего веб-сайта, развернутая Стейси в Amazon Cloud, получает уведомление, автоматически восстанавливает и повторно публикует только те страницы вашего веб-сайта, на которые влияет обновление. Никакой ручной регенерации и повторного развертывания веб-сайта не требуется.
При использовании Stacy ваш веб-сайт представляет собой проект NPM, который обычно проверяется в репозитории git для контроля версий. Проект включает в себя ваши шаблоны Handlebars и статический контент (например, таблицы стилей CSS, изображения, используемые в дизайне веб-сайта, шрифты и т. д.), в то время как контент веб-сайта находится в контентном пространстве. В проекте веб-сайта разработчики веб-сайта используют инструмент командной строки Stacy для разработки, публикации и повторной публикации сайта. После публикации веб-сайта в Amazon Cloud авторы контента работают только с Contentful UI.
Подробное руководство/пошаговое руководство см. в разделе «Создание веб-сайта с помощью Stacy».
Во-первых, вам нужно достаточное пространство для контента вашего сайта. Получив это, вы можете создать новый проект для своего веб-сайта.
Убедитесь, что у вас установлен Node.js версии 10.16.3 или новее вместе с npm. Если вы собираетесь публиковать веб-сайт в облаке Amazon, вам также потребуется установить AWS CLI.
Начните с глобальной установки Stacy:
npm install -g stacy
В своем Contentful-пространстве перейдите в «Настройки пространства» → «Ключи API» и добавьте ключ API в токены доставки/предварительного просмотра контента . Обратите внимание на значения идентификатора пространства и токена доступа к API доставки контента , которые вы будете использовать для подключения среды Stacy к пространству Contentful.
Теперь вы можете создать первоначальный проект для своего сайта:
stacy new --cf-space <your space ID> --cf-access-token <your access token> mywebsite
Это создаст новый каталог проекта с именем «mywebsite» в текущем каталоге. Значение mywebsite называется идентификатором сайта . Используйте другое значение, идентифицирующее ваш веб-сайт. Значение должно соответствовать URL-адресу (маленькие буквы, цифры и тире).
В каталоге вашего проекта поместите статический контент в /static (он будет скопирован на ваш веб-сайт как есть) и поместите шаблоны записей в /templates . Имя файла шаблона (без расширения) должно точно соответствовать соответствующему типу контента записи в вашей модели Contentful Content . В /templates файлы шаблонов можно организовать в подпапках. Однако имена файлов должны быть уникальными во всех подпапках, поскольку они используются для уникального сопоставления шаблонов с типами содержимого входа (подпапки в /templates не играют никакой роли).
Примечание. Обычно шаблон в сочетании с содержимым записи создает HTML. Если вам нужно создать контент другого типа, вы можете добавить расширение к имени шаблона. Например, page.hbs создает HTML. Для создания обычного текста используйте page.txt.hbs . Это также означает, что page.hbs и page.html.hbs одинаковы.
Теперь вы можете запустить свой веб-сайт локально в целях разработки:
stacy serve
Вы можете увидеть свой сайт по адресу http://localhost:8080/ . После редактирования любого шаблона, статического контента или контента в Contentful просто перезагрузите страницу.
Чтобы остановить локальный веб-сервер Стейси, используйте Ctrl+C .
Запустите stacy --help чтобы увидеть другие доступные команды.
Содержимое каталога вашего проекта вы можете зарегистрировать в репозитории git, например GitHub или Bitbucket.
Внутри ваших шаблонов все поля ввода доступны по идентификатору поля , как определено в вашей модели контента . Вы можете ссылаться на них непосредственно в своем шаблоне. Например:
Это выведет значение поля caption записи. Обратите внимание, что здесь используется идентификатор поля , а не имя поля.
Стейси добавляет несколько специальных помощников, которые вы можете использовать в своих шаблонах:
module <reference field> — включает запись модуля, на которую ссылается поле Тип ссылки. Например, если у вас есть поле с идентификатором paragraphs и оно представляет собой список ссылок:
asset <asset field> — включите указанный ресурс, например изображение. Например:
В настоящее время поддерживаются только графические ресурсы, для которых отображается HTML-тег <img> .
assetSrc <asset field> — Получить URL-адрес актива. Например:
assetTitle <asset field> — Получить название актива. Например:
markdown <long text field> — отображать длинное текстовое поле Markdown. Например:
Обратите внимание на тройные скобки, необходимые здесь, потому что помощник генерирует HTML, который не нужно экранировать.
richText <rich text field> — отображает поле форматированного текста. Например:
Как и в случае с markdown , обратите внимание на тройные скобки.
json <field> — выводит внутреннее содержательное представление поля в формате JSON. Например:
Этот помощник может быть полезен для диагностики проблем.
Как упоминалось выше, между типами контента, которые вы определяете в модели контента и шаблонах вашего Contentful пространства, существует связь «один к одному».
Примечание. Строго говоря, у вас может быть более одного шаблона для данного типа контента, чтобы можно было создавать файлы разных типов для одной и той же записи контента. Например, для module идентификатора типа контента вы можете использовать шаблоны module.html.hbs и module.xml.hbs . Первый шаблон создаст HTML-файл для записи, а второй — XML-файл.
При определении типа контента обратите внимание на идентификатор API (также известный как идентификатор типа контента ). Файл шаблона для типа контента должен иметь то же имя (плюс расширение).
Существует одно требование к типам контента для записей страниц (в отличие от записей модулей): тип контента страницы должен определять обязательное поле ярлыка . Значение в поле будет определять имя сгенерированного файла, когда запись содержимого объединяется с соответствующим шаблоном. Например, если значением пула для записи страницы является «index», созданная страница будет «/index.html». Если ярлык «more/terms», страница будет «/more/terms.html». И так далее.
По умолчанию идентификатор поля для поля Slug должен быть slug . Идентификатор можно переопределить в файле stacy.json проекта. Помимо того, что поле ярлыка является обязательным в определении типа контента, также рекомендуется связать с ним пользовательский валидатор шаблона соответствия, чтобы обеспечить определенный формат значения поля. Регулярное выражение для валидатора может быть ^w[w-]*(/w[w-]*)*$ .
Когда вы будете готовы развернуть свой веб-сайт в AWS, вам сначала необходимо настроить инфраструктуру Stacy под своей учетной записью AWS. Прежде чем вы сможете это сделать, вам необходимо выполнить несколько шагов:
Создайте целевой сегмент S3. Здесь ваш веб-сайт будет опубликован и откуда он будет обслуживаться (вероятно, через CloudFront). Альтернативно вы можете использовать уже имеющуюся у вас корзину (Stacy также поддерживает публикацию в подпапке целевой корзины).
Если у вас его еще нет, создайте корзину S3, которую Стейси будет использовать для загрузки пакета функций Lambda издателя. Лямбда-функция издателя — это часть, которая реагирует на события публикации и отмены публикации Contentful и обновляет соответствующие страницы и ресурсы в целевой корзине S3.
Создайте пакет издателя:
stacy build-publisher
Это создаст пакет функции Lambda издателя в вашем проекте в /build/stacy-mywebsite-publisher.zip . Загрузите этот файл в корзину S3 функций Lambda.
stacy new создала шаблон CloudFormation для среды AWS и сохранила его в вашем проекте в папке /misc/cfn-template.json . При необходимости вы можете просмотреть и настроить его. В противном случае создайте стек Stacy для своего веб-сайта под своей учетной записью AWS.
После создания стека CloudFormation вам необходимо настроить политику целевого сегмента S3, чтобы разрешить издателю Stacy публиковать в нем сгенерированный контент веб-сайта. Политика корзины может включать в себя что-то вроде следующего:
{
"Version" : " 2012-10-17 " ,
"Statement" : [
{
"Effect" : " Allow " ,
"Principal" : {
"AWS" : " <Stacy publisher role ARN> "
},
"Action" : [
" s3:PutObject " ,
" s3:DeleteObject "
],
"Resource" : " arn:aws:s3:::<bucket name>/* "
}
]
} В приведенной выше политике замените ARN роли издателя Stacy на значение, которое вы можете найти в выходном параметре PublisherRoleArn стека CloudFormation, а имя корзины — на имя корзины целевого веб-сайта (корзины, к которой применяется политика).
Теперь вам нужно подготовить среду разработки к публикации. Откройте и отредактируйте файл .env в проекте вашего веб-сайта. В нем установите для всех переменных AWS_* правильные значения. Обратите внимание: значение переменной AWS_PUBLISH_EVENT_SOURCE_MAPPING можно найти в выходном параметре PublishEventSourceMappingId стека CloudFormation.
Как только ваш файл .env будет правильно настроен, вы сможете опубликовать свой веб-сайт, используя:
stacy publish
Последний шаг настройки — настроить веб-перехватчик в вашем контентном пространстве для вызова издателя Стейси при событиях публикации и отмены публикации . В своей учетной записи AWS в сервисе API Gateway найдите API, созданный для вас Стейси. На стадии prod API есть только один метод POST /publish . Обратите внимание на его URL-адрес вызова .
Кроме того, перейдите в раздел «Ключи API» и запишите значение ключа API, созданного для Стейси.
В вашем содержательном пространстве перейдите в «Настройки пространства» → «Вебхуки» и добавьте вебхук. Поместите URL-адрес вызова API Gatwey в поле URL-адреса (оставьте метод POST ). Затем выберите опцию «Выбрать конкретные триггерные события» в разделе «Триггеры» . Установите флажки «Опубликовать» и «Отменить публикацию» в строках «Запись» и «Актив» (всего отмечено 4 флажка).
В разделе «Заголовки» нажмите «Добавить секретный заголовок» . В поле «Ключ » укажите «X-API-Key», а в поле «Значение» укажите ключ API от API-шлюза.
Как только вы сохраните этот вебхук, публикация и отмена публикации записей и ресурсов в Contentful приведет к активации издателя в настройке AWS, и все готово!
