△ヘッダー

ページ上部にあるページヘッダー（フロントマター）は完全に任意であり、Grav 内でページを表示するためには全く必要ありません。Gravには3種類のページ(Standard,Listing,Modular)があり、それぞれに関連するヘッダがあります。

基本的なページヘッダー

基本的なヘッダーオプションはいくつか用意されています。

キャッシュの有効化

cache_enable: false

デフォルトでは、Grav はページファイルの内容をキャッシュして、可能な限り高速に動作しようとしますが、ページがキャッシュされないようにすることも可能です。

例えば、コンテンツで動的な Twig 変数を使用している場合です。cache_enable により、この動作をオーバーライドすることができます。Twig コンテンツ変数については、後の章で説明します。有効な値は true か false です。

Date

date: 01/01/2020 3:14pm

date 変数は、このページに関連する日付を具体的に設定することができます。投稿がいつ作成されたかを示すために使われたり、表示やソート順の目的で使用することができます。設定されていない場合、これはページの最終更新時刻をデフォルトとします。

Menu

menu: My Page

menu 変数は、ナビゲーションで使用するテキストを設定することができます。メニューにはいくつかのフォールバックがあり、menu 変数が設定されていない場合、title 変数を使用しようとします。

Published

published: true

デフォルトでは、明示的に publish: false とするか、publish_date を未来にするか、unpublish_date を過去にしない限り、そのページは公開されます。有効な値は true または false です。

Slug

slug: my-page-slug

slug 変数を使うと、URL のページの部分を具体的に設定することができます。例えば、上記の slug 変数を設定した場合、http://yoursite.com/my-page-slug が URL になります。slug 変数が設定されていない場合、フォルダ名（数値の接頭辞なし）を使用するようにフォールバックします。

slug 変数は一般にすべて小文字で、アクセント記号付きの文字はアルファベットで置き換えられ、空白文字はダッシュまたはアンダースコアで置き換えられます。将来のバージョンでは slug 変数の中にスペースを入れることができるようになりますが、空白や大文字を入れることは推奨されません。

たとえば、ブログ記事のタイトルが Blog Post Exampleの場合、推奨されるスラッグは blog-post-example です。

Taxonomy

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

非常に便利なヘッダー変数である taxonomy 変数は、サイト構成ファイルで有効なタイプとして定義したタクソノミに値を割り当てることができます。

そのファイルにタクソノミーが定義されていない場合は無視されます。この例では、このページは blog カテゴリに属し、sample、demo、grav というタグを持つものとして定義されています。これらのタクソノミーを使って、他のページ、プラグイン、さらにはテーマからこれらのページを見つけることができます。タクソノミーの章では、この概念についてより詳しく説明します。

Title

ヘッダーがまったくない場合、ブラウザや検索エンジンに表示されるページのタイトルを制御することができなくなります。このため、少なくともページのヘッダーにタイトル変数を置くことが推奨されます。

title: Title of my Page

title 変数が設定されていない場合、大文字の slug 変数をフォールバックして使用しようとします。

Advanced Headers

これらはまだ重要ですが、あまり一般的には使用されていません。これらは、ページ内で高度な機能を提供するために使用することができます。

Append URL extension

append_url_extension: '.json'

ページがデフォルトの拡張子を上書きします。また、レスポンスに適切なヘッダ属性を設定します。

Cache-Control

cache_control: max-age=604800

設定しない場合は空白、または有効な cache-control テキスト値を指定することができます。

Date Format

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

日付フォーマットのデフォルトを Grav 設定を上書きして、ページレベルで設定できるようにします。PHP の日付書式を利用することができます。

Debugger

When you enable the debugger via the system.yaml configuration file, the debugger will display on every page. There are cases where this may not be desirable or may cause conflicts with the output. Such an example is when you are requesting a page that is intended to return rendered HTML to an Ajax call. This should not have the debugger injected into the resulting data. To disable the debugger on this page you can use the debugger page header:

system.yaml 設定ファイルでデバッガを有効にすると、すべてのページでデバッガが表示されます。Ajax 呼び出しに対してレンダリングされた HTML を返すことを目的としたページを要求している場合などは、デバッガ情報を無効にするような場合に利用します。

