Создание статических сайтов с Jekyll

() translation by (you can also view the original English article)

Полномасштабная CMS редко бывает необходима. Иногда вам нужно создать всего лишь легкий, статический веб-сайт ... но у вас слишком много страниц, чтобы их постоянно копировать из шаблона в шаблон. Сегодня я продемонстрирую простое решение - Jekyll - он очень облегчит процесс создания небольших веб-сайтов.

Шаг 0: Встречаем Jekyll

Jekyll - простой, основанный на блогах, статический генератор сайта.

Jekyll - простой, основанный на блогах, статический генератор сайта. Об этом говорит нам официальный сайт. Но что именно это значит? Статический генератор сайтов - это программа, которая принимает набор файлов и генерирует ваш сайт с ними. Как вы увидите, мы сможем использовать набор шаблонов, создавать файлы контента отдельно, а затем использовать Jekyll для создания нашего сайта. Часть, посвященная блогу, означает, что мы можем использовать его для создания блога или любого веб-сайта, на котором есть серия каких-либо постов (например, портфолио). Давайте попробуем!

Шаг 1: Установка Jekyll

См. Дополнительную информацию о Ruby Gems.

Мы начнем с установки Jekyll; это gem Ruby, поэтому сделать это довольно просто.

1	gem install jekyll # use `sudo` if your setup requires it

Да, это так просто. Есть еще несколько штук, которые мы могли бы установить, если планируем сделать более сложную настройку, однако в нашем уроке этого не будет, поэтому двигаемся дальше.

Шаг 2. Создание нашего первого шаблона

Каждый файл или папка, которая не начинается с подчеркивания, будет скопирована на сгенерированный сайт.

Затем создадим папки для Jekyll. Создайте папку с именем example-app для этого урока; мы создадим небольшой портфолио для фотографа. Это отличный пример того, где Jekyll сияет: это небольшой сайт, который не будет обновляться слишком часто, но достаточно велик, чтобы вы не хотели открывать каждую страницу, когда вам необходимо будет внести изменения разметки.

Внутри example-app создайте папку с именем _layouts. Обратите внимание на подчеркивание в начале этой папки: любая папка или файл, начинающийся с символа подчеркивания, не будет частью сайта, создаваемого Jekyll. Если у них есть имя, которое распознает Jekyll (например, _config.yml или _layouts), их содержимое будет использоваться при генерации сайта, но сами файлы не будут отображаться на сайте. Помните: каждый файл или папка, которая не начинается с подчеркивания, будет скопирована на сгенерированный сайт (который, кстати, по умолчанию относится к подпапке _site).

Итак, давайте создадим макет. Мы начнем с общего макета сайта, который включает весь «хром» для нашего сайта. Создайте новый файл под именем default.html внутри папки _layouts (имя не имеет значения) и добавьте к нему следующий код:

<!DOCTYPE html>
<html>
<head>
  <meta charset=utf-8 />
  <title> {% if page.title %} {{ page.title }} | {% endif %} John Doe, Photographer </title>
  <link rel="stylesheet" href="/css/styles.css" />
</head>
<body>

  <div id="main">

    <header>
      <h1> John Doe Photograghy </h1>
    <header>

    <nav role="navigation">
      <ul>
        <li><a href="/">Home</a></li>
        <li><a href="/portfolio/">Portfolio</a></li>
        <li><a href="/about">About</a></li>
        <li><a href="/contact">Contact</a></li>
      </ul>
    </nav>

    {{ content }}

    <footer>
      <p>@copy; John Doe Photography 2011 | All Rights Reserved. </p>
    </footer>

  </div>
</body>
</html>

Здесь следует иметь в виду несколько вещей ...

Во-первых, Jekyll использует систему шаблонов Liquid (по умолчанию). Это означает, что все, что вы можете сделать с Liquid, вы можете сделать в шаблоне в Jekyll. Например, в теге <title> мы используем оба типа разметки Liquid: разметка вывода и разметка тега. Разметка вывода может выводить текст (если существует ссылка на переменную), в то время как разметка тега нет. Разметка вывода разделяется двойными фигурными скобками, а разметка тегов разделена фигурной фигурной скобкой / процентом.

