Публикация в GPM¶

Когда вы создали новую тему и хотите добавить её в репозиторий Grav, чтобы её можно было установить через GPM и админку, нужно учесть несколько стандартных требований. Эта страница состоит из двух частей: сначала публикация самой темы в GPM, затем поставка скелета — полного демонстрационного сайта, готового к распаковке и построенного вокруг вашей темы. Если вы публикуете плагин, см. версию этой страницы для плагинов.

Часть 1: Публикация темы¶

Требования к теме¶

Правильная тема Grav требует определённых файлов, чтобы работать должным образом, быть указанной в репозитории Grav и отображаться в админке Grav. Убедитесь, что ваша тема содержит все эти файлы:

• yourtheme.php — PHP-файл темы, имя которого должно совпадать с именем папки
• yourtheme.yaml — файл конфигурации темы, содержащий параметры и информацию о наследовании потоков
• blueprints.yaml — файл определения темы и файл определения формы
• CHANGELOG.md — файл изменений в правильном формате Grav для единообразного отображения
• README.md — обязательный файл для описания и предварительного просмотра темы
• LICENSE — файл лицензии, вероятно MIT, если совместим с ядром Grav
• screenshot.jpg — большое изображение-превью темы в соотношении 1:1
• thumbnail.jpg — уменьшенное изображение-миниатюра темы в соотношении 1:1
• languages.yaml (необязательно) — файл определения языка

Скриншот и миниатюра¶

В отличие от плагинов, которые представлены иконкой Font Awesome icon: в их схеме, темы — визуальные продукты, и их представляют настоящие изображения. Оба файла должны быть в формате JPG с точно такими именами и находиться в корне темы:

• screenshot.jpg — полноразмерное превью, показываемое на странице загрузок getgrav.org и в подробном представлении темы в админке. Соотношение сторон должно быть 1:1, а размер — не менее 800px x 800px; официальные темы и скелеты Team Grav поставляются с размером 1000px x 1000px.
• thumbnail.jpg — уменьшенное изображение, используемое в сетке списка тем в админке. Оно также должно иметь соотношение сторон 1:1 и размер около 300px x 300px; официальные пакеты поставляются с размером 500px x 500px для чёткого отображения на дисплеях с высоким DPI.

Файл blueprints.yaml¶

Файл blueprints.yaml в корне темы — то, что читают GPM и админка, чтобы представить вашу тему. Реальный пример из темы Quark2:

name: Quark 2
slug: quark2
type: theme
version: 1.1.10
description: The modernized Grav default theme — Blades CSS foundation, with light/dark/auto mode.
icon: meteor
author:
  name: Team Grav
  email: devs@getgrav.org
  url: https://getgrav.org
homepage: https://github.com/getgrav/grav-theme-quark2
demo: https://demo.getgrav.org/blog-skeleton
keywords: quark2, theme, modern, fast, responsive, html5, dark-mode
bugs: https://github.com/getgrav/grav-theme-quark2/issues
license: MIT
compatibility:
  grav: ['1.7', '2.0']
dependencies:
  - { name: grav, version: '>=1.7.0' }

Поля name, slug, type, version, description, author и license обязательны для листинга в GPM. Полный справочник полей, включая раздел form:, определяющий параметры конфигурации темы в админке, см. в схемах.

Процесс выпуска¶

Когда тема готова к добавлению в репозиторий, пройдите этот контрольный список:

1. Открытый исходный код с файлом LICENSE, предоставляющим лицензию, совместимую с MIT. Пример здесь
2. Содержит файл README.md с описанием функциональности и инструкциями по установке и настройке. Пример здесь
3. Содержит файл blueprints.yaml со всеми обязательными полями. Пример здесь
4. Предоставляет CHANGELOG.md в правильном формате. Пример здесь
5. Указывает соответствующую атрибуцию, если вы используете другие библиотеки, скрипты или код.
6. Создайте релиз готовой темы. Система репозитория Grav требует релиз и не найдёт вашу тему, если нет релиза, содержащего всё перечисленное.
7. Добавьте issue в трекер Grav с подробностями о теме, и мы быстро проверим её работоспособность, после чего добавим. Обратите внимание: этого не нужно делать, если вы выпускаете новую версию темы, которая уже есть в репозитории. Она будет подхвачена автоматически.

Формат списка изменений¶

Сайт GetGrav.org использует собственный формат ChangeLog, написанный в стандартном Markdown, но который можно обработать простым CSS и отобразить в привлекательном виде. Чтобы ваши ChangeLog корректно разбирались и форматировались, используйте этот синтаксис:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

# X.Y.Z
## 2015-01-01

