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

Jekyll — это генератор статических сайтов со встроенной поддержкой GitHub Pages.

Кто может использовать эту функцию?

GitHub Pages доступен в общедоступных репозиториях с GitHub Free и GitHub Free для организаций, а также в общедоступных и частных репозиториях с GitHub Pro, GitHub Team, GitHub Enterprise Cloudи GitHub Enterprise Server. Дополнительные сведения см. в разделе "Планы GitHub".

GitHub Pages теперь использует GitHub Actions для выполнения сборки Jekyll. При использовании ветви в качестве источника сборки GitHub Actions необходимо включить в репозитории, если вы хотите использовать встроенный рабочий процесс Jekyll. Кроме того, если GitHub Actions недоступен или отключен, добавление .nojekyll файла в корень исходной ветви будет обойти процесс сборки Jekyll и развернуть содержимое напрямую. Дополнительные сведения о включении GitHub Actionsсм. в разделе "Управление параметрами GitHub Actions для репозитория".

В этой статье

Сведения о 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.

Вы можете добавить поддерживаемую тему на свой сайт в GitHub. Дополнительные сведения см. в разделе "Поддерживаемые темы" на сайте GitHub Pages и "Добавление темы на сайт GitHub Pages с помощью Jekyll.

Чтобы использовать любую другую открытый код тему Jekyll, размещенную на GitHub, можно добавить тему вручную.{ % else %} Вы можете добавить тему на сайт вручную. Дополнительные сведения см. в статье [тем, размещенных на GitHub и "Добавление темы на сайт GitHub Pages с помощью Jekyll".

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

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

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

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

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

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

Tip

Вы можете убедиться, что вы используете последнюю версию всех подключаемых модулей, сохраняя данные GitHub Pages. Дополнительные сведения см. в разделе "Локальное тестирование сайта GitHub Pages с помощью Jekyll" и "Версии зависимостей" на сайте GitHub Pages.

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

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

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

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

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

kramdown:
  syntax_highlighter_opts:
    disable : true

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

rougify style github > style.css

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

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