debugger: false

ETag

etag: true

Enable or disable on a page level whether or not to display an ETag header variable with a unique value. false by default unless overridden in your system.yaml.

Expires

expires: 604800

ページの有効期限を秒単位で指定します。（604800秒 = 7日）

External Url

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

Allows you to override the dynamically generated URL with one you explicitly provide.

HTTP Response Code

http_response_code: 404

HTTPレスポンスコードを明示的に設定できるようにします。

Language

language: fr

特定のページの言語をオーバーライドできます。

LastModified

last_modified: true

Enable or disable on a page level whether or not to display a Last Modified header variable with modified date. false by default unless overridden in your system.yaml.

Lightbox

lightbox: true

Although strictly speaking this is not a standard page header, it is a common way to enable the loading of a standard lightbox JavaScript and CSS for a page. By default the core antimatter theme does not load the prerequisites to enable lightbox capabilities of images, be sure to install a lightbox plugin such as Featherlight, which is available via GPM.

Login Redirect Here

login_redirect_here: false

The login_redirect_here header enables you to determine whether or not someone is kept on that page after logging in through the Grav Login Plugin. Setting this header to false will forward someone to the prior page after a successful login.

A true setting here will enable the person to stay on the current page after a successful login. This is also the default setting, which applies if there is no login_redirect_here header in the frontmatter.

You can override this default behavior by forcing a standard location by specifying an explicit option in your Login configuration YAML:

redirect_after_login: '/profile'

This will always take you to the /profile route after a successful login.

Markdown

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

user/config/system.yaml 設定ファイルでグローバルに有効にするか、このマークダウンヘッダーオプションで ページごとにこのグローバル設定をオーバーライドすることができます。

Twig をキャッシュしない

never_cache_twig: true

有効にすると、結果をキャッシュしてページロードごとに保存するのではなく、ページロードごとに動的に変更できる処理ロジックを追加することができるようになります。これはsystem.yaml でサイト全体、または特定のページで true または false を設定することができます。

Process

process:
    markdown: false
    twig: true

Grav は、標準ではページ内の Markdown を処理しますが、Twig は処理しません。デフォルトで Twig を処理しないという選択は、一般的に必要とされる機能ではないため、純粋にパフォーマンス上の理由によるものです。プロセス変数でこの動作を上書きすることができます。

ページ内で 100% HTML を使用し、マークダウン処理を全く実行させたくない場合、特定のページでマークダウンを無効にしたい場合があります。また、プラグインが完全に別の方法でコンテンツを処理することを可能にします。有効な値は true またはfalse です。

ページ内で Twig のテンプレート機能を使いたい場合は、twig 変数を true に設定することで実現できます。

Twig 処理を優先する

twig_first: false

true に設定すると、Twig の処理は Markdown の処理の前に行われます。これは Markdown コンパイラによって処理されるために利用可能である必要があるマークダウンを Twig が生成する場合、特に有用です。注意点として、cache_enable: false と twig_first: true を設定すると、ページキャッシングは事実上無効になります。

Publish Date

publish_date: 01/23/2020 13:00

自動的に公開を開始する日付を指定することができます。有効な値は、strtotime() がサポートする任意の文字列の日付値です。

リダイレクト

redirect: '/some/custom/route'

or

redirect: 'http://someexternalsite.com'

内部または外部ページに直接リダイレクトすることができます。このページは表示されませんが、Grav 内のページとして存在するため、コレクションやメニューなどに表示することができます。

また、角括弧を使用することで、URL にリダイレクトコードを指定することができます。

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

Routes

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

You can now provide a default route that overrides the standard route structure as defined by the folder structure.

You can also specify a specific canonical route that can be used in themes to output a canonical link:

<link rel="canonical" href="https://yoursite/dresses/green-dresses-are-awesome" />

Lastly, you can specify an array of route aliases that can be used as alternative routes for a particular page.

Routable

routable: false

By default, all pages are routable. This means that they can be reached by pointing your browser to the URL of the page. However, you may need to create a page that is created to hold specific content, but it is meant to be called directly by a plugin, other content, or even a theme directly. A good example of this is a 404 Error page.