Следующее, что нужно заметить выше, - это то, что находится внутри тегов Liquid: такие вещи, как page.title и content. Это переменные, предоставленные Джекилом; вы можете увидеть список доступных данных шаблона в документах. Мы также можем создавать пользовательские данные шаблона, как мы вскоре рассмотрим.

Наконец, обратите внимание на CSS, который мы используем: создаем папку css в корне вашего проекта и бросаем этот стиль в файл style.css:

body {
  font: 16px/1.5 verdana, helvetica-neue, helvetica, arial, san-serif;
  background: black;
  color: #ececec;
  padding: 0;
  margin: 0;
}
ul {
  margin: 0;
  padding: 0;
}
a {
  color: #ccc;
  text-decoration: none;
}

a:hover {
  color: #ececec;
  text-decoration: underline;
}

#main {
  width: 960px;
  margin: 0 auto;
  background: rgba(255, 255, 255, 0.4);
}
header {
  padding: 0 10px;
  overflow: hidden;
}
h1 {
  margin: 0;
}

nav ul, ul.entries {
  list-style-type: none;
}
nav li a {
  float: left;
  margin: 5px; 
}
.content {
  padding: 10px;
}

ul.entries li {
  position: relative;
  margin: 20px auto;
  padding: 20px;
  background: #ececec;
  width: 600px;
}

ul.entries img {
  width: 600px;
}

ul.entries li h3 {
  position: absolute;
  bottom: -18px;
  left: 17px;
  font-size: 2em;
}
ul.entries a {
  color: #ececec;
}
ul.entries a:hover {
  color: #fff;
}

footer {
  font-size: 0.65em;
  text-align: center;
}

Кроме того, создайте папку img и добавьте изображение с именем banner.jpg; мы будем использовать его в ближайшее время. И так же для любого изображения: просто обрезайте его до 960px на 300px ;.

Возможно, вам интересно, почему мы используем оператор if выше, если переменная page.title просто не отображается, если она существует? Ну, если он существует, я хочу включить в него вертикальную полосу; Другой способ написать это будет следующим:

1	{{ page.title }}{% if page.title %} \| {% endif %}

Итак, как мы используем этот шаблон? Ну, нам нужно создать страницу, которая будет использовать этот шаблон. В корневом каталоге нашего проекта создайте файл index.html. Вот его содержимое:

---
layout: default
---
<section role="banner">
  <img src="/img/banner.jpg" />
</section>

<section class="content">
  <p>
  Welcome to John Doe Photography! Please, check out my <a href="/portfolio/">Portfolio</a> to see my work.
  </p> 
</section>

Вот содержимое нашего файла index.html. Обратите внимание на то, что находится в верхней части файла: Jekyll называет это передним YAML. Любой файл (который не начинается с подчеркивания), который имеет переднюю грань YAML, будет создан Jekyll перед тем, как быть помещен в папку _site (если у него нет подчеркивания или YFM, тогда он будет просто скопирован в _site). В этом случае передняя часть YAML просто сообщает Jekyll, какой шаблон мы хотим использовать.

Теперь откройте терминал, cd в каталог вашего проекта и запустите jekyll. Вы должны увидеть что-то вроде этого:

1	WARNING: Could not read configuration. Using defaults (and options).
2	No such file or directory - /Users/andrew/Desktop/example-app/_config.yml
3	Building site: /Users/andrew/Desktop/example-app -> /Users/andrew/Desktop/example-app/_site
4	Successfully generated site: /Users/andrew/Desktop/example-app -> /Users/andrew/Desktop/example-app/_site

Проигнорируйте предупреждение; мы скоро придем к этому. Пока вы можете видеть, что сайт был создан в недавно созданном каталоге _site. Если вы открываете файл _site/index.html в своем браузере на выбор, вы должны увидеть ... сбой. Проблема в том, что наши пути (URL-адреса и таблицы стилей) начинаются с косой черты. Это означает, что мы не можем просто просматривать их как файлы, мы должны просматривать их на сервере. Конечно, вы могли бы начать W/MAMP, но зачем брать на себя труд? Jekyll имеет встроенный сервер. Итак, запустите jekyll --server и перейдите на localhost:4000, чтобы увидеть что-то вроде изображения ниже:

Если изображения выше недостаточно, посмотрите код _site/index.html. Вы увидите, что указанный нами шаблон был смешан с содержимым, которое мы предоставили, и-voila! - у нас есть наша страница.

Я хочу напомнить вам, что это первый блок YAML делает всю эту магию; если файл не начинается с тремя тире, одной или несколькими строками свойств и другой линией из трех тире, файл будет просто скопирован в папку _site, без генерации.

Шаг 3: Создание шаблона портфолио

Теперь, когда мы будем закончили с основами, давайте создадим портфолио для нашего вымышленного фотографа. Помните, как я заметил, что Jekyll «для блогов»? Итак, мы будем использовать эту функцию для работы с блогом: вместо постов у нас будут записи портфолио.

Сообщения находятся в папке, называемой _posts, поэтому создайте ее сейчас. Шаблон имени файла для сообщений также должен быть конкретным: year-month-day-title.ext. Сообщения - ну, любой файл на вашем сайте Jekyll, действительно - может быть либо Markdown, либо HTML.

Итак, давайте создадим несколько сообщений: помните, что это будут записи в нашем портфолио:

`_posts/2010-03-04-bikes.md`

---
layout: portfolio_entry
image: /img/bikes.jpg
title: Bikes, Black and White
---
Bikes are used by almost everyone in downtown Amsterdam. These ones are chained to a bike rack.

`_posts/2010-10-01-wing.md`

---
layout: portfolio_entry
title: Wing and a Prayer
image: /img/wing.jpg
---
The wing of the AirBus I rode to England.

`_posts/2011-06-05-bridge.md`

---
layout: portfolio_entry
title: Stone Bridge
image: /img/bridge.jpg
---
An old stone bridge in London.

`_posts / 2011-07-09-road.md`

---
layout: portfolio_entry
title: Road and Curb
image: /img/road.jpg
---
Bike lanes here are terribly thin.

Довольно просто, не так ли? Обратите внимание на то, как мы создаем пользовательское поле YAML: image. Это URL-адрес изображения для этой записи. Конечно, мы могли бы построить весь HTML-код в этом файле, но что, если мы хотим его изменить? Мы должны вернуться и изменить его в каждой записи. Таким образом, мы можем вместо этого использовать наш шаблон portfolio_entry для их рендеринга. Как выглядит этот шаблон? Это тоже довольно просто:

`_layouts/portfolio_entry.html`

---
layout: default
---

<h2 class="content">{{page.title}}</h2>

<img src="{{ page.image }}" />

{{ content }}

Если вы посмотрите на данные шаблона страницы, вы поймете, что любой пользовательский фронт, который мы добавим, будет доступен в page; поэтому здесь мы можем получить доступ к page.image. Мы также используем page.title и content (все после последней строки с тремя пунктами).

Я должен упомянуть здесь, что, хотя title сообщения должен быть доступен для объекта post, мне удалось заставить его работать с объектом page. Все работает!

Также обратите внимание, что у нас есть этот шаблон, используя наш макет default. Вы можете вкладывать шаблоны друг в друга таким образом.

Это дает нам наши страницы (публикации), но как насчет главной страницы портфолио? При написании нашей навигации в макете по умолчанию я отметил, что мы хотим, чтобы это было как /portfolio/. Итак, создайте папку, с именем portfolio в корневом каталоге, и откройте в ней файл index.html.

---
layout: default
title: Portfolio
---

<section class="content">
  <h2>Portfolio</h2>

  <p>Check out my images below!</p>
</section>

<ul class="entries">
  {% for post in site.posts %}

  <li>
    <a href="{{ post.url }}">
      <img src="{{ post.image }}" />
      <h3>{{ post.title }}</h3>
    </a>
  </li>

  {% endfor %}
</ul>

