Grav - Pages

In this chapter, let us study about Grav Pages. Pages can be defined as building blocks of the site. Pages combine contents and navigations; this makes work easier even for the inexperienced users.

To begin with, let us know how to create a simple page. All user contents will be stored under user/pages/ folder. There will be only one folder called 01.home. The numeric portion of the folder is optional; it expresses the order of your pages (for example, 01 will come before 02) and explicitly informs Grav that this page should be visible in menu.

Let us now see how to create a new page.

Step 1 − Create a folder under /user/pages/; for example, 02.about as shown in the following screenshot.

Grav Pages

Step 2 − Create a file called default.md inside the newly created 02.about folder with the following content.

---
title: About Us
---

# About Us Page!

This is the body of **about us page**.

The above code uses some Markdown syntax explained briefly below. You can study in detail about Markdown in Markdown chapter.

  • The content between the --- indicators are the Page Headers.

  • # or hashes syntax in Markdown indicates a title which will be converted to <h1> header in HTML.

  • ** markers indicates bold text or <b> in HTML.

Step 3 − Reload your browser and you can see new page in menu as shown in the following screenshot.

Grav Pages

Page Types

Grav Pages supports 3 types of pages −

  • Standard Page.
  • Listing Page.
  • Modular Page.

Standard Page

Standard Pages are most basic type of pages such as blog post, contact form, error page etc. By default, a page is considered as a Standard Page. You are welcomed by a Standard Page as soon as you download and install the Base Grav package. You will see the following page when you install Base Grav package.

Grav Pages

Listing Page

Listing Page is an extension of a standard page which has a reference to a collection of pages. The easiest way to set up the listing page is to create child pages below the listing page. A blog listing page is a fine example for this.

A sample Blog Skeleton with Listing Page can be found in the Grav Downloads. A sample one is shown in the following screenshot.

Grav Pages

Modular Page

Modular Page is a form of listing page which builds a single page from its child pages. This allows us to build very complex one-page layouts from smaller modular content pages. This can be achieved by building the modular page from multiple modular folders found in the page’s primary folder.

A sample one-page skeleton using a Modular Page can be found in the Grav Downloads. A sample one is shown in the following screenshot.

Grav Pages

Folders

The /user/pages folder will contain contents for their respective pages. The folders inside the /user/pages folder are automatically treated as menus by Grav and used for the purpose of ordering. For example, the 01.home folder will be treated as home. Ordering is also to be maintained, i.e, 01.home will come before 02.about.

You should provide an entry-point so that it specifies the browser where to go when you point browser to root of your site. For example, if you enter http://mysite.com in your browser, Grav expects an alias home/ by default, but you can override the home location by changing the home.alias option in the Grav configuration file.

Underscore ( _ ) before the folder name is identified as Modular folders, which is a special folder type that is intended to be used only along modular content. For example, for the folder such as pages/02.about, slug would default to about, and the URL will be http://mysite.com/about.

If the folder name is not prefixed with numbers, that page is considered to be invisible and will not be displayed in navigation. For example, the if user/pages/ has /contact folder, will not be displayed in navigation. This can be overridden in the page itself inside the header section by setting visible to true as shown below to make it visible in navigation.

---
title: contact
visible: true
---

By default a page is visible in the navigation if the surrounding folders have numerical prefixes.The valid values for setting visibility are true or false.

Ordering

There are many ways to control ordering of the folder, one of the important way is to set content.order.by of the page configuration settings. The options are listed below.

  • default − File system can be used for ordering, i.e., 01.home before 02.about.

  • title − Title can be used for ordering which is defined in each page.

  • date − Ordering can be based on date which is defined in each page.

  • folder − Folder name consisting of any numerical prefix, e.g. 01., will be removed.

  • basename − Ordering is based on the alphabetic folder without numeric order.

  • modified − Modified timestamp of the page can also be used.

  • header.x − Any of the page header field can be used for ordering.

  • manual − Using order_manual variable ordering can be made.

  • random − Randomizing your order can also be done.

Manual order is specifically defined by providing a list of options to the content.order.custom configuration setting. You can set the pages.order.dir and the pages.order.by options to override the default behavior in the Grav system configuration file.

Page File

The page inside the page folder should be created as .md file, i.e., Markdown formatted file; it is markdown with YAML front matter. The default will be the standard name for main template and you can give it any name. An example for a simple page is shown below −

---
title: Title of the page
taxonomy:
   category: blog page
---
# Title of the page

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque porttitor eu
felis sed ornare. Sed a mauris venenatis, pulvinar velit vel, dictum enim. Phasellus
ac rutrum velit. **Nunc lorem** purus, hendrerit sit amet augue aliquet, iaculis
ultricies nisl. Suspendisse tincidunt euismod risus. Nunc a accumsan purus.

Contents between --- markers is known as the YAML front matter and this YAML front matter consists of basic YAML settings. In the above example, we are setting title and taxonomy to the blog page. The section after the pair of --- markers is the actual content that we see on our site.

Summary Size and Separator

The default size of the summary can be set in site.yaml used via page.summary(). This is useful for blogs where just the summary information is needed and not the full page content. You can use the manual summary separator also known as summary delimiter: === and ensure you put this in your content with blank lines above and below it, as shown below.

Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor
incididunt ut labore et dolore magna aliqua.

===

Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt
ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation
ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in
reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur
sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id
est laborum."

The text above the separator will be used when referenced by page.summary() and the full content when referenced by page.content().

Finding other Pages

Grav has feature called find() method to find another page and perform actions on that page.

For example, if you want to list all the company location on a particular page, use the following markdown rule −

# Locations 
<ul>
   {% for loc in page.find('/locations').children if loc != page %}
      <li><a href="{{loc.url}}">{{ loc.title }}</a></li>
   {% endfor %}
</ul>
Advertisements