Заголовки и метаданные страниц¶

Заголовки страницы (также известные как метаданные страницы) в её начале полностью необязательны — для отображения страницы в Grav они вообще не нужны. В Grav есть 3 основных типа страниц (обычные, страницы-списки и модульные), и у каждого есть свои заголовки.

Основные заголовки страниц¶

Есть ряд основных параметров заголовка страницы.

Включение кэша¶

cache_enable: false

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

Пример — использование динамических переменных Twig в контенте. Переменная cache_enable позволяет переопределить это поведение. Переменные Twig в контенте мы рассмотрим в отдельной главе. Допустимые значения — true или false.

Дата¶

date: 01/01/2020 3:14pm

Переменная date позволяет явно задать дату, связанную с этой страницей. Обычно она указывает, когда была создана запись, и используется для отображения или сортировки. Если дата не задана, по умолчанию берётся время последнего изменения страницы.

Меню¶

menu: My Page

Переменная menu задаёт текст, который используется в навигации. Для меню есть несколько уровней резервных значений: если переменная menu не задана, Grav попытается использовать переменную title.

Публикация¶

published: true

По умолчанию страница опубликована, если вы явно не установили published: false, не указали publish_date в будущем или unpublish_date в прошлом. Допустимые значения — true или false.

Слаг¶

slug: my-page-slug

Переменная slug позволяет явно задать часть URL, относящуюся к странице. Например, если задать указанный выше slug, URL будет http://my-site.example/my-page-slug. Если slug не задан, Grav использует имя папки (без числовых префиксов).

Слаги обычно состоят только из строчных букв; акцентированные символы заменяются буквами английского алфавита, а пробелы — дефисом или подчёркиванием. Хотя будущие версии Grav будут поддерживать пробелы в слагах, использовать пробелы или заглавные буквы не рекомендуется.

Например: если заголовок записи блога — Blog Post Example, рекомендуемый слаг будет blog-post-example.

Таксономия¶

taxonomy:
    category: blog
    tag: [sample, demo, grav]

Очень полезная переменная заголовка: taxonomy позволяет присваивать значения таксономии, определённой как допустимые типы в файле конфигурации сайта.

Если таксономия не определена в этом файле, она игнорируется. В примере страница отнесена к категории blog и имеет теги sample, demo и grav. Эти таксономии можно использовать для поиска таких страниц с других страниц, из плагинов и даже тем. Подробнее эта концепция рассматривается в главе Таксономия.

Заголовок¶

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

title: Title of my Page

Если переменная title не задана, Grav использует резервный вариант — переменную slug с заглавной первой буквой.

Дополнительные заголовки¶

Эти параметры тоже важны, но используются реже. Они позволяют реализовать на странице дополнительные возможности.

Добавление расширения URL¶

append_url_extension: '.json'

Позволяет странице переопределить расширение по умолчанию и задать его программно. Также устанавливает соответствующие заголовки ответа.

Cache-Control¶

cache_control: max-age=604800

Может быть пустым (тогда параметр не задаётся) или содержать допустимое текстовое значение cache-control.

Формат даты¶

dateformat: 'Y-m-d H:i:s'

Переопределяет конфигурацию форматов даты Grav по умолчанию и позволяет задать её на уровне страницы. Можно использовать любой из доступных форматов даты PHP.

Отладчик¶

Если вы включили отладчик в файле конфигурации system.yaml, он будет отображаться на каждой странице. Иногда это нежелательно или может конфликтовать с выводом. Пример — запрос страницы, которая должна вернуть отрендеренный HTML для Ajax-вызова. В таком случае отладочная панель не должна внедряться в возвращаемые данные. Чтобы отключить отладчик на этой странице, используйте заголовок debugger:

debugger: false

ETag¶

etag: true

Включает или отключает на уровне страницы вывод переменной заголовка ETag с уникальным значением. По умолчанию — false, если не переопределено в system.yaml.

Срок действия¶

expires: 604800

Время истечения страницы в секундах (604800 секунд = 7 дней).

Внешний URL¶

external_url: https://www.example.com/foo/bar

Позволяет заменить динамически сгенерированный URL на тот, который вы указали явно.

