Jekyll – это генератор статических сайтов, который предлагает некоторые функции системы управления контентом (CMS), но при этом позволяет избежать проблем производительности и безопасности, которые бывают при использовании баз данных. Также Jekyll поставляется со специальными функциями для обработки контента, организованного по датам. Jekyll хорошо подходит для людей, которые часто работают офф-лайн, предпочитают использовать легкий редактор для поддержки контента и контроль версий для отслеживания изменений на сайте.
В первом мануале – Установка Jekyll и создание сайта в Ubuntu 16.04 – вы научились устанавливать Jekyll и его зависимости, создавать простой сайт в домашнем каталоге и открывать порт сайта в брандмауэре.
В этом мануале вы узнаете, как использовать автоматически сгенерированный контент и как Jekyll превращает исходные файлы в статический контент.
Требования
Чтобы работать с этим мануалом, нужно выполнить предыдущее руководство, Установка Jekyll и создание сайта в Ubuntu 16.04.
Домашняя страница
Начнем обзор с домашней страницы, которая собирается из четырех разных исходных файлов. Мы рассмотрим каждый из этих файлов по отдельности, чтобы понять, как они соединяются, чтобы создать статическую домашнюю страницу.
Если вы остановили веб-сервер разработки после выполнения первого мануала, запустите его снова:
cd ~/www
jekyll serve --host=203.0.113.0
Затем посетите сайт в веб-браузере. На домашней странице присутствуют следующие элементы:
- Your awesome title (настраивается в файле _config.yml)
- Posts (настраивается в index.html)
- Welcome to Jekyll! (настраивается в каталоге _posts/YYYY-MM-DD-welcome-to-jekyll.markdown)
- Subscribe via RSS (настраивается в index.html)
- About (отвечает файл about.md)
Настройки конфигурации: файл _config.yml
Одним из важных преимуществ Jekyll является возможность настраивать информацию, которая будет повторяться в нескольких местах на статическом веб-сайте, в одном исходном файле, _config.yml
По умолчанию _config.yml, созданный при запуске команды jekyll new, содержит пять параметров, которые отображаются на главной странице:
- title: Your awesome title
- email: your-e-mail@domain.com
- description: Write an awesome description for your new site here …
- twitter_username: jekyll
- github_username: jekyllrb
Эта информация автоматически включается во все остальные страницы и сообщения, которые вы создаете. Если вам нужно обновить один из этих параметров, вы можете внести все изменения в этот файл. Попробуйте сделать это.
Откройте файл в новом терминале:
nano ~/www/_config.yml
Укажите новые значения:
title: 8host Blog
email: 8host@8host.com
description: >
Welcome to my blog!
github_username: 8host
twitter_username: 8host
Оставьте url и baseurl без изменений на время разработки – их можно изменить при развертывании.
Чтобы увидеть изменения, внесенные в конфигурационный файл, необходимо остановить веб-сервер, нажав CTRL-C, а затем перезапустить его:
jekyll serve --host=203.0.113.0
Примечание: Убедитесь, что каждая строка в description имеет отступы, по крайней мере, в один пробел; иначе вы столкнетесь с ошибкой:
could not find expected ':' while scanning a simple key at line 19 column 1
Когда все будет готово, сохраните файл и выйдите из редактора. Затем перезагрузите страницу в браузере. В зависимости от настроек локального кэша браузера вам может понадобиться нажать Shfit+Reload, чтобы увидеть новые данные.
В файле _config.yml есть еще много настроек, но пока мы не будем их трогать и перейдем к следующему исходному файлу.
Страницы: файл about.md
Перейдите по ссылке About в правом верхнем углу. Изменения, внесенные в этот конфигурационный файл, будут отображаться выше и ниже основного контента About.
Текст, который находится по центру страницы, и ссылка в заголовке хранятся в файле about.md, который содержит четыре вида контента, они перечислены ниже.
1. Титульные элементы Jekyll
Блок в начале файла about.md, который начинается и заканчивается тремя штрихами, – это титульные элементы Jekyll. Это первое, что вы должны увидеть в файле. Этот раздел сообщает Jekyll, что файл должен быть проанализирован. Обычно он содержит YAML, но также он может быть пустым. Пустой раздел титульных элементов иногда полезно использовать для файлов CSS или других файлов, в которых не нужно устанавливать какие-либо значения, но необходимо получить доступ к переменным.
Страница About содержит такие титульные элементы:
---
layout: page
title: About
permalink: /about/
---
- Layout: макеты удаляют повторяющийся контент, такой как заголовки, футеры и меню, чтобы упростить работу с сайтами. Jekyll поставляется с тремя макетами: default, page и post. Каждый из них имеет особые характеристики. В этом случае «About» отображается в заголовке, потому что установлен макет page.
- Title: Помимо ссылки в навигации, title также используется в качестве видимого заголовка страницы, отформатированного с помощью тегов Heading 1 и в качестве <title> страницы (это текст, отображаемый в панели и в закладках браузера).
- Permalink: Jekyll автоматически создает каталоги и файлы HTML из исходных файлов, которые определяют URL-адрес страницы. Постоянная ссылка – permalink –позволяет переопределить поведение по умолчанию. В данном примере этот параметр вызывает URL-адрес страницы http://203.0.113.0:4000/about/, а не http://203.0.113.0: 4000 / about.html.
2. Отображаемый текст
Контент страницы идет после титульных элементов. Указанный здесь текст появляется на странице, например «This is the base Jekyll 3. theme».
3. Markdown
Markdown является частью содержимого главной страницы и контролирует формат контента. Для поддержки статического сайта он будет преобразовываться в HTML. Часто авторы контента предпочитают использовать Markdown, а не HTML, потому что его проще читать и писать.
4. Директивы шаблонов Liquid
Jekyll использует шаблонизатор Liquid для поддержки динамических элементов. Директивы Liquid отображаются между фигурными скобками:
{% include icon-github.html username="jekyll" %}
Давайте внесем некоторые изменения на этой странице, чтобы увидеть, как это повлияет сайт.
Изменение заголовка
Откройте файл и вместо About используйте заголовок About me:
nano ~/www/about.md
---
. . .
title: "About me"
. . .
---
Сохраните и закройте файл. Этот заголовок изменится везде, где он встречался на сайте.
Добавление новой страницы
Затем добавьте на сайт страницу Contact и используйте markdown, чтобы добавить изображение.
Начнем с создания каталога assets для хранения изображения:
mkdir ~/www/assets
Затем передайте изображение на нашу машину с помощью wget. Флаг -O направит его в созданный каталог. Флаг требует также указать имя файла:
wget -O ~/www/assets/postcard.jpg http://assets.8host.com/articles/jekyll-1604/postcard.jpg
Когда изображение будет на локальной машине, создайте новую страницу:
nano ~/www/contact.md
---
layout: page
title: "Send me a postcard!"
---
8host\\
Attn: 8host Blog\\
101 Avenue of the Americas\\
New York, NY 10013
Давайте подробнее рассмотрим markdown. Во-первых, двойной слеш в конце каждой строки инициирует возврат без дополнительного пробела. Во-вторых, изображение отображается с помощью символов ! [] (). Восклицательный знак указывает, что следующая ссылка является изображением. Квадратные скобки содержат альтернативный текст, который будет использоваться, если изображения не загружаются. Круглые скобки содержат ссылку на файл изображения. Узнать больше о стиле разметки Jekyll по умолчанию можно на веб-сайте kramdown.
Сохраните и закройте файл, затем перезагрузите страницу. Появится новая ссылка, где файлы упорядочены в алфавитном порядке.
С учетом новых файлов начало файловой структуры будет выглядеть так:
├── about.md
├── assets
│ └── postcard.jpg
├── _config.yml
├── contact.md
Вернитесь на домашнюю страницу, и на ней вы увидите новую ссылку в меню навигации.
Примечание: Обычно на странице контактов есть интерактивная веб-форма. Jekyll не предоставляет встроенной обработки формы, но вы можете использовать облачные сервисы, такие как Disqus, Formspree или FormKeep.
Записи: каталог _posts/YYYY-MM-DD-welcome-to-jekyll.markdown
Следуйте по ссылке Welcome to Jekyll, чтобы просмотреть образец записи в блоге.
Каталог _posts содержит файлы, названные по формату YYYY-MM-DD-Words-in-Title. Если файл поста не назван в этом формате, он не будет обрабатываться. Если имя файла содержит дату в будущем, страница не будет обрабатываться статическим сайтом. Используя в имени файла дату в будущем, вы можете настроить cron или другие средства автоматизации для публикации записей после определенной даты и времени. Файлы записей могут иметь расширение .markdown, .md, .html или другие расширения, если у вас установлены пользовательские преобразователи.
Запись начинается с титульных элементов. Они необходимы каждой записи, поскольку в них определяются важные параметры (например, дата).
---
layout: post
title: "Welcome to Jekyll!"
date: 2016-08-31 17:35:19 +0000
categories: jekyll update
---
- layout: макет записей очень похож на макет по умолчанию, хотя он может и отличаться. В разделе HTML <head> … </ head> отличается содержимое страницы, а также содержимое между тегами <div class = “wrapper”> … </ div>, но остальной код совпадает. Единственное очевидное отличие на этой странице – это автоматическое добавление значения даты под заголовком (в титульных элементах).
- title: заголовок отображается как Heading 1 в самом блоге и как Heading 2 на индексной странице.
- date: заданная здесь дата будет отображаться как на главной странице, так и в самой записи. Эта дата также определяет URL-адрес записи.
Примечание: Дата в титульных элементах не имеет прямого отношения к дате в начале имени файла. Имя файла должно начинаться с даты в правильном формате, чтобы его можно было проанализировать. Если в имени указана дата в будущем, файл не будет обрабатываться до этой даты. Между тем дата в титульных элементах определяет структуру каталогов после обработки файла и используется как значение, отображаемое на главной странице и в записи.
- categories: категории используются для группировки контента по темам. По умолчанию они не отображаются на странице, хотя их можно добавить к настраиваемому шаблону.
Остальные файлы
На данный момент мы подробно рассмотрели три файла: _config.yml, about.md и _posts/YYYY-MM-DD-welcome-to-jekyll.markdown. Ниже приведен краткий обзор файлов, работа которых не отображаются непосредственно в браузере:
- main.scss: Jekyll использует Sass, который он компилирует в обычный CSS при каждой сборке сайта. Файлы .sass хранятся в каталоге css.
- feed.xml: Jekyll использует RSS для того, чтобы разрешить сайтам агрегировать записи, а пользователям – подписываться.
- Gemfile и Gemfile.lock: Gemfile перечисляет плагины для Jekyll, установленные с помощью команды bundle.
Из этих четырех файлов только CSS влияет на представление контента. Если вас особенно интересуют Jekyll и Sass, посмотрите на этот пример.
Заключение
В этом мануале мы подробно рассмотрели стандартный контент Jekyll. Также теперь вы знаете, как объединяются исходные файлы для создания веб-страниц. Вы можете определять значения нескольких компонентов в одном файле. Также Jekyll позволяет динамически размещать записи на главной странице, поэтому вам не нужно вручную обновлять страницу, чтобы добавить новую запись.
В следующей части этой серии мануалов мы рассмотрим структуру файла статического сайта, как эта структура отражается в URL-адресах страниц и стандартных записей и как переопределить поведение Jekyll по умолчанию.