1. [](#new)
    * New features added
    * Another new feature
2. [](#improved)
    * Improvement made
    * Another improvement
3. [](#bugfix)
     * Bugfix implemented
     * Another bugfix

...repeat...

Каждый раздел #new, #improved, #bugfix необязателен; включайте только нужные разделы.

Демонстрационный контент¶

Вы можете предоставить демонстрационный контент как часть пакета темы. Это значит, что всё, что находится в папке _demo/, будет скопировано в папку user/ в процессе установки. Так можно предоставить страницы, конфигурацию или что угодно ещё, что находится в папке user/. Пользователю будет предложено сделать это, и это совершенно необязательно.

Обратите внимание: демонстрационный контент не копируется при установке темы через админку.

Часть 2: Поставка скелета¶

Скелет Grav — это готовый образец сайта всё в одном: полная папка user/ — страницы, конфигурация, ваша тема и необходимые плагины, — которая упаковывается вместе с ядром Grav в один zip, который можно просто распаковать в действующий сайт. Если демонстрационный контент (часть 1 выше) — это лишь вкус вашей темы, то скелет — полноценное блюдо, и это, безусловно, лучший способ для людей увидеть вашу тему именно такой, какой вы её задумали. Скелеты перечислены в репозитории Grav вместе с плагинами и темами.

Требования к скелету¶

Репозиторий скелета — это по сути папка user/ действующего сайта Grav с несколькими упаковочными файлами в корне:

• .dependencies — файл, определяющий зависимости темы и плагинов для этого скелета
• blueprints.yaml — файл определения скелета с теми же полями GPM, что у темы (name, slug, version, description, author, license и т. д.)
• CHANGELOG.md — файл изменений в правильном формате Grav для единообразного отображения
• README.md — обязательный файл для описания и предварительного просмотра скелета
• LICENSE — файл лицензии, вероятно MIT, если совместим с ядром Grav
• screenshot.jpg — превью скелета с соотношением сторон 1:1, те же правила размера, что для тем
• thumbnail.jpg — миниатюра с соотношением сторон 1:1, те же правила размера, что для тем
• pages/, config/, accounts/, data/ — фактический контент и конфигурация сайта

Официальный Blog Site Skeleton — канонический образец для Grav 2.0: он включает тему Quark2 и стек Admin Next и является лучшей отправной точкой для копирования.

Файл .dependencies¶

Файл .dependencies сообщает инструментам сборки, какие тему и плагины включить в пакет. У каждой зависимости есть запись git: (откуда брать и куда размещать) и соответствующая запись links: (используется для символьных ссылок в процессе разработки). Ваша тема — просто ещё одна зависимость:

git:
    quark2:
        url: https://github.com/getgrav/grav-theme-quark2
        path: user/themes/quark2
        branch: develop
    breadcrumbs:
        url: https://github.com/getgrav/grav-plugin-breadcrumbs
        path: user/plugins/breadcrumbs
        branch: develop
links:
    quark2:
        src: grav-theme-quark2
        path: user/themes/quark2
        scm: github
    breadcrumbs:
        src: grav-plugin-breadcrumbs
        path: user/plugins/breadcrumbs
        scm: github

Сборка пакетов с помощью Skeleton Builder¶

Вам не нужно собирать zip-файлы вручную. Официальный GitHub Action Skeleton Builder читает файл .dependencies, скачивает ядро Grav и все перечисленные темы и плагины и создаёт готовые пакеты, прикреплённые к вашему релизу GitHub. Создайте файл рабочего процесса .github/workflows/build-skeleton.yaml в репозитории скелета:

name: Build Skeleton

on:
  release:
    types: [ published ]
  workflow_dispatch:
    inputs:
      tag:
        description: 'Target tag for re-upload'
        required: true
        default: ''
      version:
        description: 'Which Grav release to use'
        required: true
        default: 'latest'
      admin:
        description: 'Create also a package with Admin'
        required: true
        default: true

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Extract Tag
        run: echo "SKELETON_VERSION=${{ github.event.inputs.tag || github.ref_name }}" >> $GITHUB_ENV
      - name: Generate Skeleton Packages
        uses: getgrav/skeleton-builder@v1
        with:
          version: ${{ github.event.inputs.version || 'latest' }}
          admin: ${{ github.event.inputs.admin || true }}
      - name: Upload packages to release
        uses: svenstaro/upload-release-action@v2
        with:
          repo_token: ${{ secrets.GITHUB_TOKEN }}
          tag: ${{ env.SKELETON_VERSION }}
          file: dist/*.zip
          overwrite: true
          file_glob: true

Рабочий процесс запускается двумя способами:

1. Автоматически — каждый раз, когда вы публикуете релиз GitHub вашего скелета, сборщик создаёт пакеты и прикрепляет их к этому релизу. Это и есть процесс выпуска скелетов: поставьте тег, опубликуйте релиз, и пакеты появятся.
2. Вручную — через Actions -> Build Skeleton -> Run workflow на GitHub, указав существующий тег. Используйте это, чтобы пересобрать пакеты последнего релиза при выходе новой версии Grav (или одной из зависимостей), не выпуская новый релиз скелета — существующие пакеты будут перезаписаны свежим содержимым.

Отправка скелета¶

Скелеты отправляются в репозиторий так же, как темы: убедитесь, что существует релиз с прикреплёнными собранными пакетами, затем откройте issue [add-resource] в трекере Grav, указав репозиторий скелета. Последующие релизы подхватываются автоматически. Действуют те же правила согласованности тегов.

Протокол заброшенных ресурсов¶

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

1. Отправьте хорошо оформленный и протестированный pull request в исходный репозиторий.

2. Если сопровождающий вообще не отвечает в течение 30 дней или заявляет, что забрасывает ресурс и не готов предоставить кому-то другому доступ на запись, переходите к следующему шагу.

3. Отправьте новый issue в репозиторий Grav на GitHub со следующими сведениями:

4. Заголовок: [change-resource] Take over plugin/theme

5. Укажите название темы и ссылку на исходный репозиторий.

6. Дайте ссылку на ваш pull request, оставшийся без ответа, или на обсуждение, в котором сопровождающий отказался от ресурса.

7. Сопровождающие Grav рассмотрят случай и сообщат, одобрено ли принятие. Если одобрено, переходите к следующему шагу.

8. Подготовьте форк репозитория с новым релизом.

9. Добавьте в README примечание, что этот репозиторий теперь основной, и ссылку на старый репозиторий.

10. Ответьте в issue, сообщив сопровождающим новый URL темы.

11. Сопровождающие обновят GPM, и новые и обновлённые установки будут происходить из вашего форка.