Making the Blog Page

Our first step is to add the blog page. This is where all of our future posts will be listed. To add a blog page, first click the Add button on the Pages tab.

Button 'Add' is at the top right on the Pages tab.

We have to choose a title for our page. I chose Blog and the folder name automatically constructed itself as blog. We also have to set the template to use as the Blog template. The other settings are good the way they are.

Page settings are: Page Title: Blog; Folder Name: blog; Parent Page: / (root); Page Template: Blog; Visible: Auto.

The Page Editor

After clicking the Save button at the top right, the page editor will look like this.

Various sections on the page editor are highlighted. Save button (5) is at the top right. Below that are tabs (3) with Content, Options, Advanced, and Blog Config. To the right of that is the editor mode toggle (4). Below that is the Title (1), with the input text currently 'Blog.' Below that is the markdown editor (2). At the bottom is the page media (6) section.

  1. Title. This is automatically filled with the title we chose. We can change it at any time if we want a different title.
  2. Markdown Editor. This is where the content of the page goes. Grav uses markdown to format text. The Grav documentation includes a very handy markdown reference. There are also markdown editors you can use instead if you prefer. I found that once I got used to markdown I had no problems with the built-in Grav editor, but a lot of this will come down to personal preference.
  3. Tabs. All pages will have Content, Options, and Advanced tabs. Options and Advanced make it easy to change various settings for the page, although the defaults are often perfectly fine. Some pages will also have a special tab. For the Blog page it is the Blog Config tab. We will take a closer look at this in a moment.
  4. Editor Mode. By default, the content editor is in normal mode. Putting it in expert mode will reduce the number of tabs and configurable options, but will allow us to directly edit the "frontmatter" of the page. Essentially, the frontmatter is a list of settings written in a special format at the top of the page. Using the normal editor mode obscures this by providing a user interface for setting these options. Occasionally, however, we may want to switch to expert mode in order to set an option that is not available in the user interface.
  5. Save Button. This is the most important button on the page! Remember to save early and save often. You will also have noticed this button on the plugin and theme configuration pages. Any time we make a change, we need to save it by clicking this button.
  6. Page Media. This is where you can add media that you want to embed in your page.

Adding Some Content

The blog page is not supposed to take a lot of content. A heading and subheading is all it really needs. In markdown, headings are denoted with the hashtag symbol. Type

CLIP: # My Example Blog

## Learning to use Grav

The above text - '# My Example Blog \n\n ## Learning to use Grav' - is shown typed into the markdown editor.

This will render as

Visual representation of the markdown.

Blog Settings

After saving, we can take a look at the Blog Config tab.

The Blog Config tab is shown. There are three sections - Hero Section, Configuration, and Content Definition.

There are a lot of options here. Fortunately, the default settings are usually good to start out with, so all you need to do is glance over this tab for now. Some of the settings define the collection of blog posts. Some others provide settings for enabled plugins.

One setting we might want to change is Max Item Count under Content Definition. By default this is set to 5, which means that the blog page will show five posts per page. Five does not seem like very much to me, so I would change it to 10.

Max Item Count is the second option under Content Definition. It is set to 10.

Testing Expert Mode

If we switch to expert mode, we can see how these settings are provided in the frontmatter. Although we will not have to edit them while in expert mode, this will help demystify the frontmatter, which may help in the future if we come across something we cannot modify from the provided user interface.

CLIP: title: Blog
        - '@self.children'
    limit: 10
        by: date
        dir: desc
    pagination: true
    url_taxonomy_filters: true
    limit: 10

Now we only have Content and Options tabs. On the Content tab, the Title section has been replaced with a Frontmatter section, which defines the title and some of the options we saw on the Blog Config tab. You may notice (especially if you took a look at the Options and Advanced tabs) that not all of the settings are listed here. If a setting is not explicitly defined in the frontmatter, Grav will automatically use the default.

Since the normal editing mode will be much more useful to us in general, we can go ahead and switch back. If we navigate to our website, it should look like this:

The Website Blog page (not the Home page) is shown. The content (title and subtitle) we added is featured prominently.