Это наша самая сложная часть. Помните, что это не шаблон: это «обычный» файл, но он все равно может содержать теги Liquid. Мы начинаем с установки layout в default и title в «Портфолио».

Обратите внимание, что в HTML у нас есть Liquid цикл for-in. Мы извлекаем все сообщения с сайта из sites.posts; затем, мы перебираем эти сообщения в цикле с помощью for post in site.posts / endfor. Если вы работали с WordPress или любой другой системой ведения блога, вы должны быть знакомы с концепцией loop. Вот и все! Внутри, как вы можете видеть, мы можем получить стандартные свойства, а также любые другие собственные данные, которые мы сами определили (например, image).

Теперь, если мы запустим jekyll --server для повторного создания сайта и запуска сервера, localhost:4000/portfolio/ должен отобразить это:

И вот страница входа:

Прекрасно! Вы создали портфолио. Я уверен, вы также видите, как это работает для блога. Давайте теперь перейдем к рассмотрению некоторых параметров конфигурации для Jekyll.

Шаг 4: Пишем файл конфигурации

Существует огромное множество вариантов для Jekyll. Замечательно, что у всех есть действительно разумные дефолты, но если вы хотите их изменить, это совсем не сложно.

Существует два способа установки параметров.

Во-первых, когда вы запускаете программу в командной строке, вы можете передавать параметры. Мы уже видели параметр --server, который запускает сервер после генерации сайта.
Другой способ - в файле конфигурации с именем _config.yml; это YAML файл, поэтому каждая строка представляет собой пару key:value, как и в случае с фронтом YAML. Jekyll будет искать этот файл перед созданием сайта.

Итак, создайте файл _config.yml, и давайте рассмотрим некоторые из наиболее распространенных опций.

Полный список параметров см. в документации по конфигурации.

auto: добавление auto: true в ваш конфигурационный файл заставит Jekyll следить за изменениями в вашей папке проекта и регенерации сайта «на лету».
source: Если исходные файлы находятся в другом каталоге, отличном от того, с которого вы запускаете Jekyll, вам нужно установить этот каталог в свойстве source.
destination: По умолчанию ваш сгенерированный сайт расположен в директории ./_site. Если вы хотите выбрать что-то другое, установите это здесь.
permalink: Постоянная ссылка - это путь к вашим сообщениям. По умолчанию это /year/month/day/title.html. Однако вы можете настроить это, если захотите. Среди прочих вы можете использовать переменные :year, :month, :day, :title и :categories. :categories исходят из фронта; все остальные относятся к имени файла поста. Затем вы можете установить permalink в такие значения, как /:year/:month/:title/ или /:categories/:title.html. Бонусный совет: если у вас есть свойство permalink в post front matter, оно переопределит значение по умолчанию для всего сайта.
exclude: Как я уже сказал выше, Jekyll не будет генерировать файлы в каталогах, которые начинаются с подчеркивания. Но если у вас есть папки, которые вы хотите игнорировать, но они при этом не начинаются с подчеркивания, вы можете сделать это с помощью exclude в вашем файле конфигурации.

Шаг 5: Развертывание сайта

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

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

Если у вас есть VPS или выделенный хостинг, вы можете сделать все более автоматически. Ознакомьтесь с документацией по развертыванию. Если вы не знаете, что делать, попробуйте следовать указаниям для использования git post-receive hook; Я пробовал их, и это довольно круто.

Шаг 6: Что делать дальше

Это только верхушка Джекила.

Существует плагиновая архитектура, позволяющая вам изменять способ создания вашего контента.
Больше всего вы можете сделать с Liquid и некоторыми Liquid расширениями, которые добавляет Jekyll.
Есть много данных о шаблонах, о которых мы не говорили. Проверьте это и посмотрите, что вы можете сделать!

Вывод

Ну, это ваше введение в Jekyll - простой, известный в блогах, статический генератор сайтов. В следующий раз, когда вы создадите сайт в стиле брошюры, визитная карточка, сайт микропортфолио, подумайте, что вы попробуете Jekyll? Дайте мне знать в комментариях и благодарим вас за чтение!