- Вступление
- Монтаж
- Начиная
- Конфигурирование и структура
- _config.yml
- Front Matter
- Макеты и Включает
- Включает в себя
- Создание страниц
- Написание сообщений
- файлы
- Front Matter
- Индексирование сообщений
- Выдержки
- Темы
- Плагины и многое другое
- GitHub Pages 404 Page
- SASS / SCSS
- Подсветка синтаксиса
- Поисковая оптимизация (SEO)
- jemoji - Emoji со вкусом GitHub
- переадресовывать
- Трэвис CI
Поскольку в последние несколько месяцев я уделял много времени этому сайту, я подумал, что с тем же успехом могу поделиться своим опытом, чтобы другие тоже могли участвовать в нем! Вы можете просмотреть источник для этого сайта на GitHub репозиторий ,
Вступление
Джекил генератор статического сайта, написанный на Рубин , Он принимает серию шаблонов и статических файлов и выводит их в готовый каталог файлов. Для простых сайтов, таких как блог или портфолио, статический генератор сайтов идеален. Кроме того, с генератором, как Джекилл и его Жидкий шаблонизатор вы по-прежнему можете использовать многие мощные функции, такие как разметка, макеты, частичные и итерации по данным для создания файлов. В качестве дополнительного бонуса GitHub Pages может создать сайт Jekyll и разместить его, что делает его идеальным для личных и проектных сайтов и блогов.
Монтаж
Jekyll официально поддерживает Linux, Unix и macOS, хотя, кажется, вы можете получить его установить на Windows также.
Поскольку Jekyll написан на Ruby, вам потребуется установить Ruby. Apple поставляет теперь неподдерживаемую версию Ruby 2.0.0p648 на El Capitan, поэтому я установил последнюю версию Ruby (2.3.1) с Homebrew ( 
Доморощенный, я люблю хорошего менеджера пакетов). Я развернул этот сайт с помощью GitHub Pages, поэтому для начала я установил гем github-pages. Чтобы сохранить зависимости, создайте файл с именем Gemfile и добавьте следующее:
источник 'https://rubygems.org' gem 'github-pages'
Существует хороший инструмент под названием bundler, который управляет пакетами и средами для вас. Это рекомендуемый способ использования Jekyll (насколько я могу судить). Чтобы установить это и ваши зависимости проекта, запустите
gem install сборщик пакетов комплектация
Теперь все готово и готово начать строить свой сайт! Проверьте Документы по установке Jekyll для получения дополнительной информации.
Начиная
Вы можете либо создать все файлы самостоятельно, либо запустить следующее для создания нового сайта скаффолда:
Джекилл новый путь / к / каталог
Конфигурирование и структура
Чтобы создать свой сайт, запустите:
bundle exec jekyll build # build site bundle exec jekyll serve --livereload # построить сайт и обслуживать его, автоматически регенерируя при изменениях # доступ с http: // localhost: 4000 /
По умолчанию сайт построен на _site и получен из текущего каталога. Эти пути могут быть настроены в _config.yml или путем передачи флагов при запуске jekyll.
_config.yml
Для начала вам понадобится файл _config.yml для конфигурации и место для хранения глобальных переменных. Вот хороший стартовый пример для файла.
markdown: часовой пояс kramdown: Америка / Чикаго постоянная ссылка: / posts /: slug исключить: - README.md - .gitignore - Gemfile - Gemfile.lock - .sass-cache - CNAME - ЛИЦЕНЗИЯ
Уценка: линия kramdown говорит Джекиллу использовать kramdown как переводчик уценки.
Настройка часового пояса гарантирует, что даты, используемые по всему сайту, будут локализованы в желаемом часовом поясе, если Jekyll по умолчанию не использует UTC.
Настройка постоянной ссылки говорит Джекиллу, как маршрутизировать сообщения в блоге. По историческим причинам у меня есть мой в / posts /: slug. Вы можете отформатировать вашу постоянную ссылку, чтобы включить любую информацию, доступную на странице, т.е. передний вопрос или встроенные переменные. Проверять, выписываться Jekyll Постоянная ссылка документы для гораздо большей информации.
Параметр exclude говорит Jekyll игнорировать определенные файлы при создании сайта и не копирует их в каталог _site.
Front Matter
Фронтовая материя YAML блок между набором из трех пунктирных линий. Это как установить переменные уровня страницы и метаданные. Liquid добавит теги и переменные только в том случае, если файл содержит переднюю информацию. Ниже передняя тема из этого поста:
--- layout: post title: Как создать слаг для сайта Jekyll / Blog: how-to-make-jekyll-site-blog изменено: 2018-09-02 19:35 Описание CDT: руководство по созданию сайта на основе Jekyll / блог. автор: brian seo.type: изображение BlogPosting: как создать сайт Jekyll / блог ---
Переменные, включенные в предварительный текст или являющиеся стандартными для любой страницы или сообщения, могут быть доступны на странице с помощью движка шаблонов Liquid:
<h1> {{page.title}} </ h1>
Это довольно аккуратно, что еще вы можете сделать?
Хороший вопрос, я рад, что вы спросили!
{% assign author = site.data.authors [page.author]%} <p> Автор {{author.name}} в {{page.date | дата: "% B% -d,% Y"}} </ p>
Ого.
Что тут происходит? Для начала мы используем файл данных для хранения авторов. Это можно найти по адресу _data /hors.yml. Содержимое этого файла становится доступным для Liquid на сайте site.data.authors. Более подробную информацию о файлах данных можно найти на Jekyll файлы данных документы , Мы назначаем переменную author для site.data.authors [page.author]. page.author ссылается на передний вопрос, который решает Брайан. Так что теперь автор сохраняет все внутри объекта brian в _data /hors.yml. Внутри этого файла у нас есть:
Брайан: имя: Брайан Митчелл, био: «Веб-разработчик, любитель смайликов: wave: и страстный поклонник электронной музыки». твиттер: BrianMitchL граватар: 89e0d7d3d9370c45517960c8a12f92b9 веб: https://brianm.me
Доступ к информации можно получить так же, как если бы это было первым вопросом, что и делает {{author.name}} выше.
Как видно из приведенного выше примера, Liquid также может фильтровать данные. Здесь дата форматируется. Это только начало того, что может сделать Liquid, но это две вещи, которые я считаю действительно полезными. Проверьте другие фильтры и функции жидкости на Jekyll шаблоны документов ,
Если у вас есть файл, для которого вам не нужно объявлять какие-либо переменные, но вы хотите использовать Liquid, вы все равно должны использовать набор из трех штриховых линий, чтобы Jekyll обработал этот файл. Например, вот мой humans.txt файл:
--- --- / * TEAM * / Имя: {{site.data.authors.brian.name}} Twitter: @ {{site.data.authors.brian.twitter}} Расположение: Миннеаполис, Миннесота, США. / * СПАСИБО * / Имя: мама / * САЙТ * / Последнее обновление: {{site.time | date: "% Y /% m /% d"}} Язык: английский Тип документа: HTML5 Компоненты: Jekyll, UIkit, fontawesome, SCSS, GitHub Программное обеспечение: WebStorm, Safari, Photoshop
Для получения полного списка функций, ознакомьтесь с документами Jekyll на передний вопрос а также переменные ,
Макеты и Включает
Макеты
При написании страниц и сообщений вам не нужно отслеживать каждое вхождение навигационной панели или заголовка страницы. Это где макеты и включает в себя чрезвычайно полезны. Сохраните все макеты, которые вы используете в _layouts /. На моем сайте у меня есть файл _layouts / default.html, который более или менее содержит следующее:
{% raw%} <! DOCTYPE html> <html lang = "en"> <head> {% include head.html%} </ head> <body> {{content}} {% include footer.html%} < ! - некоторые теги сценариев и Google Analytics находятся здесь -> </ body> </ html>
Каждая страница, которую я так или иначе создаю, использует этот макет. Если бы я создал новую страницу, я включил бы следующее в ее предварительный текст, и содержимое этого файла было бы отображено в {{content}} макета по умолчанию:
Другой макет также может использовать макет. Его содержимое будет загружено в {{content}} его родительского макета.
Включает в себя
В приведенном выше макете у меня также есть {% include head.html%} и {% include footer.html%}. Они известны как включает (или частичные). Включает в себя файл, который может быть вставлен в любую страницу. Они идеально подходят для навигационной панели или нижнего колонтитула, где вы хотите, чтобы разметка была последовательной на всем сайте. Храните любые включения, которые вы используете в _include /. Вот часть моего кода nav.html:
{% assign url = page.url | remove: '/ index.html'%} {% для ссылки в site.navigation%} <li {% if url = = ссылка. url%} class = "uk-active" {% endif%}> <a href= "enjndom link.url} угл ."== enj∈ link.title} enj"> {{link.text}} </ a> </ li> {% endfor%}
Здесь я получаю URL с текущей страницы (при удалении нежелательных возможных имен файлов) и сохраняю его как URL. Далее я перебираю список словарей ссылок и строю список в HTML. Выполняя итерацию по этому списку, я проверяю, совпадает ли URL-адрес страницы с текущей ссылкой в цикле, и, если это так, задаю для класса элемента значение active, которое затем применяет другой цвет фона, указывая, что пользователь находится на указанном стр.
Создание страниц
Ваша домашняя страница должна иметь имя index.html (или index.md, если вы пишете ее в уценке) и располагаться на корневом уровне вашего проекта. Для любой другой страницы на корневом уровне вы можете создать файл так, чтобы заголовком файла был URL-адрес этой страницы. Например, если вы создадите файл по адресу /about.md, Jekyll сделает его доступным по адресу https://example.com/about.html (или example.com/about, если вы зададите постоянную ссылку: / about в начале файла). ). Если вы хотите иметь страницу в подкаталоге (или много подкаталогов ), укажите в этом подкаталоге желаемый путь URL, а затем вставьте в этот каталог файл index.html (или эквивалент уценки). Например, если бы я создал /this/is/a/test/index.html, я мог бы получить доступ к этой странице по адресу https://example.com/this/is/a/test.
Проверьте документацию Jekyll на создание страниц ,
Написание сообщений
Все сообщения находятся в соответствующем каталоге _posts.
файлы
Каждый пост - это его собственный файл, который должен иметь имя файла в формате:
ГГГГ-ММ-ДД представляет год, месяц и день публикации, заголовок - заголовок публикации. Я всегда указываю это в начале файла, и обычно устанавливаю свой собственный слаг и использую его для имени файла. MARKUP относится к расширению файла и формату файла. Вот несколько примеров имен файлов:
2016-05-29-tech-crew.md 2016-07-04-happy-независимости-day.html
Front Matter
В отличие от страниц, сообщение должно содержать переднюю тему. Мне нравится устанавливать более конкретную дату, а также заголовок, слаг, описание и, конечно же, какой макет я использую.
Индексирование сообщений
Итак, теперь у вас есть куча хорошо написанных и занимательных постов, но как вы показываете ссылки на них? Это довольно просто, вы можете использовать Liquid, чтобы перебирать свои сообщения, чтобы показать их в списке:
<ul> {% для поста в site.posts%} <li> <a href= "enj карваже post.url} enj"> {{post.title}} </a> </ li> {% endfor%} </ UL>
Если у вас много постов, обязательно ознакомьтесь с пагинация Плагин для отображения ваших сообщений на более чем одной странице.
Выдержки
По умолчанию первый абзац каждого сообщения доступен по адресу {{post.excerpt}}. Кроме того, вы можете установить свой собственный, включив переменную отрывка в заголовок вашего сообщения. Вы можете сконфигурировать отрывки еще больше, такие как установка excerpt_separator и фильтрация отрывка. Проверять, выписываться опубликовать выдержки для большего.
Темы
Jekyll поддерживает темы для всего сайта. Если вы используете команду jekyll new для создания скаффолдингового сайта, она будет использовать минимумы темы. Вы можете установить и заменить другие темы, установив гем для используемой темы и указав его в файле _config.yml. Для получения дополнительной информации об использовании и создании пакета темы, проверьте Jekyll тематические документы ,
Обратите внимание, что GitHub Pages поддерживает только тему минимума. Если вы хотите использовать что-то другое, вы должны свернуть свое собственное, связать весь исходный код в вашем проекте или использовать внешнее решение.
Плагины и многое другое
GitHub Pages поддерживает только ограниченный набор плагинов. Я расскажу о тех, которые я использую на этом сайте (большинство из которых поддерживает GitHub). Посмотреть жемчужина страниц зависимости для списка доступных плагинов.
GitHub Pages 404 Page
Если вы используете GitHub Pages для размещения своего сайта, вы можете создать свою собственную страницу ошибки 404. Вместо того, чтобы показывать посетителю вашего сайта стандартную страницу GitHub 404, вы можете создать свою собственную, которая соответствует вашему сайту. Обратите внимание, что это можно сделать, только если вы используете собственный домен, см. Страницу GitHub на Создание пользовательской страницы 404 для вашего сайта GitHub Pages для дополнительной информации.
Если это относится к вам, все, что вам нужно сделать, это создать файл 404.html или 404.md в корне проекта и добавить постоянную ссылку: /404.html в начало, и все готово!
SASS / SCSS
Чтобы добавить поддержку SASS / SCSS (что вам полностью следует 
), добавьте следующее в файл _config.yml:
sass: sass_dir: assets / css / _sass стиль: сжатые плагины: - jekyll-sass-конвертер
Установите sass_dir, где вы храните ваши файлы Sass / SCSS. Вы можете изменить стиль вывода на вложенный, расширенный, компактный, сжатый или полностью удалить его, чтобы сохранить все.
Проверьте Sass / SCSS документы ,
Вот что официальные документы говорят о нумерации страниц:
На многих веб-сайтах, особенно в блогах, очень распространено разбивать основной список сообщений на более мелкие списки и отображать их на нескольких страницах. Jekyll предлагает плагин для разбивки на страницы, так что вы можете автоматически генерировать соответствующие файлы и папки, которые вам нужны для нумерации страниц.
Так почему же нет? Чтобы добавить нумерацию страниц, добавьте следующее в ваш файл _config.yml:
paginate: 5 paginate_path: / blog / page /: num / plugins: - jekyll-paginate
Число страниц задает, сколько сообщений будет добавлено на каждую страницу. Имеет смысл показывать много, если вы показываете только заголовок и ссылку, но меньше, если вы показываете все содержимое каждого поста на одной странице. Строка paginate_path устанавливает способ формирования путей / URL-адресов страниц. Примечание: страница / blog не может иметь постоянную ссылку для нумерации страниц. Чтобы обойти это, я создаю каталог блогов и размещаю там свою страницу: blog.html → blog / index.html.
Чтобы обновить страницу, просто замените цикл сообщений на {% для сообщения в paginator.posts%}. Чтобы показать соответствующие кнопки «предыдущий / следующий», я рекомендую проверить Документы по пакинации Jekyll ,
Подсветка синтаксиса
Прежде чем вы сможете использовать подсветку синтаксиса, вы должны добавить несколько вещей в ваш файл _config.yml:
подсветка: рум kramdown: syntax_highlighter: плагины руж: - руж
Это устанавливает румяна для подсветки синтаксиса. Jekyll также поддерживает подсветку Pygments, но GitHub Pages - нет, поэтому я буду говорить только о Rouge в этом посте. Kramdown: список настраивает kramdown, конвертер уценки.
Чтобы использовать синтаксическое выделение на вашем сайте, вы можете использовать настройку по умолчанию или использовать обратные пометки GitHub Flavored Markdown для обозначения блока кода. По умолчанию: используйте {% highlight python%}, за которым следует некоторый приятный код Python, закрытый с помощью {% endhighlight%}.
При создании сайта rouge будет выполнять поиск по блоку кода и добавлять теги span с классами на части кода. Эти теги могут быть стилизованы под разные цвета, отсюда и подсветка синтаксиса. Я был большим поклонником темы Даркулы в JetBrain, поэтому я адаптировал версию из https://smasue.github.io/pygments-darcula использовать на этом сайте. Вы можете найти код в _darcula.scss , Будет работать любая CSS-тема Rouge или Pygments. Вы можете создавать CSS-файлы из Pygments или загружая темы, например, из https://github.com/richleland/pygments-css/ ,
Поисковая оптимизация (SEO)
Смешно легко получить довольно хороший SEO с Jekyll. Плагин jekyll-seo-tag выполняет почти всю тяжелую работу, чтобы правильно создавать правильные метатеги (описание, открытый график, твиттер-карту) и заголовок. Все, что действительно требуется, - это обязательно установить некоторые переменные в _config.yml, не забудьте указать заголовок и описание в заголовке страницы или поста и включить {% seo%} в заголовок вашей страницы. Ниже то, что я добавил в свой файл _config.yml:
плагины: - jekyll-sitemap - jekyll-seo-tag # seo title: описание Брайана Митчелла: публикации в блогах, проекты, присутствие в социальных сетях и многое другое! url: https://brianm.me твиттер: имя пользователя: BrianMitchL facebook: app_id: издатель: admins: логотип: /assets/images/BM-Logo.png социальный: имя: Брайан Митчелл ссылки: - https://github.com / BrianMitchL - https://facebook.com/BrianMitchL - https://twitter.com/BrianMitchL - https://plus.google.com/+BrianMitchell16/ - https://www.instagram.com/BrianMitchL - https : //www.last.fm/user/bman4789 - https://www.linkedin.com/in/brianscottmitchell - https://open.spotify.com/user/1237277662 - https://soundcloud.com/bman4789 - https://steamcommunity.com/id/MagicBriBri - https://vine.co/bman4789 - https://www.youtube.com/user/bman112234 - https://www.snapchat.com/add/bman4789 google_site_verification: 4-mwXA7aYqZalRm3UuWpPv-aMyFT_zUtA_ks_RK7r5I
Название, описание, логотип и URL-адрес используются в качестве параметров по умолчанию для всего сайта. Jekyll вычисляет URL-адрес каждой страницы для вас, поэтому не беспокойтесь об установке этого параметра для каждой страницы. Используйте твиттер для настройки учетной записи Twitter вашего сайта. Это будет использоваться для поля twitter: site. В сообщении с отдельным автором не забудьте указать автора в начале статьи имя пользователя автора в Twitter. Вы также можете установить автора как объект с полем twitter, как показано в _data / _authors.yml. Установите соответствующие поля facebook, если вы хотите отслеживать свои акции и страницу с помощью приложения facebook.
Социальный раздел используется для создания карты сайта в поисковых системах. Введите название веб-сайта / человека / компании, а затем список других официальных страниц. Установите строку google_site_verification с ключом подтверждения сайта Google для веб-мастеров, чтобы он был вставлен в виде мета-тега.
На любой странице или посте вы можете определить переменную seo.type. Это использует schema.org типы, чтобы определить, какой тип контента на странице.
Обязательно добавьте jekyll-sitemap в ваш _config.yml.
Оттуда все, что вам нужно сделать, это добавить {% feed_meta%} в заголовок вашей страницы. Это создаст файл с именем sitemap.xml, который будет ссылаться на каждую страницу вашего сайта. Это поддерживает индекс вашего сайта, который помогает поисковым системам найти все.
jemoji - Emoji со вкусом GitHub
Как обычно с плагинами, добавьте jemoji в ваш файл _config.yml.
Этот плагин позволит вам вставлять Emojis со вкусом GitHub в ваши страницы и посты. Например:
будет производить: 
переадресовывать
Добавьте jekyll-redirect-from в ваш файл _config.yml.
плагины: - jekyll-redirect-from
Этот плагин позволяет вам давать вашим страницам и публиковать несколько URL-адресов. Перенаправления выполняются путем создания новых файлов HTML с метатегом HTTP-REFRESH, указывающим на текущую страницу. Чтобы использовать, добавьте переменную redirect_from в начало страницы. Он принимает строку или список строк. Если установлено несколько redirect_froms, будет использоваться только первый.
redirect_from: / contact redirect_from: - / contact - / other-sites
Трэвис CI
Из того, что я нашел, лучший способ протестировать ваш сайт Jekyll - использовать gem html-proofer. Этот пакет будет просматривать ваш сайт сборки на наличие ошибок HTML. Чтобы настроить это, добавьте следующее в ваш _config.yml:
Также добавьте следующее в ваш Gemfile:
Это происходит из-за драгоценных камней комплектации Travis CI в каталоге поставщиков. Затем создайте файл .travis.yml и включите в него следующее:
sudo: false язык: ruby кеш: bundle rvm: - скрипт 2.5.1: - комплектация exec jekyll build - комплектация exec htmlproofer ./_site --disable-external --assume-extension env: global: - NOKOGIRI_USE_SYSTEM_LIBRARIES = true
Флаг --disable-external отключает проверку сторонних ссылок. Некоторые веб-сайты блокируют скребки, такие как тот, который используется в html-proofer, что приведет к сбою проверки, так что это просто пропускает все. Флаг --assume-extension предполагает, что href like / about такой же, как about.html. Для более подробной информации, проверьте Документация Jekyll по непрерывной интеграции ,
Обновление 2018-09-02: я реорганизовал это, чтобы использовать Rakefile и сказать Travis CI, чтобы использовать это (см. .travis.yml ). У меня были проблемы с сопоставлением URL-адресов с помощью html-корректора с дефисом в них, и мне нужно было использовать конфигурацию url_swap, которую, как мне казалось, было проще настроить в Rakefile.
Что тут происходит?Так почему же нет?