Grav automatically looks for a page with the route /error if another page cannot be found. With this being an actual page within Grav, you would have complete control over what this page looks like. You probably do not want people accessing this page directly in their browser, however, so this page commonly has its routable variable set to false. Valid values are true or false.

SSL

ssl: true

You can now enable a specific page to be forced with SSL on or off. This only works with the absolute_urls: true option set in the system.yaml configuration. This is because to be able to switch back and forth between SSL and non-SSL pages, you must be using full URLs with the protocol and host included.

Summary

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

The summary option configures what the page.summary() method returns. This is most often used in a blog-listing type scenario, but can be used anytime you need a synopsis or summary of the page content. The scenarios are as follows:

The size attribute has different meanings when the format is set to short and long:

Template

template: custom

As explained in the previous chapter, the template from the theme that is used to render a page is based on the filename of the .md file.

So a file called default.md, will use the default template in the active theme. You can, of course, override this behavior by simply setting the template variable in the header and choosing a different template.

In the example above, the page will use the custom template from the theme. This variable exists because you may need to change the template of a page programmatically from a plugin.

Template Format

template_format: xml

Traditionally, if you want a page to output a specific format (ie: xml, json, etc.) you needed to append the format to the url. For example, entering http://example.com/sitemap.xml would tell the browser to render the content using the xml twig template ending in .xml.twig. This is all well and good, because we love doing things simply in Grav.

Using the template_format page header, we can tell the browser how to render the page without any need for extensions in the URL. By entering template_format: xml in our sitemap page, we can make http://example.com/sitemap work for us without having to append .xml to the end of it.

We used this method with the Grav Sitemap Plugin.

Unpublish Date

unpublish_date: 05/17/2020 00:32

Optional field, but can provide a date to automatically trigger un-publication. Valid values are any string date values that strtotime() supports.

Visible

visible: false

By default, a page is visible in the navigation if the surrounding folder has a numerical prefix, i.e. /01.home is visible, while /error is not visible. This behavior can be overwritten by setting the visible variable in the header. Valid values are true or false.

Custom Page Headers

Of course, you can create your own custom page headers using any valid YAML syntax. These would be page-specific and be available for any plugin, or theme to make use of. A good example of this would be to set some variable specific to a sitemap plugin, such as:

sitemap:
    changefreq: monthly
    priority: 1.03

The significance of these headers is that Grav does not use them by default. They are only read by the sitemap plugin to determine how often this particular page is modified and what its priority should be.

Any page header such as this should be documented, and generally, there will be some default value that will be used if the page does not provide it.

Another example would be to store page-specific data that could then be used by Twig in the content of the page.

For example, you might have want to associate some author reference for the page. If you added these YAML settings to the page header:

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

You could then access them from Twig:

<section id="author-details">
    <h2></h2>
    <p></p>
    <span>Contact: <a href="https://twitter.com/"><i class="fa fa-twitter"></i></a></span>
</section>

If the variable name contains a special character like a dash you should use twigs attribute function:

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

Meta Page Headers

Meta headers allow you to set the standard set of HTML tags for each page as well as OpenGraph, Facebook, and Twitter.

Standard Metatag examples

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'

This will produce the HTML:

<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" />

All HTML5 metatags are supported.

OpenGraph Metatag examples

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

This will produce the HTML:

<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" />

For a full outline of all OpenGraph metatags that can be used, please consult the official documentation.

Facebook Metatag examples

metadata:
    'fb:app_id': your_facebook_app_id

This will produce the HTML:

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

Facebook mostly uses OpenGraph metatags, but there are some Facebook-specific tags and these are supported automatically by Grav.

Twitter Metatag examples

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

This will produce the HTML:

<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" />

For a full outline of all Twitter metatags that can be used, please consult the official documentation.

This really provides a lot of flexibility and power.

Frontmatter.yaml

An advanced feature that can come in handy for some power users is the ability to use common frontmatter values via a frontmatter.yaml file located in the page folder. This is particular useful when working with multi-language sites where you may wish to share a portion of the frontmatter between all the language versions of a given page.

To take advantage of this, simply create a frontmatter.yaml file alongside your page's .md file and add any valid frontmatter values. For example:

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