baker example page template
1.0.0
Демонстрация того, как создавать и публиковать страницы с помощью инструмента сборки Baker.
Los Angeles Times использует Baker для создания статических страниц, публикуемых по адресу latimes.com/projects. Система Times опирается на частную версию репозитория, очень похожую на эту. В этом упрощенном примере промежуточные и рабочие версии публикуются в общедоступных корзинах Amazon S3.
Локальный тестовый сервер с постоянным обновлением
HTML-шаблоны с Nunjucks
Расширенный CSS с помощью Sass
Объединение JavaScript с Rollup и Babel
Импорт данных с помощью quaff
Динамическая генерация страниц на основе структурированных входных данных
Автоматическое развертывание каждой ветки в промежуточной среде при каждом push событии через GitHub Action.
Развертывание нажатием кнопки в производственной среде при каждом release с помощью GitHub Action.
Сообщения Slack, которые передают статус каждого развертывания через действие Github datadesk/notify-slack-on-build.
Node.js версии 12, 14 или 16, но не ниже 12.20, 14.14 или 16.0.
Менеджер пакетов узлов
мерзавец
После небольшой настройки вы можете использовать этот шаблон для простой публикации страницы. С помощью небольшой настройки вы можете сделать его так, как захотите. Это руководство познакомит вас с основами.
Создание новой страницы
Исследование репозитория
Доступ к активам
Доступ к данным
Динамические страницы
Развертывание
Глобальные переменные
Baker.config.js
Первый шаг — нажать кнопку GitHub «использовать этот шаблон», чтобы сделать копию репозитория для себя.
Вам будет предложено предоставить пул для вашего проекта. Как только это будет сделано, новый репозиторий будет доступен по адресу https://github.com/your-username/your-slug .
Затем вам нужно будет клонировать его на свой компьютер, чтобы работать с кодом.
Откройте терминал и перейдите в папку с кодом. Клонируйте проект в свою папку. Проект будет скопирован на ваш компьютер.
git clone https://github.com/your-username/your-slug
Если эта команда у вас не работает, возможно, ваш компьютер настроен по-другому, и вам необходимо клонировать его в репозиторий с помощью SSH. Попробуйте запустить это в своем терминале:
git clone [email protected]:ваше имя пользователя/ваш-slug.git
После завершения загрузки репозитория перейдите в свой-slug и установите зависимости Node.js.
установка npm
После установки зависимостей вы готовы просмотреть проект. Выполните следующую команду, чтобы запустить тестовый сервер.
запуск НПМ
Теперь перейдите по адресу localhost:3000 в вашем браузере. Вы должны увидеть шаблонную страницу, готовую для ваших настроек.
Альтернативный путь — создать новую страницу с помощью bluprint — инструмента командной строки, разработанного графическим отделом Reuters.
чертеж добавить https://github.com/datadesk/baker-example-page-template mkdir моя-новая-страницаcd моя-новая-страница начало чертежа страницы-примера-пекаря
Вот стандартные файлы и папки, которые вы найдете при клонировании нового проекта из нашего шаблона страницы. Работая с некоторыми файлами вы потратите больше времени, чем с другими, но полезно иметь общее представление о том, что они все делают.
Папка данных содержит соответствующие данные для проекта. Мы используем эту папку для хранения необходимой информации о каждом проекте — например, по какому URL-адресу он должен находиться. Здесь вы также можете хранить множество других типов данных, включая .aml , .csv и .json .
Файл meta.aml содержит важную информацию о странице, такую как заголовок, подпись, ярлык, дата публикации и другие поля. Его заполнение гарантирует, что ваша страница отображается правильно и может быть проиндексирована поисковыми системами. Полный список всех атрибутов можно найти в наших справочных материалах. Вы можете расширить это, включив в него столько опций, сколько захотите.
Эта папка, в которой хранится базовый шаблон нашего сайта и фрагменты кода, которые можно использовать повторно. Когда вы только начинаете, вы вряд ли что-то здесь поменяете. В более сложных случаях использования здесь можно хранить код, который повторно используется на нескольких страницах.
base.htmlФайл base.html содержит весь основной HTML-код, который можно найти на каждой создаваемой нами странице. Приведенный здесь пример является элементарным по своей конструкции. Вероятно, вам захочется включить в реальную реализацию гораздо больше.
Рабочая область — это место, где вы можете разместить все, что имеет отношение к проекту и не требует публикации в Интернете. AI-файлы, фрагменты кода, письменные тексты и т. д. Решать вам.
Он используется для хранения мультимедиа и других ресурсов, таких как изображения, видео, аудио, шрифты и т. д. Их можно перетащить на страницу с помощью static тегов шаблона.
В этой папке хранятся файлы JavaScript. Основной файл JavaScript называется app.js , в который вы можете напрямую писать свой код. Пакеты, установленные через npm можно импортировать и запускать, как любой другой скрипт Node.js. Вы можете создать в этой папке другие файлы для записи своего кода JavaScript, но вы должны убедиться, что файл загружается из app.js
Наши таблицы стилей написаны на SASS, мощном языке таблиц стилей, который дает разработчикам больше контроля над CSS. Если вам не нравится SASS, вы можете написать в таблицах стилей простой CSS.
Папка стилей состоит из таблицы стилей ( app.scss ), в которую вы можете добавить все свои стили в свой проект, хотя иногда вам может потребоваться создать дополнительные таблицы стилей и импортировать их в app.scss . Этот пример проекта включает только необходимый минимум для моделирования простого сайта. Вероятно, вам захочется начать с гораздо большего в реальной реализации.
В файле baker.config.js мы помещаем параметры, которые Baker использует для обслуживания и сборки проекта. Это было полностью задокументировано в другом месте этого файла. За исключением настройки domain , этот файл потребуется изменить только опытным пользователям.
Шаблон по умолчанию для вашей страницы. Здесь вы разместите свою страницу. Для создания HTML он использует систему шаблонов Nujucks.
Эти файлы отслеживают зависимости Node, используемые в наших проектах. Когда вы запустите npm install добавленные вами библиотеки будут автоматически отслеживаться здесь.
Это специальный каталог для хранения файлов, который GitHub использует для взаимодействия с нашими проектами и кодом. Каталог .github/workflows содержит действие GitHub, которое управляет нашими развертываниями для разработки. Здесь не нужно ничего редактировать.
Хранилища файлов в каталоге ресурсов оптимизируются и хэшируются в рамках процесса развертывания. Чтобы гарантировать сохранность ссылок на изображения и другие статические файлы, следует использовать тег {% static %} . Это гарантирует, что файл будет тщательно кэшироваться при публикации и что ссылка на изображение будет работать во всех средах. Вы захотите использовать его для всех фотографий и видео.
<цифра>
<img src="{% static 'assets/images/baker.jpg' %}" alt="Логотип Baker" width=200>
</фигура> Файлы структурированных данных, хранящиеся в вашей папке _data , доступны через теги шаблонов или JavaScript. В эту демонстрацию включен файл example.json чтобы проиллюстрировать возможности. Поддерживаются другие форматы файлов, такие как CSV, YAML и AML.
Файлы в папке _data доступны в ваших шаблонах под своим именем. Итак, с помощью _data/example.json вы можете написать что-то вроде:
{% для объекта в примере %}
{{ obj.year }}: {{ obj.wheat }}{% endfor %}Общей потребностью любого, кто создает проект в Baker, является доступ к необработанным данным в файле JavaScript. Часто эти данные затем передаются в код, написанный с использованием d3 или Svelte, для рисования графики или создания HTML-таблиц на странице.
Если данные, к которым вы обращаетесь, уже доступны по URL-адресу, которому вы доверяете, он останется активным, это легко. Но что, если это не так, и это данные, которые вы подготовили сами?
Вы можете получить доступ к записям в вашей папке _data. Единственное предостережение: работа по преобразованию этого файла в пригодное для использования состояние лежит на вас. Хорошая библиотека для этого — d3-fetch .
Чтобы создать URL-адрес этого файла понятным Бейкеру способом, используйте следующий формат:
import { json } from 'd3-fetch'; // первый параметр должен быть путем к файлу // второй параметр *должен* быть «import.meta.url»const url = new URL('../_data /example.json', import.meta.url);// Назовите это inconst data = await json(url); Другой подход — распечатать данные в шаблоне в виде тега script . Фильтр jsonScript принимает переданную ему переменную, запускает для нее JSON.stringify и выводит JSON в HTML в теге <script> с установленным в нем идентификатором, который вы передаете в качестве параметра.
{{ example|jsonScript('пример-данных') }}Как только это будет сделано, вы сможете получить JSON, хранящийся на странице, по идентификатору в вашем JavaScript.
// захватываем элемент jsonScript, созданный с использованием того же идентификатора, который вы передали inconst dataElement = document.getElementById('example-data'); // преобразуем содержимое этого элемента в JSON // делаем то, что вам нужно делать с «данными» !const data = JSON.parse(dataElement.textContent); Хотя метод URL-адреса рекомендуется, этот метод все же может быть предпочтительнее, если вы пытаетесь избежать дополнительных сетевых запросов. Он также имеет дополнительное преимущество: не требуется специальная библиотека для преобразования данных .csv в JSON.
Вы можете создать неограниченное количество статических страниц, передав источник структурированных данных в параметр createPages в файле baker.config.js . Например, этот фрагмент создаст страницу для каждой записи в файле example.json .
экспорт по умолчанию {
// ... все остальные параметры выше этого были исключены, чтобы подчеркнуть суть
createPages: createPages(createPage, data) {// Берем данные из папки _data. . Он находится в папке _layouts const template = 'year-detail.html'; // Устанавливаем URL страницы const url = `${d.year}`; // Устанавливаем переменные, которые будут переданы в контекст шаблона const context = { obj: d }; // Используем предоставленную функцию для рендеринга страницы createPage(template, url, context);}
},}; Это можно использовать для создания URL-адресов типа /baker-example-page-template/1775/ и /baker-example-page-template/1780/] с одним шаблоном.
Прежде чем вы сможете развернуть страницу, созданную этим репозиторием, вам необходимо настроить свою учетную запись Amazon AWS и добавить набор учетных данных в свою учетную запись GitHub.
Во-первых, вам нужно создать два сегмента в службе хранения S3 Amazon. Один из них предназначен для вашего промежуточного сайта. Другой — для вашего производственного участка. В этом простом примере каждый из них должен разрешить публичный доступ и быть настроен для обслуживания статического веб-сайта. В более сложной схеме, подобной той, которую мы используем в Los Angeles Times, корзины могут быть связаны с зарегистрированными доменными именами, а промежуточный сайт защищен от публичного просмотра с помощью схемы аутентификации.
Имена этих сегментов затем следует сохранить как «секреты» GitHub, доступные для действий, развертывающих сайт. Вам следует посетить панель настроек вашей учетной записи или организации. Начните с добавления этих двух секретов.
| Имя | Ценить |
|---|---|
BAKER_AWS_S3_STAGING_BUCKET | Имя вашего промежуточного сегмента |
BAKER_AWS_S3_STAGING_REGION | Регион S3, в котором был создан промежуточный сегмент. |
BAKER_AWS_S3_PRODUCTION_BUCKET | Название вашего производственного сегмента |
BAKER_AWS_S3_PRODUCTION_REGION | Регион S3, в котором был создан ваш производственный сегмент. |
Затем вам следует убедиться, что у вас есть пара ключей от AWS, которая позволяет загружать общедоступные файлы в ваши два сегмента. Значения также следует добавить к вашим секретам.
| Имя | Ценить |
|---|---|
BAKER_AWS_ACCESS_KEY_ID | Ключ доступа к AWS |
BAKER_AWS_SECRET_ACCESS_KEY | Секретный ключ AWS |
Действие GitHub, включенное в этот репозиторий, автоматически опубликует промежуточную версию для каждой ветки. Например, код, отправленный в main ветку по умолчанию, появится по адресу https://your-staging-bucket-url/your-repo/main/ .
Если бы вы создали новую ветку git под названием bugfix и отправили свой код, вы вскоре увидели бы новую промежуточную версию по адресу https://your-staging-bucket-url/your-repo/bugfix/ .
Прежде чем опубликовать свою страницу, вам следует определиться с окончательным URL-адресом. Это установит подкаталог в вашем сегменте, где будет опубликована страница. Эта функция позволяет The Times публиковать множество страниц в одном и том же сегменте, причем каждая страница управляется отдельным репозиторием.
Шаг первый — ввести URL-адрес вашего URL-адреса в файл конфигурации _data/meta.aml .
слаг: слаг вашей страницы
Никогда не будет плохой идеей убедиться, что ваша пуля еще не была поймана. Вы можете сделать это, посетив https://your-production-bucket-url/your-slug/ и убедившись, что он возвращает ошибку «страница не найдена».
Если вы хотите опубликовать свою страницу в корне корзины, вы можете оставить пустой фрагмент пустым.
слизняк:
Затем вы фиксируете изменения в файле конфигурации и убедитесь, что они отправлены в основную ветку GitHub.
git добавить _data/meta.aml git commit -m «Установить фрагмент страницы» git push origin main
Посетите раздел выпусков на странице вашего репозитория на GitHub. Вы можете найти его на домашней странице репо.
Проект нового релиза.
Там вы создадите новый номер тега. Хороший подход — начать с номера формата xxx, который соответствует стандартам семантического управления версиями. 1.0.0 — хорошее начало.
Наконец, нажмите большую зеленую кнопку внизу и отправьте релиз.
Подождите несколько минут, и ваша страница должна появиться по адресу https://your-production-bucket-url/your-slug/ .
Тестовый сервер Baker может вести журнал более подробно, начав со следующей опции.
DEBUG=1 запуск npm
Чтобы ограничить журналы запуском Baker:
DEBUG=пекарь:* запуск npm
Если ваша сборка не удалась, вы можете попробовать создать статический сайт самостоятельно локально через терминал. Если при построении страницы возникнут ошибки, они будут распечатаны на вашем терминале.
npm запустить сборку
Baker поставляется с набором глобальных переменных, которые одинаковы на каждой создаваемой странице, а также еще одним набором переменных, специфичных для страницы, которые устанавливаются на основе текущей создаваемой страницы. Вы можете использовать эти переменные для условного добавления контента на страницы или для фильтрации несвязанных данных на основе текущей страницы.
NODE_ENV Переменная NODE_ENV всегда будет иметь одно из двух значений: development или production . Это соответствует тому, какой тип сборки запускается на странице.
Когда вы запускаете npm start , вы находитесь в режиме development . Когда вы запускаете npm run build , вы находитесь в production режиме.
Это наиболее полезно для добавления элементов на страницы, только когда вы находитесь в режиме development .
{% if NODE_ENV == 'development' %}<p>Вы никогда не увидите это на действующем сайте!</p>{% endif %}DOMAIN Переменная DOMAIN всегда будет такой же, как опция domain , переданная в baker.config.js , или пустой строкой, если она не была передана.
PATH_PREFIX Переменная PATH_PREFIX всегда будет такой же, как опция pathPrefix переданная в baker.config.js , или одинарная косая черта ( / ), если она не была передана.
page.url URL-адрес текущей страницы относительно проекта. Будет включать pathPrefix , если он был указан в файле baker.config.js — другими словами, он будет учитывать все выполняемые пути проекта и указывать на правильную страницу в проекте.
page.absoluteUrl Абсолютный URL-адрес текущей страницы. При этом domain , pathPrefix и текущий путь объединяются в полный URL-адрес. В настоящее время это используется для вывода канонического URL-адреса и всех URL-адресов социальных тегов <meta> .
<link rel="canonical" href="{{ page.absoluteUrl }}">page.inputUrl Это путь к исходному шаблону, использованному для создания этой страницы, относительно каталога текущего проекта. Если у вас есть HTML-файл, расположенный по адресу page-two/index.html , page.inputUrl будет иметь имя page-two/index.html .
page.outputUrl Это путь к HTML-файлу, который был выведен для создания этой страницы, относительно папки _dist . Если у вас есть HTML-файл, расположенный по адресу page-two.html , page.outputUrl будет иметь page-two/index.html .
Каждый проект Baker, над которым мы работаем, включает в себя файл baker.config.js в корневом каталоге. Этот файл отвечает за передачу информации в Baker, чтобы он мог правильно построить ваш проект.
экспорт по умолчанию {
// каталог, в котором находятся ресурсы
активы: «активы»,
// создание страниц
createPages: неопределенно,
// каталог данных
данные: '_данные',
// дополнительный пользовательский домен, который будет использоваться при построении путей
домен: неопределенный,
// путь или набор путей каждой точки входа JavaScript
точки входа: 'scripts/app.js',
// общий входной каталог, обычно текущая папка
ввод: процесс.cwd(),
// где расположены макеты шаблонов, макросы и включения
макеты: '_layouts',
// объект с ключами и значениями глобальных переменных, которые будут
// передается во все шаблоны Nunjucks
nunjucksПеременные: не определено,
// объект ключа (имя) + значение (функция) для добавления пользовательских
// фильтруем по Нунджакам
nunjucksFilters: не определено,
// объект ключа (имя) + значение (функция) для добавления пользовательского
// теги нунджаков
nunjucksТеги: не определено,
// куда выводить скомпилированные файлы
вывод: '_dist',
// префикс, добавляемый в начало каждого разрешенного пути, как
// слизни работают
Префикс пути: '/',
// необязательный каталог для размещения всех ресурсов, используется редко
staticRoot: '',}; по умолчанию: ”assets”
Это сообщает Бейкеру, какую папку считать каталогом ресурсов. Скорее всего, вам не придется это менять.
по умолчанию: undefined
createPages — необязательный параметр, который позволяет динамически создавать страницы, используя данные и шаблоны проекта.
экспорт по умолчанию {
// …
// createPage — передать шаблон, выходное имя и контекст данных
//data - подготовленные данные в папке `_data`
createPages(createPage, data) {for (const title of data.titles) { createPage('template.html', `${title}.html`, {context: { title }, });}
},}; по умолчанию: ”_data”
Опция data сообщает Бейкеру, какую папку считать источником данных. Скорее всего, вам не придется это менять.
по умолчанию: undefined
Опция domain сообщает Baker, что использовать при создании абсолютных URL-адресов. bakery-template для этого параметра установлено значение https://www.latimes.com .
по умолчанию: ”scripts/app.js”
Параметр entrypoints сообщает Бейкеру, какие файлы JavaScript следует рассматривать в качестве отправных точек для пакетов сценариев. Это может быть путь к файлу или файловый glob, что позволяет создавать несколько пакетов одновременно.
по умолчанию: process.cwd()
Опция input сообщает Бейкеру, какую папку считать основным каталогом для всего проекта. По умолчанию это папка, в которой находится файл baker.config.js . Скорее всего, вам не понадобится ее устанавливать.
по умолчанию: ”_layouts”
Опция layouts сообщает Baker, где расположены шаблоны, включения и макросы. По умолчанию это папка _layouts . Скорее всего, вам не понадобится это устанавливать.
по умолчанию: undefined
Вы можете использовать nunjucksFilters для передачи собственных фильтров. В объекте каждый ключ — это имя фильтра, а значение функции — это то, что вызывается при использовании фильтра.
экспорт по умолчанию {
// ...
// передаем объект фильтров для добавления в Nunjucks
nunjucksFilters: {square (n) { n = +n; вернуть n * n;}
},} {{ значение|квадрат }} по умолчанию: undefined
Вы можете использовать nunjucksTags для передачи собственных тегов. Они отличаются от фильтров тем, что упрощают вывод блоков текста или HTML.
экспорт по умолчанию {
// ...
// передаем объект фильтров для добавления в Nunjucks
nunjucksTags: {doubler(n) { return `<p>${n}, удвоенное равно ${n * 2}</p>`;}
},}; {% значение удвоения %} по умолчанию: ”_dist”
Параметр output сообщает Бейкеру, куда поместить файлы при запуске npm run build run. По умолчанию это папка _dist . Скорее всего, вам не понадобится это устанавливать.
по умолчанию: ”/”
pathPrefix сообщает Baker, какой префикс пути добавлять к любым создаваемым URL-адресам. Если также передается domain , он будет объединен с pathPrefix при построении абсолютных URL-адресов. Обычно вы не устанавливаете это значение вручную — оно используется во время развертывания для создания URL-адресов с помощью фрагментов проекта.
по умолчанию: ””
Опция staticRoot предписывает Baker поместить все ресурсы в дополнительный каталог. Это полезно для проектов, которым необходимо иметь уникальные фрагменты на каждой странице без вложенности, что позволяет всем им совместно использовать статические ресурсы. Однако это особый случай, и для развертывания требуется специальная настройка. Не пытайтесь использовать это без уважительной причины.
