Assuming you successfully installed Grav with the instructions listed in the previous chapter, we can continue and play around with Grav a little to get you more comfortable.
Because Grav does not require a database, it is pretty easy to work with, without having to worry about causing issues between your Grav installation and any other significant data source. If something goes awry, you can generally recover very easily.
First, let us familiarize ourselves with where Grav stores content. We will go into more depth in a future chapter, but for the time being, you need to be aware that all our user content, is stored in the
user/pages/ folder of your Grav install.
Currently, there are two folders in the pages folder, the first one is called
01.home and the second is
01. portion of the folder is optional but provides a couple of things that can be handy.
Firstly, it lets you expressly define the order of your pages. For example,
01 will come before
00 will come before
The other thing that the numeric portion of the folder name does is explicitly inform Grav this page should be visible in the menu. It is important to note that the numeric portion up to and including the
. will be removed from URLs.
There is an option in the
user/config/system.yaml file that sets the location of the home page, in other words, where Grav points to when you reference the root of your site:
If you examine this configuration file in your install, you will see that it already points to the alias for
/home. We can leave it like this in this example.
Pages in Grav are composed in Markdown syntax. Markdown is a plain text formatting syntax that a computer can readily parse and convert to HTML. It uses basic text symbols to indicate presentation (e.g. bold, italics, headings, lists, etc.), making it easy to write without needing to know the complexities of HTML. Benefits of Markdown include lower error rate, readability, ease of learning and use, etc.
You can read an extensive write-up of available syntax with examples in the documentation, but for now, follow along.
Open the home page in your text editor. The file that controls the homepage is located in the
user/pages/01.home/ folder and is called
default.md. All of the content you create will be created in the
user/pages/ folder in your Grav installation.
When you edit the page in a text editor, the content will look something like this:
# Say Hello to Grav! ## installation successful... Congratulations! You have installed the **Base Grav Package** that provides a **simple page** and the default **Quark** theme to get you started. !! If you see a **404 Error** when you click `Typography` in the menu, please refer to the [troubleshooting guide](https://learn.getgrav.org/troubleshooting/page-not-found).
Let us break this down a little so you can see how easy it is to write in Markdown. The stuff between the
--- indicators are the Page Headers, and these are written in a straightforward format called YAML. This configuration block that sits in the
.md file is commonly known as YAML Front Matter.
title: Home body_classes: title-center title-h1h2
This block sets the HTML title tag for the page (the text you see in the browser tab). You can also access this from your themes via the
page.title attribute. There are a few standard headers that let you configure a variety of options for this page. Another example is
menu: Something that lets you override the text used to display the name of the page in a menu. By default, Grav will use the title for the menu value.
# Say Hello to Grav! ## installation successful...
hashes syntax in markdown indicates a title. A single
# with a space and then text converts into an
<h1> header in HTML.
## or double hash would convert into an
<h2> tag. Of course, this goes all the way up to the HTML valid
<h6> tag which of course, would be six hashes:
###### My H6 Level Header.
Congratulations! You have installed the **Base Grav Package** that provides a **simple page** and the default **Quark** theme to get you started.
This is a simple paragraph that would have been wrapped in regular
<p> tags when converted to HTML. The
** markers indicate bold text or
<b> in HTML. Italic text is indicated by wrapping text in
!! If you see a **404 Error** when you click `Typography` in the menu, please refer to the [troubleshooting guide](https://learn.getgrav.org/troubleshooting/page-not-found).
This section uses a custom markdown feature that is provided by the included
markdown-notices plugin. This allows you to create simple notices by prefix a paragraph of text with a number of
! (apostrophe) symbols, from
This overview should provide you with a few key pointers for writing Markdown, but you should check out our more detailed explanation to get a thorough understanding.
Ensure you save your
.md files as
UTF8 files. This will ensure they work with language-specific special characters.
Creating a new page is a simple affair in Grav. Just follow these simple steps:
user/pages/and create a new folder. In this example, we will use explicit default ordering and call the folder
# My New Page! This is the body of **my new page** and I can easily use _Markdown_ syntax here.
default.md. This will tell Grav to render the page using the default template in the current theme:
The page will automatically show up in the Menu after the "Typography" menu item. If you wish to change the name that shows up in the Menu, add:
menu: My Page between the dashes in the page content.
Congratulations, you have now successfully created a new page in Grav. There is much more you can do with Grav, so please continue reading to find out about more advanced capabilities and in-depth features.
If you have any issues accessing this new page, you are either missing an
.htaccess file (Apache web server only) or you may need to edit the
RewriteBase command in the
.htaccess file. Please consult the Troubleshooting section for more information.
Found errors? Think you can improve this documentation? Simply click the Edit link at the top of the page, and then the icon on Github to make your changes.