△ルーティング

Page -> Folders section で説明したように、Grav でのルーティングは、フォルダ構造によって主に制御されます。

Grav には様々なツールや設定オプションが搭載されており、より柔軟な対応が可能です。

他の CMS プラットフォームから Grav にサイトを移行した場合、新しいサイトの設定方法についていくつかの選択肢があることを想像してください。

1. フォルダ構造を一致させることで、旧サイトの URL を再現する。
2. 新しいサイトを好きなように構築し、ウェブサーバーで古いURLを「書き換え」て、クライアントを新しい場所にリダイレクトさせることができます。
3. 新しいサイトを好きなように構築し、古い URL から新しい場所にクライアントをリダイレクトするように Grav を設定します。

他にも、フォルダ構造とは異なる URL に反応させたいケースは多々ありますが、Grav は以下のような機能も備えており、目的の実現を助けます。

Page Level Route and Redirect Overrides

Headers -> Routes section で説明したように、 デフォルトルートや ルートエイリアスの配列に対して、明示的なルーティングオプションを指定することができます。

路線:

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

ルーティングオプションは、ページごとに処理され、キャッシュされます。そして、ページ階層のスラッグに基づき生成されたルートである生ルートと呼ばれるもの（Gravがデフォルトでルートを計算する方法です）と共に利用できます。そのため、カスタムのページルートを提供する場合でも、生ルートは常に有効です。

ページレベルのルーティングと同様に、ページヘッダーでターゲットページを指定することで、ページレベルのリダイレクトもサポートしています。詳しくは Headers -> Redirect の項をご覧ください。

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

Site Level Routes and Redirects

Grav has a powerful regex-based mechanism for handling route aliases and redirects from one page to another. This feature is particularly useful when you migrate a site to Grav and want to ensure the old URLs will still work with the new site. This is often best accomplished via rewrite rules using your web server, but sometimes it's more convenient and flexible just to let Grav handle them.

These are handled via the Site Configuration. Grav comes with a sample system/config/site.yaml but you can override or add any of your own settings by editing the user/config/site.yaml file.

ルート・エイリアス

シンプルなエイリアス

The most basic kind of alias is a direct one-to-one mapping. In the routes: section of the site.yaml, you can create a list of mappings to indicate the alias and the actual route that should be used.

routes:
  /something/else: '/blog/focus-and-blur'

If you requested a URL http://mysite.com/something/else and that was not a valid page, the routes definition would actually serve you the page located at /blog/focus-and-blur, assuming it exists. This does not actually redirect the user to the provided page, it simply displays the page when you request the alias.

正規表現によるエイリアス

A more advanced type of alias redirect allows the use of a simple regex to map part of an alias to a route. For example, if you had:

routes:
   /another/(.*): '/blog/$1'

This would route the wildcard from the alias to the route, so http://mysite.com/another/focus-and-blur would actually display the page found at the /blog/focus-and-blur route. This is a powerful way to map one set of URLs to another. Great for moving your site from WordPress to Grav :)

You can also perform the match to capture any alias, and map that to a specific route:

routes:
  /one-ring/(.*): '/blog/sunshine-in-the-hills'

With this route alias, any URL that confirms to the wildcard: /one-ring/to-rule-them-all or /one-ring/is-mine.html will both show the content from the page with the route /blog/sunshine-in-the-hills.

You can even get much more creative and map multiple items or use any regex syntax:

routes:
  /complex/(category|section)/(.*): /blog/$1/folder/$2

This would match and rewrite the following:

/complex/category/article-1      -> /blog/category/folder/article-1
/complex/section/article-2.html  -> /blog/section/folder/article-2.html

This route would not match anything that doesn't start with complex/category or complex/section. For more information, Regexr.com is a fantastic resource to learn about and test regular expressions.

リダイレクト

The other corollary option to route aliases is provided by redirects. These are similar, but rather than keeping the URL and simply serving the content from the aliased route, Grav actually redirects the browser to the mapped page.

There are three system-level configuration options that affect Redirects:

pages:
  redirect_default_route: false
  redirect_default_code: 302
  redirect_trailing_slash: true

• redirect_default_route enables Grav to automatically redirect to the page's default route.
• redirect_default_code allows you to set the default HTTP redirect codes:
  • 301: Permanent redirect. Clients making subsequent requests for this resource should use the new URI. Clients should not follow the redirect automatically for POST/PUT/DELETE requests.
  • 302: Redirect for undefined reason. Clients making subsequent requests for this resource should not use the new URI. Clients should not follow the redirect automatically for POST/PUT/DELETE requests.
  • 303: Redirect for undefined reason. Typically, 'Operation has completed, continue elsewhere.' Clients making subsequent requests for this resource should not use the new URI. Clients should follow the redirect for POST/PUT/DELETE requests.
  • 307: Temporary redirect. Resource may return to this location at a later point. Clients making subsequent requests for this resource should use the old URI. Clients should not follow the redirect automatically for POST/PUT/DELETE requests.
• redirect_trailing_slash option lets you redirect to a non-trailing slash version of the current URL

For example:

redirects:
    /jungle: '/blog/the-urban-jungle'

You can also explicitly pass the redirect code between square brackets [] as part of the URL:

redirects:
    /jungle: '/blog/the-urban-jungle[303]'

If you were to point your browser to http://mysite.com/jungle, you would actually get redirected and end up on the page: http://mysite.com/blog/the-urban-jungle.

The same regular expression capabilities that exist for Route Aliases, also exist for Redirects. For example:

redirects:
    /redirect-test/(.*): /$1
    /complex/(category|section)/(.*): /blog/$1/folder/$2

These look almost identical to the Route Alias version, but instead of transparently showing the new page, Grav actually redirects the browser and loads the new page specifically.

Hiding the Home Route

When you set a certain page to be your site's home via the system.yaml file:

home:
  alias: '/home'

You are effectively telling Grav to add a route of / as an alias for that page. This means that when Grav is requesting the page for the / URL, it finds the page you have set.

However, Grav really doesn't do anything special for pages that are beneath this homepage. So if you have a page called /blog that displays a list of your blog posts, and you set this to be your homepage, it will work as expected. If however, you click on a blog post that sits beneath the /blog folder, the URL could be /blog/my-blog-post. This is expected behavior, but it might not be what you intend. There is a new option available via the system.yaml that let's you hide this top level /blog from the route if so enabled.

You can enable this behavior by toggling the following value:

home:
  hide_in_urls: true