Grav Howto (1)

This howto is based on the following documentation:

Installation

The different components for the installation can be found under the following links:

NOTE:

The theme Quark as well as the plugins Problems & Error are part of the Grav core package.

Download and unzip the Grav core package:

file='grav.zip'

cd '<HTDOCS>'

curl --output "${file}" 'https://getgrav.org/download/core/grav/latest'

unzip -q "${file}" -d '.'

rm "${file}"

Remove the Quark theme package & install the theme from the repository using Git:

cd '<HTDOCS>/grav'

./bin/gpm uninstall 'quark'

cd 'user/themes'

git clone --branch='master' 'https://github.com/getgrav/grav-theme-quark.git' \
  'quark'

Install additional plugins:

cd '<HTDOCS>/grav'

./bin/gpm install --force 'archives' 'feed' 'page-inject' 'pagination' 'sitemap' \
                          'taxonomylist' 'unitegallery'

Set file permissions:

cd '<HTDOCS>/grav'

sudo chown --recursive 'alex:users' '.'

find '.' -type 'd' -execdir chmod 1775 '{}' '+'
find '.' -path './bin' -prune -or -type 'f' -execdir chmod 0644 '{}' '+'
find './bin' -type 'f' -execdir chmod 0755 '{}' '+'

Open the site in the standard browser:

open 'https://www.examle.com/grav/'

Update

Update the Quark theme:

cd '<HTDOCS>/grav/user/themes/quark'

git pull

Update Grav itself, all installed plugins & themes:

cd '<HTDOCS>/grav'

for command in 'self-upgrade' 'update'; do  
  ./bin/gpm "${command}" --force
done

Set file permissions:

cd '<HTDOCS>/grav'

sudo chown --recursive 'alex:users' '.'

find '.' -type 'd' -execdir chmod 1775 '{}' '+'
find '.' -path './bin' -prune -or -type 'f' -execdir chmod 0644 '{}' '+'
find './bin' -type 'f' -execdir chmod 0755 '{}' '+'

Verify the security and the YAML configuration files:

cd '<HTDOCS>/grav'

for command in 'security' 'yamllinter'; do  
  ./bin/grav "${command}" --verbose --verbose
done

Open the site in the standard browser:

open 'https://www.example.com/grav/'

Configuration

Edit the configuration files:

Create configuration directories for themes & plugins:

cd '<HTDOCS>/grav/user/config'

mkdir 'themes' 'plugins'

Theme: Quark

Quark is the new default theme for Grav CMS. This theme is built with the Spectre.css framework and provides a powerful base for developing your own themes.^[1]

Project Homepage [EN]

Skeleton: Blog Site
- Example files [EN]
- Demo [EN]

Skeleton: One-Page
- Example files [EN]
- Demo [EN]

Create a configuration file for this theme:

cd '<HTDOCS>/grav/user/config/themes'

cp '<HTDOCS>/grav/user/themes/quark/quark.yaml' '.'

Edit the configuration file:

<HTDOCS>/grav/user/config/themes/quark.yaml

Copy logo & icon:

cp 'rpl-icon.ico' '<HTDOCS>/grav/favicon.ico'
cp 'rpl-icon.ico' '<HTDOCS>/grav/user/themes/quark/images/favicon.ico'
cp 'rpl-icon.ico' '<HTDOCS>/grav/user/themes/quark/images/favicon.png'
cp 'rpl-logo.png' '<HTDOCS>/grav/user/themes/quark/images/grav-logo.svg'

Edit the CSS file & the footer Twig file:

Plugin: Archives

Archives is a Grav plugin that automatically appends a month_year taxonomy to all pages. It then provides a partials/archives.html.twig template which you can include in a blog sidebar, that then is able to create links that will display pages from that month/year. This is a very handy feature to have for blogs.^[2]

Project Homepage [EN]

Create a configuration file for this plugin:

cd '<HTDOCS>/grav/user/config/plugins'

cp '<HTDOCS>/grav/user/plugins/archives/archives.yaml' '.'

Edit the configuration file:

<HTDOCS>/grav/user/config/plugins/archives.yaml

Plugin: Feed

Feed is a Grav plugin and allows Grav to generate feeds of your pages. This plugin supports Atom 1.0, RSS and JSON feed types.^[3]

