Grav Tutorial
Grav Tutorial
Audience
This tutorial has been prepared for anyone who has a basic knowledge of Markdown and
has an urge to develop websites. After completing this tutorial, you will find yourself at a
moderate level of expertise in developing websites using Grav.
Prerequisites
Before you start proceeding with this tutorial, we assume that you are already aware about
the basics of Markdown. If you are not well aware of these concepts, then we will suggest
you to go through our short tutorials on Markdown.
All the content and graphics published in this e-book are the property of Tutorials Point (I)
Pvt. Ltd. The user of this e-book is prohibited to reuse, retain, copy, distribute or republish
any contents or a part of contents of this e-book in any manner without written consent
of the publisher.
We strive to update the contents of our website and tutorials as timely and as precisely as
possible, however, the contents may contain inaccuracies or errors. Tutorials Point (I) Pvt.
Ltd. provides no guarantee regarding the accuracy, timeliness or completeness of our
website or its contents including this tutorial. If you discover any errors on our website or
in this tutorial, please notify us at contact@tutorialspoint.com
i
Grav
Table of Contents
About the Tutorial .................................................................................................................................... i
Audience .................................................................................................................................................. i
Prerequisites ............................................................................................................................................ i
GRAV ─ INSTALLATION......................................................................................................... 3
Folders .................................................................................................................................................. 10
Ordering ................................................................................................................................................ 11
Headings ............................................................................................................................................... 15
Comments ............................................................................................................................................. 15
Emphasis ............................................................................................................................................... 17
Notices .................................................................................................................................................. 19
ii
Grav
Lists ....................................................................................................................................................... 22
Code ...................................................................................................................................................... 24
Tables.................................................................................................................................................... 25
Links ...................................................................................................................................................... 27
Images................................................................................................................................................... 28
Slug Relative.......................................................................................................................................... 31
Remote ................................................................................................................................................. 35
Slug Relative.......................................................................................................................................... 38
Absolute ................................................................................................................................................ 40
Remote ................................................................................................................................................. 41
GRAV ─ MEDIA................................................................................................................... 43
Display Modes....................................................................................................................................... 43
Actions .................................................................................................................................................. 44
iii
Grav
Metafiles ............................................................................................................................................... 70
iv
Grav
v
Grav
vi
Grav
vii
Grav
viii
Grav
ix
GRAV ─ OVERVIEW Grav
Grav is a flat-file based content management system. This system does not use database to
store the content, instead it uses a text (.txt) file or a markdown (.md) file to store the
content. The flat-file part refers to the readable text and it handles the content in an easy
way which can be simple for a developer.
Grav was developed by the Rocket Theme team. It runs on PHP and is an open-source CMS
like Joomla, Wordpress or Drupal.
Why Grav?
Grav is now the fastest flat-file content management system. It is easier to publish and
manage content with Grav. It allows a developer to handle content very easily by storing
content in files (such as text or markdown files) rather than in database.
Grav helps you build a simple, manageable and a quick site. It costs less than the database
driven CMS and is useful with I/O for file handling, when you don't have enough resources to
handle database.
Features of Grav
It is a fast, easy and powerful flat-file web platform.
It uses PHP based template provided by Twig which is parsed directly into PHP that
makes it fast.
Advantages
It is not based on database CMS, so it's very easy to install and will be ready to use
when you upload the files to the server.
It uses Markdown text files to make things easy. Using this, the content is dynamically
converted to HTML and displayed in the browser.
In case of security, Grav doesn't have admin area and database. So there is no chance
of hacking into account or in the database to access the important data.
You can easily backup all the files to keep the backup copy of your website, since there
is no database to backup.
Disadvantages
You might come across instances where unauthorized users may access your content
from the files directly as there is no database for the files.
11
GRAV ─ INSTALLATION Grav
In this chapter, we will understand the installation of Grav. We will discuss the software
requirements for Grav and also how to download it.
Web Server
WAMP (Windows)
LAMP (Linux)
XAMP (Multi-platform)
MAMP (Macintosh)
Nginx
Microsoft IIS
Browser Support: IE (Internet Explorer 8+), Firefox, Google Chrome, Safari, Opera
Text Editors:
Notepad ++ (Windows)
Download Grav
Click on this link http://getGrav.org/downloads and follow the steps as shown in the
screenshot given below to download Grav.
12
Grav
Setup Wizard
Installation of Grav is a very simple process. Follow the steps given below for Grav setup.
Download the zip file and extract it to your web server or local host. Rename the folder
from its current name that you want to use to refer to your site.
13
Grav
Grav comes with a sample page that helps you get started. In the above screenshot,
you can see the home link which has displayed a sample page.
14
Grav
Grav Content
15
GRAV ─ PAGES Grav
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.
Step 1: Create a folder under /user/pages/; for example, 02.about as shown in the
following screenshot.
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!
16
Grav
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.
Step 3: Reload your browser and you can see new page in menu as shown in the following
screenshot.
Page Types
Grav Pages supports 3 types of pages:
17
Grav
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.
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.
18
Grav
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.
19
Grav
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.
20
Grav
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.
folder: Folder name consisting of any numerical prefix, e.g. 01., will be removed.
header.x: Any of the page header field can be used for ordering.
21
Grav
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.
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
22
Grav
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().
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>
23
GRAV ─ MARKDOWN SYNTAX Grav
Markdown syntax is defined as writing plain text in an easy to read and easy to write format,
which is later converted into HTML code. Symbols like (*) or (`) are used in markdown syntax.
These symbols are used to bold, creating headers and organize your content.
There are many benefits of using Markdown syntax, some of them are as follows.
When you use markdown there are very few chances of having errors.
Your content and visual display is kept separate so that it does not affect the look of
your website.
24
Grav
In the following sections, we will discuss the main elements of HTML that are used in
markdown.
Headings
Each heading tag is created with # for each heading, i.e., from h1 to h6 the number of #
increases as shown.
Open the .md file in a browser as localhost/Grav/mypage; you will receive the following
result:
Comments
You can write comments in the following format.
<!—
25
Grav
Open the .md file in a browser as localhost/Grav/mypage; you will receive the following
result:
Horizontal rules
Horizontal rules are used to create a thematic break in between paragraphs. You can create
breaks between paragraphs using any of the following methods.
Open the md file in a browser as localhost/Grav/mypage; you will receive the following
result:
26
Grav
Body Copy
Body copy can be defined as writing text in normal format in markdown syntax, no (p) tag
is used
Example
It is a way of writing your plain text in an easy to read and write format, which
later gets converted into HTML code.
Open the .md file in a browser as localhost/Grav/mypage; you will receive the following
result:
Emphasis
Emphasis are the writing formats in markdown syntax that are used to bold, italicize or
strikethrough a portion of text. Let us discuss them below:
Bold
A portion of text can be made bold using two (**) signs at either sides.
Example
27
Grav
The newest articles from **Advance Online Publication (AOP)** and the current issue.
In this example, we have to show ‘Advance Online Publication (AOP)’ word as bold.
Open the .md file in a browser as localhost/Grav/mypage, you will receive the following
result:
Italics
Use “_” (underscores) sign at either sides of the word to italicize the text.
Example
The newest articles from _Advance Online Publication_ (AOP) and the current issues.
Open the .md file in a browser as localhost/Grav/mypage. This will give you the following
result:
Strikethrough
Use two "~~" (tildes) on either sides of the word to strikethrough the word.
28
Grav
Example
The newest articles from ~~Advance Online Publication~~ (AOP) and the current issues.
Open the .md file in a browser as localhost/Grav/mypage.. This will give you the following
result:
Blockquote
To create a block quote, you must add an > sign before the sentence or the word.
Example
>The newest articles from Advance Online Publication (AOP) and the current issues.
Open the .md file in a browser as localhost/Grav/mypage; you will receive the following
result:
>The newest articles from Advance Online Publication (AOP) and the current issues.
>>> The newest articles from Advance Online Publication (AOP) and the current issues.
Open the .md file in a browser as localhost/Grav/mypage; you will receive the following
result:
Notices
Notices can be used to inform or notify about something important.
There are four types of notices — yellow, red, blue and green.
Yellow
You must use the >>> sign before a yellow notice type that describes !Info or information.
Example
Red
Use four >>>> signs before a red notice for a Warning.
Example
30
Grav
Blue
Use five >>>>> signs for a Blue notice type, this describes a Note.
Example
Green
Use six >>>>>> signs before a Green notice type, this describes a Tip.
Example
Open the md file in a browser as localhost/Grav/mypage; you will receive the following
result:
31
Grav
Lists
In this section, we will understand how the unordered and ordered lists work in Grav.
Unordered
In an unordered list, bullets are used. Use *, - , +. symbols for bullets. Use the symbol with
space before any text and the bullet will be displayed.
Example
+ Bullet
+ Bullet
+ Bullet
-Bullet
-Bullet
-Bullet
*Bullet
32
Grav
Open the .md file in a browser as localhost/Grav/mypage; you will receive the following
result:
Ordered
Add the numbers before you list something.
Example
1. Coffee
2. Tea
3. Green Tea
33
Grav
Open the .md file in a browser as localhost/Grav/mypage. This will give you the following
result:
Code
In this section, we will understand how the Inline and block code “fences” work in Grav.
Inline Code
Make inline code using (`) for using codes in markdown.
Example
In the given example, '<section></section>' must be converted into code.
Open the .md file in a browser as localhost/Grav/mypage; you will receive the following
result:
34
Grav
Example
```
Your Text Here
```
Open the .md file in a browser as localhost/Grav/mypage; you will receive the following
result:
Tables
In Grav, tables are created by using pipes and dashes under the header section. Pipes must
not be vertically aligned.
Example
35
Grav
| Number| Points |
| ------| ----------- |
| 1 | Eve Jackson 94|
| 2 | John Doe 80 |
| 3 |Adam Johnson 67 |
Open the .md file in a browser as localhost/Grav/mypage; you will receive the following
result:
| Number| Points |
| ------:| -----------: |
| 1 | Eve Jackson 94|
| 2 | John Doe 80 |
| 3 |Adam Johnson 67 |
Open the .md file in a browser as localhost/Grav/mypage; you will receive the following
result:
36
Grav
Links
In this section, we will understand how links work in Grav.
Basic Links
Links are made with the help of ([]) square brackets and (()) parenthesis. In [] brackets, you
must write the content and in () write the domain name.
Example
[Follow the Given link](http://www.google.com)
Open the .md file in a browser as localhost/Grav/mypage; you will receive the following
result:
Add a Title
In this section, we will understand how to add a title in .md file.
Example
[Google](https://www.gogle.com/google/ "Visit Google!")
Open the .md file in a browser as localhost/Grav/mypage; you will receive the following
result:
37
Grav
Images
Images are similar to a link but have an exclamation point at the start of the syntax.
Example
![Nature] (/Grav/images/Grav-images.jpg)
38
Grav
39