Сведения о GitHub Pages и Jekyll

Сведения о Jekyll

Jekyll — это генератор статических сайтов со встроенной поддержкой GitHub Pages и упрощенным процессом сборки. Jekyll принимает файлы Markdown и HTML и создает полный статический веб-сайт на основе вашего выбора макетов. Jekyll поддерживает Markdown и Liquid, язык шаблонов, который загружает динамическое содержимое на вашем сайте. Дополнительные сведения см. в разделе Jekyll.

Jekyll для Windows официально не поддерживается. Дополнительные сведения см. в разделе Jekyll в Windows в документации по Jekyll.

Рекомендуется использовать Jekyll с GitHub Pages. При желании вы можете использовать другие генераторы статических сайтов или настроить собственный процесс сборки локально или на другом сервере. Дополнительные сведения см. в разделе Описание GitHub Pages.

Настройка Jekyll на вашем сайте GitHub Pages

Вы можете настроить большинство параметров Jekyll, таких как тема и подключаемые модули сайта, изменив файл _config.yml. Дополнительные сведения см. в разделе Настройка в документации по Jekyll.

Некоторые параметры конфигурации для сайтов GitHub Pages изменять нельзя.

lsi: false
safe: true
source: [your repo's top level directory]
incremental: false
highlighter: rouge
gist:
  noscript: false
kramdown:
  math_engine: mathjax
  syntax_highlighter: rouge

По умолчанию Jekyll не создает файлы или папки, которые:

• находятся в папке с именем /node_modules или /vendor;
• начинаются с _, . или #;
• заканчиваются на ~;
• исключены параметром exclude в файле конфигурации.

Если вы хотите, чтобы Jekyll обрабатывал какой-либо из этих файлов, можно использовать параметр include в файле конфигурации.

Титульный лист

Чтобы задать переменные и метаданные, такие как название и макет, для страницы или публикации на сайте, можно добавить титульный лист YAML в начало любого файла Markdown или HTML. Дополнительные сведения см. в статье "Титульный лист" в документации по Jekyll.

Вы можете добавить site.github в публикацию или на страницу, чтобы добавить на ваш сайт любые метаданные ссылок на репозитории. Дополнительные сведения см. в разделе Использование site.github в документации по метаданным Jekyll.

Themes

Вы можете добавить тему Jekyll на сайт GitHub Pages, чтобы настроить его внешний вид. Дополнительные сведения см. в разделе Темы в документации по Jekyll.

Дополнительные сведения см. в статье ](https://github.com/topics/jekyll-theme) "Поддерживаемые темы" на сайте GitHub Pages и "Добавление темы на сайт GitHub Pages с помощью Jekyll".

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

Подключаемые модули

Для расширения функциональных возможностей Jekyll на вашем сайте вы можете скачать или создать подключаемые модули Jekyll. Например, подключаемый модуль jemoji позволяет использовать эмодзи GitHub на любой странице сайта так же, как вы это делали бы в GitHub. Дополнительные сведения см. в разделе Подключаемые модули в документации по Jekyll.

GitHub Pages использует подключаемые модули, которые включены по умолчанию и не могут быть отключены:

• jekyll-coffeescript
• jekyll-default-layout
• jekyll-gist
• jekyll-github-metadata
• jekyll-optional-front-matter
• jekyll-paginate
• jekyll-readme-index
• jekyll-titles-from-headings
• jekyll-relative-links

Вы можете включить дополнительные подключаемые модули, добавив зависимость подключаемого модуля в параметр plugins в файле _config.yml. Дополнительные сведения см. в разделе Настройка в документации по Jekyll.

Список поддерживаемых подключаемых модулей см. в разделе Версии зависимостей на сайте GitHub Pages. Сведения об использовании для определенного подключаемого модуля см. в документации этого подключаемого модуля.

GitHub Pages не может создавать сайты с помощью неподдерживаемых подключаемых модулей. Если вы хотите использовать неподдерживаемые подключаемые модули, создайте сайт локально, а затем отправьте статические файлы сайта в GitHub Enterprise Server.

Выделение синтаксиса

Чтобы вам было удобнее читать сайт, фрагменты кода на сайтах GitHub Pages выделяются так же, как они выделяются в GitHub Enterprise Server. Дополнительные сведения о синтаксисе, выделенном на GitHub Enterprise Server, см. в разделе "Создание и выделение блоков кода".

По умолчанию блоки кода на сайте будут выделяться Jekyll. Jekyll использует средство выделения Rouge (которое совместимо с Pygments). Если в файле _config.yml вы укажете Pygments, вместо него будет использоваться Rouge. Jekyll не может использовать какое-либо другое средство выделения синтаксиса, и если вы укажете в файле _config.yml другое средство выделения синтаксиса, то во время сборки страницы получите предупреждение. Дополнительные сведения см. в разделе Сведения об ошибках сборки Jekyll для сайтов GitHub Pages.

Если вы хотите использовать другой элемент выделения, например highlight.js, необходимо отключить синтаксис Jekyll, обновив файл _config.yml проекта.

kramdown:
  syntax_highlighter_opts:
    disable : true

Если тема не содержит каскадные таблицы стилей для выделения синтаксиса, можно создать каскадные таблицы стилей выделения синтаксиса GitHub и добавить их в файл проекта style.css.

rougify style github > style.css

Локальное создание сайта

Если публикация выполняется из ветви, изменения на сайте публикуются автоматически при слиянии изменений в источнике публикации сайта. Если публикация выполняется с помощью пользовательского рабочего процесса GitHub Actions, изменения публикуются при каждой активации рабочего процесса (обычно за счет отправки в ветвь по умолчанию). Для предварительного просмотра изменений можно внести их локально, а не в GitHub Enterprise Server. Затем протестируйте сайт локально. Дополнительные сведения см. в разделе Локальное тестирование сайта GitHub Pages с помощью Jekyll.