2.3 How Page Content Works in Grav CMS
Each piece of content in a Grav site is termed a “page”, and pages are driven by Markdown files. In order for Grav to function correctly, these files need to be named in a particular way and be housed in a directory structure organised in a prescribed fashion. In this lesson we’ll learn the rules of organizing Markdown files in a Grav site.
1.Introduction1 lesson, 01:23
2.Getting Started3 lessons, 26:42
3.Grav CMS Templates4 lessons, 25:21
4.Set Up a Blog4 lessons, 33:39
5.Conclusion1 lesson, 03:43
2.3 How Page Content Works in Grav CMS
Hey, welcome to Up & Running with Grav CMS. In this lesson, we're gonna go through the rules of how page content is organized in a Grav site, how the folder and file naming conventions affect everything, and the things that you need to know as a foundation for building themes. The first thing to understand about GRAV is everything is a page. In other content management systems you might have static pages and posts or you might have other types of content like store entries or gallery entries. In GRAV, no matter what the purpose is of a particular piece of content, it's still called a page That's just a catch-all term for everything. Under that umbrella, there are three different types of pages. We have a standard page, a listing page, and a modular page. And we're gonna be using each of these three types in the theme that we create through this course. A standard page is just a default. This is meant for static content that you'll pretty much add at the start of a site development project and you're going to leave it as it is. So this is suitable for something like an about us page or a contact page for example. A listing page is designed to present a collection of child pages. So this is the kind of page that you're gonna use to create something like a blog which is what we're gonna be doing as part of our theme. A listing page basically acts as the parent to all of the blog entries which will be added as children of that parent listing page, and then when you create your template to control the presentation of that parent listing page, that's where you're gonna set up a blog style display or whatever other type of listing display you need for your site project. The key distinction here is that everyone of these child pages is designed to act as an individual piece of content that can also be viewed by itself outside of this listing context. And that is what makes a listing page different to the third type of page. Which is a modular page. A modular page is, in a sense, half way in between a standard page and a listing page. A modular page is a parent page that has a series of child pages, but in this case, each one of those child pages act as a module that comprises part of the parent pages context. For example, on this page here, you can see that it's comprised of a few sections stacked one on top of the other. And with this, each one of these sections is classed as a module and will have its own separate markdown file that contains its contents and also typically its own corresponding template inside your theme. We we create our theme, we're gonna be using this modular page type to set up a home page, not too dissimilar to what you see here. So that way you're gonna get to see and work with all three of the different types of pages that you have available to you in GRAV CMS site. All right so here we are in the admin panel again. I'm in the pages section. I've also got a file explorer open here and I'm going to go into the user folder and into the pages folder so you can see what happens inside the GRAV system when you create a new page through admin. So we're gonna add a new page. We'll give it a title. We're not gonna change its parent so we're not gonna make it a child page. We're just gonna leave parent set as root. So this is a top level page. And then in the page template, drop down here. You'll see that we have a few selections. These are coming from the default antimatter theme but so we're just gonna leave this set to default. All right so now we hit continue. Now before anything happens inside that file system, we're gonna need to add some contents to our page and then we'll hit save. And once we do that, now you can see a new folder has popped up inside our pages folder. And you'll notice that the name of the folder corresponds with the name that we gave our page. This can be a little bit confusing at first. You might expect that the mark down document will have the same name as the page it represents. That's not the case. The name of the page is determined by the name of the folder. So just bear that in mind as you're working with the system. So if we go into the folder for our new page. In here, we have the mark down file for our page. And you'll notice that it's named default.md. In GRAV, the name of the marked down file for each page is what determines the template from the theme that is going to be used to display it. So by having this file name, default.md, that tells the system that we want this content to be displayed using the default template from our theme. Let's open it up and take a quick look inside. So there we can see we've got our title and we've got the content that we just added earlier. Now as I mentioned, you can edit any of your content either through your favorite mark down editor or another text editor, anything you want, as well as working in the admin panel. So if we add a little bit in here and we save the file, then we go back to our admin panel and refresh. You can see that the changes that I made directly to the file are now reflected in the admin panel. So this is kind of a two-way street. Changes you make through the admin panel will show up in your files. Changes you make in your files will show up in the admin panel. Now the other thing that you might have noticed is that each one of those folder names had a number in front of them. Now a new page folder is given the number 02. What that number does is determines a sort order for each one of our pages. So, for example, if you have a menu that lists each one of the top level pages in your site, then this number would determine what order your pages would show up in your menu. So right now, the page named home would come up first, followed by the page named new page. Now if you want to use the admin panel to change the order of your pages, you'll go into the advanced tab for the page that you want to move and then you have a little drag and drop list here. So we're gonna move new page so that it's now first by dragging this up, and then we'll hit save. In my file manager, you'll see that that disappeared because there's no longer a file named zero two.new page. So we'll back into our page's folder and now you can see that folder has been renamed. Now we've got 01.new-page and we've got 02.home. And once again that's something you can do manually if you prefer, you can just rename your folders, adding numbers to correspond with the order you want your pages to be in. I mentioned earlier that the name of your marked down file determines which template from your theme is gonna be used to display that file. You can rename your marked down files manually to determine which template they're going to use, or in your admin panel, also in the advanced temp, you'll find this page template drop down list, so let's have a demonstration of this feature. We'll change this to item and we'll save. Now if we go into our folder, you'll see that our mark down file has been renamed to item.md. And so that's the essentials of how you control the order of your top level pages and how you control which theme template is used to control the presentation of a given page. Now, let's have a quick look at how child pages work. So in the admin panel, we're going to add another page. We'll just call it Child Page. And now in the Parent Page, we're going to choose new page. So this is going to add this child page that we're creating now on the level underneath our new page that we created earlier. So once again, we'll just add a little content, so that we have something to save into the corresponding mark down file. We'll save that. Now if we go into the folder for our new page, we have another folder that's been added inside it. And just like with our top-level pages, the name of the folder matches the name of the page. The only difference here is we don't have the numerical ordering system. And then if we go into that folder, there's our mark down file and it too is named according to the template that should be used to display it from the theme. So let's have a quick look at the complete structure that we've created so far. This gives you a good overview of the type of systems that you're going to be working with to control pages in GRAV CMS. So we've got our numerical ordering on top level pages, we have our directory naming to correspond with page names and we have our mark down file naming to correspond with the template that you wanna use from a theme. Now there's one more thing that we're gonna touch on quickly, and that is the use of front matter, or otherwise know as headers in GRAV CMS. So if we open up this default.md file here, in this case, I'm opening this up in Atom so we can just have a look at the raw text. Along the top here, you'll see we have this section with three dashes at the beginning and three dashes at the end. Now that creates a little section that you can put basically meta information about the page in question. This type of content with the three dashes at the top and three dashes at the bottom Is most commonly known as frontmatter but in GRAV, it's also known as headers. And in this example you can see that we have a title specified, Child Page. Now this section can specify all kinds of different information. This can include the post date of a particular page, it can include categories and tags. There's basically no limit on the kind of information that you can include in this top section if you choose, and you're going to see a little bit more of that in later lessons. Now if we go back to our admin panel in the editing interface for this particular markdown file, you'll see we have that title field showing up there. But sometimes, rather than using a field like this, you're gonna want to just directly edit that frontmatter or header section. To do that, what you want to do is hit this button here and switch into expert mode. And now that's just going to give you a plain text field to allow you to directly edit that frontmatter or header section. With a little bit more fine grain control over exactly what gets added. That is particularly useful if you're going to be adding frontmatter that doesn't have anything in the admin GUI to represent it. And you'll see an example of what I am talking about in a lesson that we're gonna go through later, where we're gonna use frontmatter to add some content in a way that doesn't have any predefined fields in the admin panel. Now that said, there is a lot of content that can be put into this frontmatter into this header section, that does have predefined fields in the admin panel. For example, if we switch back into normal mode, and we go into the options tab, we are going to scroll down here and we are just going to add a random category into this taxonomies field and we'll save that. Now when we go back to our mark down file, you can see how that information has been added into the frontmatter or header section. So once again, like we've almost everything in GRAV, you've got those two options. You can directly edit your files or you can use the admin interface. So now that gives you all of the fundamental information that you need. You should now understand the essentials of how page content works in GRAV and how it's organized. And that means that you are ready to start creating your first theme. There are some really cool tools that GRAV includes that allow you to scaffold out a fairly feature rich theme to get the ball rolling for you, but what we're actually gonna do is create all of your files and all of your code from scratch. So that you know exactly what's going on in every one of those files. Later on, you'll probably find that scaffolding tool very helpful, but for now it's probably better to do everything yourself by hand so you know just what files need to be included, what code is absolutely essential and what things can be done optionally. So to get started, in the next lesson, we're going to create the essential theme files. The files that a GRAV theme cannot function without. So we're going to be doing that in the next lesson. I'll see you there.