Код ответа HTTP¶

http_response_code: 404

Позволяет динамически задать код ответа HTTP.

Язык¶

language: fr

Позволяет переопределить язык для конкретной страницы.

LastModified¶

last_modified: true

Включает или отключает на уровне страницы вывод переменной заголовка Last Modified с датой изменения. По умолчанию — false, если не переопределено в system.yaml.

Lightbox¶

lightbox: true

Строго говоря, это не стандартный заголовок страницы, но распространённый способ подключить для страницы стандартные JavaScript и CSS lightbox. По умолчанию основная тема antimatter не загружает предварительные требования для работы lightbox с изображениями. Установите плагин lightbox, например Featherlight, доступный через GPM.

Перенаправление после входа¶

login_redirect_here: false

Заголовок login_redirect_here определяет, остаётся ли пользователь на этой странице после входа через плагин Grav Login. Если установить false, после успешного входа пользователь будет перенаправлен на предыдущую страницу.

Значение true позволит пользователю остаться на текущей странице после успешного входа. Это также настройка по умолчанию, которая применяется, если в метаданных страницы нет заголовка login_redirect_here.

Это поведение по умолчанию можно переопределить, принудительно задав стандартное место, указав явный параметр в YAML-конфигурации Login:

redirect_after_login: '/profile'

После успешного входа пользователь всегда будет попадать на маршрут /profile.

Markdown¶

  markdown:
    extra: false
    auto_line_breaks: false
    auto_url_links: false
    escape_markup: false
    special_chars:
      '>': 'gt'
      '<': 'lt'

Эти параметры можно включить глобально в файле user/config/system.yaml или переопределить глобальную настройку для отдельной страницы с помощью заголовка markdown.

Никогда не кэшировать Twig¶

never_cache_twig: true

Включение этой опции позволяет добавить логику обработки, которая может меняться динамически при каждой загрузке страницы, вместо кэширования и сохранения результатов для каждой загрузки. Её можно включить или отключить для всего сайта в system.yaml или для конкретной страницы. Допустимые значения — true или false.

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

Обработка¶

process:
    markdown: false
    twig: true

Обработка страницы — ещё одна продвинутая возможность. По умолчанию Grav обрабатывает markdown, но не обрабатывает twig на странице. Twig по умолчанию не обрабатывается исключительно ради производительности, поскольку эта фича нужна нечасто. Переменная process позволяет переопределить это поведение.

Вы можете отключить markdown на конкретной странице, если хотите использовать на странице только HTML и вообще не запускать обработку Markdown. Кроме того, это позволяет плагину полностью изменить способ обработки контента. Допустимые значения — true или false.

Бывают ситуации, когда в контенте нужно использовать возможности шаблонизации Twig; для этого установите переменную twig в true.

Сначала обработать Twig¶

twig_first: false

Если установить true, обработка Twig произойдёт до любой обработки Markdown. Это особенно полезно, если ваш Twig генерирует Markdown, который должен быть доступен для обработки компилятором Markdown. Учтите: если заданы cache_enable: false и twig_first: true, кэширование страниц фактически отключается.

Дата публикации¶

publish_date: 01/23/2020 13:00

Необязательное поле; задаёт дату, по достижении которой публикация запускается автоматически. Допустимы любые строковые значения даты, которые поддерживает strtotime().

Перенаправление¶

redirect: '/some/custom/route'

или

redirect: 'http://someexternalsite.com'

Можно перенаправить на другую внутреннюю или внешнюю страницу прямо из заголовка страницы. Разумеется, сама страница отображаться не будет, но она может оставаться в коллекции, меню и т. д., поскольку существует как страница внутри Grav.

Также можно добавить код перенаправления к URL в квадратных скобках:

redirect: '/some/custom/route[303]'

Маршруты¶

routes:
  default: '/my/example/page'
  canonical: '/canonical/url/alias'
  aliases:
    - '/some/other/route'
    - '/can-be-any-valid-slug'

Можно задать маршрут по умолчанию, который переопределяет стандартную структуру маршрутов, определяемую структурой папок.