Project Homepage [EN]

Create a configuration file for this plugin:

cd '<HTDOCS>/grav/user/config/plugins'

cp '<HTDOCS>/grav/user/plugins/feed/feed.yaml' '.'

Edit the configuration file:

<HTDOCS>/grav/user/config/plugins/feed.yaml

Customize the base Twig file:

<HTDOCS>/grav/user/themes/quark/templates/partials/base.html.twig
- Insert before the {% endblock head %} marker

Plugin: Page Inject

Page Inject is a powerful Grav plugin that lets you inject entire pages or page content into other pages using simple markdown syntax.^[4]

Project Homepage [EN]

Create a configuration file for this plugin:

cd '<HTDOCS>/grav/user/config/plugins'

cp '<HTDOCS>/grav/user/plugins/page-inject/page-inject.yaml' '.'

Edit the configuration file:

<HTDOCS>/grav/user/config/plugins/page-inject.yaml

Plugin: Pagination

Pagination is a Grav plugin that allows to divide articles into discrete pages.^[5]

Project Homepage [EN]

Customize the pagination Twig file:

<HTDOCS>/grav/user/plugins/pagination/templates/partials/pagination.html.twig
- Replace {% set base_url = base_url|default(page.url) %} by {% set blog_url = page.header.blog_url %}
- Replace base_url by blog_url

Plugin: Sitemap

Sitemap is a Grav plugin that generates a map of your pages in XML format that is easily understandable and indexable by Search engines.^[6]

Project Homepage [EN]

Create a configuration file for this plugin:

cd '<HTDOCS>/grav/user/config/plugins'

cp '<HTDOCS>/grav/user/plugins/sitemap/sitemap.yaml' '.'

Edit the configuration file:

<HTDOCS>/grav/user/config/plugins/sitemap.yaml

The sitemap is available under the URLs https://www.example.com/grav/sitemap and https://www.example.com/grav/sitemap.xml.

Plugin: Taxonomy List

Taxonomy List is a Grav plugin that generates a list of linked tags collected throughout the site.^[7]

Project Homepage [EN]

Plugin: Unitegallery

Unitegallery is a Grav plugin that provides Twig extension for creating images gallery using Unitegallery javascript library.^[8]

Project [EN]
Example files [EN]

List all available gallery themes:

ls '<HTDOCS>/user/plugins/unitegallery/vendor/unitegallery/themes'

Output:

carousel  compact   default   grid      slider    tiles     tilesgrid video

Create a configuration file for this plugin:

cd '<HTDOCS>/grav/user/config/plugins'

cp '<HTDOCS>/user/plugins/unitegallery/unitegallery.yaml' '.'

Edit the configuration file:

<HTDOCS>/grav/user/config/plugins/unitegallery.yaml

Create a gallery Twig file:

<HTDOCS>/grav/user/themes/quark/templates/modular/gallery.html.twig

Create a gallery within the Blog directory:

cd '<HTDOCS>/user/pages/01.blog/article1'

mkdir '_gallery-my_photos_1'

Add images to the directory _gallery-my_photos_1

Create a configuration file for the gallery:

<HTDOCS>/grav/user/pages/01.blog/article1/_gallery-my_photos_1/gallery.md

Edit the Blog file <HTDOCS>/grav/user/pages/01.blog/article1/item.md:

Add to the header:

page-inject:
    active: true
    processed_content: true

Add to the body:

[plugin:page-inject](_gallery-my_photos_1)

Verify

Verify the security and the YAML configuration files:

cd '<HTDOCS>/grav'

for command in 'security' 'yamllinter'; do  
  ./bin/grav "${command}" --verbose --verbose
done

References

[1] ttps://github.com/getgrav/grav-theme-quark

[2] ttps://github.com/getgrav/grav-plugin-archives

[3] ttps://github.com/getgrav/grav-plugin-feed

[4] ttps://github.com/getgrav/grav-plugin-page-inject

[5] ttps://github.com/getgrav/grav-plugin-pagination

[6] ttps://github.com/getgrav/grav-plugin-sitemap

[7] ttps://github.com/getgrav/grav-plugin-taxonomylist

[8] ttps://github.com/variar/grav-plugin-unitegallery

[1]

[2]

[3]

[4]

[5]

[6]

[7]

[8]