Также можно указать конкретный канонический маршрут, который используется в темах для вывода канонической ссылки:

<link rel="canonical" href="https://my-site.example/dresses/green-dresses-are-awesome" />

Наконец, можно задать массив псевдонимов маршрутов, которые будут альтернативными маршрутами для конкретной страницы.

Маршрутизируемая¶

routable: false

По умолчанию все страницы маршрутизируемые. Это значит, что до них можно добраться, открыв URL страницы в браузере. Однако может понадобиться страница, созданная для хранения определённого контента, но предназначенная для прямого вызова плагином, другим контентом или даже темой. Хороший пример — страница ошибки 404.

Grav автоматически ищет страницу с маршрутом /error, если другую страницу найти не удалось. Поскольку это настоящая страница внутри Grav, вы полностью контролируете её внешний вид. Но, вероятно, вы не хотите, чтобы люди открывали эту страницу напрямую в браузере, поэтому обычно для неё задают routable: false. Допустимые значения — true или false.

SSL¶

ssl: true

Можно принудительно включить или отключить SSL для конкретной страницы. Это работает только при параметре absolute_urls: true в файле system.yaml. Причина в том, что для переключения между SSL- и не-SSL-страницами нужно использовать полные URL с протоколом и хостом.

Аннотация¶

summary:
  enabled: true
  format: short | long
  size: int

Параметр summary определяет, что возвращает метод page.summary(). Чаще всего он используется в сценариях со списком блога, но подходит в любой ситуации, когда нужен краткий обзор или аннотация содержимого страницы. Возможны следующие варианты:

Атрибут size имеет разное значение в зависимости от того, установлен формат short или long:

Шаблон¶

template: custom

Как объяснялось в предыдущей главе, шаблон темы, используемый для рендеринга страницы, определяется именем файла .md.

Так, файл default.md будет использовать шаблон default активной темы. Разумеется, это поведение можно переопределить, просто задав переменную template в заголовке и выбрав другой шаблон.

В примере выше страница будет использовать шаблон custom из темы. Эта переменная существует, потому что может понадобиться программно изменить шаблон страницы из плагина.

Формат шаблона¶

template_format: xml

Традиционно, если страница должна выводить определённый формат (например, xml, json и т. д.), нужно добавлять расширение к URL. Например, http://my-site.example/sitemap.xml указывает браузеру отрендерить контент с помощью Twig-шаблона xml, оканчивающегося на .xml.twig. Всё это хорошо и правильно, ведь в Grav мы любим простые решения.

С помощью заголовка template_format можно указать браузеру, как рендерить страницу, без необходимости добавлять расширение к URL. Указав template_format: xml на странице sitemap, мы можем сделать так, чтобы http://my-site.example/sitemap работал без добавления .xml в конце.

Мы использовали этот метод в плагине Grav Sitemap.

Дата снятия с публикации¶

unpublish_date: 05/17/2020 00:32

Необязательное поле; задаёт дату, по достижении которой публикация автоматически снимается. Допустимы любые строковые значения даты, которые поддерживает strtotime().

Видимость¶

visible: false

По умолчанию страница видима в навигации, если у окружающей папки есть числовой префикс, то есть /01.home видима, а /error не видима. Это поведение можно переопределить, задав переменную visible в заголовке. Допустимые значения — true или false.

Пользовательские заголовки страниц¶

Разумеется, можно создавать собственные заголовки страниц с любым допустимым синтаксисом YAML. Они будут относиться к конкретной странице и станут доступны любому плагину или теме. Хороший пример — переменная, специфичная для плагина sitemap:

1
2
3

sitemap:
    changefreq: monthly
    priority: 1.03

Особенность этих заголовков в том, что Grav по умолчанию их не использует. Их читает только плагин sitemap, чтобы определить, как часто изменяется эта страница и каким должен быть её приоритет.

Любой такой заголовок страницы должен быть задокументирован; обычно предусматривается значение по умолчанию, если страница его не задаёт.

Другой пример — хранение данных конкретной страницы, которые затем может использовать Twig в контенте страницы.

Например, вы можете захотеть связать со страницей сведения об авторе. Если добавить в заголовок страницы такие настройки YAML:

1
2
3
4

author:
    name: Sandy Johnson
    twitter: @sandyjohnson
    bio: Sandy is a freelance journalist and author of several publications on open source CMS platforms.

их можно будет получить из Twig:

1
2
3
4
5

<section id="author-details">
    <h2>{{ page.header.author.name|e }}</h2>
    <p>{{ page.header.author.bio|e }}</p>
    <span>Contact: <a href="https://twitter.com/{{ page.header.author.twitter|e }}"><i class="fa fa-twitter"></i></a></span>
</section>

Если имя переменной содержит специальный символ, например дефис, используйте функцию attribute в Twig:

attribute(page.header, 'plugin-name').active 

Метатеги страниц¶

Метазаголовки позволяют задать для каждой страницы стандартный набор HTML-тегов <meta>, а также метатеги OpenGraph, Facebook и Twitter.

Примеры стандартных метатегов¶

1
2
3
4
5
6
7
8

metadata:
    refresh: 30
    generator: 'Grav'
    description: 'Your page description goes here'
    keywords: 'HTML, CSS, XML, JavaScript'
    author: 'John Smith'
    robots: 'noindex, nofollow'
    my_key: 'my_value'

В результате получится HTML:

1
2
3
4
5
6
7

<meta name="generator" content="Grav" />
<meta name="description" content="Your page description goes here" />
<meta http-equiv="refresh" content="30" />
<meta name="keywords" content="HTML, CSS, XML, JavaScript" />
<meta name="author" content="John Smith" />
<meta name="robots" content="noindex, nofollow" />
<meta name="my_key" content="my_value" />

Поддерживаются все метатеги HTML5.

Примеры метатегов OpenGraph¶

1
2
3
4
5

metadata:
    'og:title': The Rock
    'og:type': video.movie
    'og:url': http://www.imdb.com/title/tt0117500/
    'og:image': http://ia.media-imdb.com/images/rock.jpg

В результате получится HTML:

1
2
3
4

<meta name="og:title" property="og:title" content="The Rock" />
<meta name="og:type" property="og:type" content="video.movie" />
<meta name="og:url" property="og:url" content="http://www.imdb.com/title/tt0117500/" />
<meta name="og:image" property="og:image" content="http://ia.media-imdb.com/images/rock.jpg" />

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

Примеры метатегов Facebook¶

1
2

metadata:
    'fb:app_id': your_facebook_app_id

В результате получится HTML:

1

<meta name="fb:app_id" property="fb:app_id" content="your_facebook_app_id" />

Facebook в основном использует метатеги OpenGraph, но есть и специфичные для Facebook теги; Grav поддерживает их автоматически.

Примеры метатегов Twitter¶

1
2
3
4
5
6

metadata:
    'twitter:card' : summary
    'twitter:site' : @flickr
    'twitter:title' : Your Page Title
    'twitter:description' : Your page description can contain summary information
    'twitter:image' : https://farm6.staticflickr.com/5510/14338202952_93595258ff_z.jpg

В результате получится HTML:

1
2
3
4
5

<meta name="twitter:card" property="twitter:card" content="summary" />
<meta name="twitter:site" property="twitter:site" content="@flickr" />
<meta name="twitter:title" property="twitter:title" content="Your Page Title" />
<meta name="twitter:description" property="twitter:description" content="Your page description can contain summary information" />
<meta name="twitter:image" property="twitter:image" content="https://farm6.staticflickr.com/5510/14338202952_93595258ff_z.jpg" />

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

Это действительно даёт большую гибкость и мощь.

Frontmatter.yaml¶

Продвинутая фича, которая может пригодиться опытным пользователям, — общие значения метаданных через файл frontmatter.yaml в папке страницы. Это особенно полезно для многоязычных сайтов, где нужно разделить часть метаданных между всеми языковыми версиями страницы.

Чтобы воспользоваться этой фичей, создайте файл frontmatter.yaml рядом с файлом .md страницы и добавьте в него любые допустимые значения метаданных. Например:

1
2
3

metadata:
    generator: 'Super Grav'
    description: Give your page a powerup with Grav!