Kun olet työskennellyt Grav CMS:n kanssa useita vuosia, sinulle kertyy joukko pätkiä, jotka kulkevat mukana projektista toiseen. YAML frontmatter, Twig-pohjat, syntaksin korostuksen asetukset, Atomin regex-kuviot: dokumentaation tai vanhan repositorion kaivelu joka kerta tuhlaa aikaa. Varsinkin silloin, kun Grav pyörii VPS:llä ja sinun täytyy muistaa, miten PHP 8.3:n sqlite-ajuri asennetaan oikein tai miten SetHandler kommentoidaan pois Apache-päivityksen jälkeen.

Tämä muistilista on tislaus todellisesta käytännön työstä: oletusotsake, Markdown-asetukset sivuille, Twig-pätkät postauksen rungossa, Atom-regex.md-vientien jälkikäsittelyyn ja Ubuntu-palvelimen komennot. Kaikki yhdessä paikassa, selityksineen mitä ja miksi.

💡 Pikakatsaus:

• Määritä Gravin YAML frontmatter kaikilla kentillä: taxonomy, page-toc, highlight, process, custom page-addon
• Aseta Markdown-logiikka sivun otsakkeisiin: title, description, date, taxonomies, template
• Lisää Twig-koodia runkoon: automaattinen sisällysluettelo toc()-funktiolla, Unitegallery-galleria
• Käsittele Writage.md-viennit Atomissa: media/-polkujen korvaaminen, luokkien välittäminen lazy loadia varten
• Pystytä palvelinympäristö: SQLite, Memcached, PHP 8.3 Ubuntu 24.04:llä, php*.conf-tiedostojen muokkaus Virtualmin-ympäristöä varten

Gravin oletusotsake kaikille sivuston sivuille

Gravisivun YAML frontmatterin peruskentät sisältävät ne tiedot, jotka CMS lukee renderöinnin aikana. Alla on toimiva pohja, joka kattaa useimmat tyypilliset tehtävät taksonomioista mukautettuihin page-addon-lippuihin.

1
title: ''
2
date: '2026-06-14 10:00'
3
published: true
4
media_order: poster.jpg
5
metadata:
6
    description: ''
7
taxonomy:
8
    category:
9
    - WordPress
10
    tag:
11
    - WordPress - Plugins
12
    - WordPress - Admin
13
page-toc:
14
    active: true
15
template: blog_item
16
highlight:
17
    enabled: true
18
    lines: true
19
page-addon:
20
    ifarmelazy: true

page-toc.active: true aktivoi Page Toc -lisäosan (GitHub), joka rakentaa sisällysluettelon H1-H6-otsikoista suoraan sivulle. template: blog_item asettaa nimenomaisesti blogin alasivun pohjan, jotta Grav ei päättele sitä heuristisesti jokaisella renderöintikerralla.

page-addon-lohko on mukautettu osio käyttäjän määrittämille lipuille. Tässä ifarmelazy: true ottaa käyttöön lazy loadingin iframeille: tiedostossa user/themes/g5_helium/custom/templates/partials/blog_item.html.twig laukeaa ehto, joka lataa iframe.ly-skriptin.

1
{% if attribute(page.header, 'page-addon').ifarmelazy %}
2
   <script async charset="utf-8" src="//cdn.iframe.ly/embed.js"></script>
3
{% endif %}
4

Itse iframen (esimerkiksi YouTube-videon) lisäämiseen käytä tätä rakennetta:

1
<iframe allowfullscreen
2
  data-iframely-url="https://www.youtube.com/embed/54WI1XSilb4"
3
  scrolling="no"
4
  style="border: 0; top: 0; left: 0; width: 100%; height: 100%; position: absolute;">
5
</iframe>

Markdown-asetukset postaussivujen otsakkeisiin

Tämä osio kattaa kentät, jotka määritetään kunkin yksittäisen postauksen otsakkeessa.

Otsikko ja kuvaus

1
title: 'Grav + Gantry 5 — an overview of useful extensions and resources'
2
metadata:
3
    description: 'A collection of Grav extensions for Gantry 5 that speed up work with content and templates.'

Kuvaus menee <meta name="description"> -tagiin ja on tärkeä hakutulosten katkelmissa.

Luontipäivä ja Auto Date

1
date: '2026-06-14 10:00'

Jotta päivämäärä asetetaan automaattisesti sivua luotaessa, asenna Auto Date -lisäosa, github.com/getgrav/grav-plugin-auto-date. Se lisää nykyisen päivämäärän ja kellonajan, jos date-kenttää ei ole täytetty käsin.

Taksonomiat

Yhdelle kategorialle ja yhdelle tagille käytä litteää syntaksia:

1
taxonomy:
2
    category: WEB
3
    tag: Markdown

Useille arvoille käytä listamuotoa:

1
taxonomy:
2
    category:
3
    - Grav
4
    tag:
5
    - Grav - Gantry 5
6
    - Grav - Plugins

Sivun sisällysluettelo ja mallipohja

Sivun sisällysluettelo luo otsikkoluettelon sivun rungon otsikoista. page-toc.active: true -lipun lisäksi ylätunnisteeseen voit lisätä Twig-koodia suoraan teemamalliin (katso alla oleva Twig-osio).

template: blog_item määritetään manuaalisesti, jotta Grav käyttää varmasti blogikirjoituksen alimallia, sillä CMS epäonnistuu toisinaan uusien sivujen automaattisessa tunnistuksessa.

Markdown- ja Twig-esikäsittelijät

1
process:
2
    markdown: true
3
    twig: true
4
twig_first: true

twig_first: true tarkoittaa, että Grav käsittelee ensin Twig-mallinnusmoottorin ja sitten Markdownin. Järjestys on ratkaiseva, jos sivun runko sisältää Twig-logiikkaa, joka tuottaa Markdown-merkintää.

Syntaksin korostus (Highlight)

Riippuu Highlight-lisäosasta, github.com/getgrav/grav-plugin-highlight.

1
highlight:
2
    enabled: true
3
    lines: true

lines: true lisää rivinumerot korostettuihin koodilohkoihin.

Twig-asetukset sivun rungolle

Automaattinen sisällysluettelo toc()-funktiolla

Sivun sisällysluettelo voi toimia paitsi ylätunnisteen kautta myös suoralla lisäyksellä teemamalliin. Lisää tiedostoon user/themes/g5_helium/custom/templates/partials/blog_item.html.twig:

1
{# PAGE TOC START #}
2
{#
3
page-toc:
4
    active: true
5
 #}
6
{% if attribute(page.header, 'page-toc').active %}
7
        {% set table_of_contents = toc(page.content) %}
8
      {% if table_of_contents is not empty %}
9
      Table of contents:
10
      {{ table_of_contents|raw }}
11
      {% endif %}
12
 
13
{% endif %}
14
{# PAGE TOC END #}
15

Twig-funktio toc(page.content) jäsentää page.content-kentän otsikot ja palauttaa rakenteellisen puun. Ehto tarkistaa page-toc.active-lipun ylätunnisteesta, jolloin voit ottaa sisällysluettelon käyttöön tai poistaa sen käytöstä yksittäisillä sivuilla koskematta malliin.

Kuvagalleria Unitegalleryn avulla

Unitegallery-lisäosa, github.com/variar/grav-plugin-unitegallery, lisää Grav-sivustolle gallerian, joka perustuu Unitegallery JS -kirjastoon ja tarjoaa useita näyttöteemoja.

Asennuksen jälkeen hallintapaneelin tai GPM:n (Grav Package Manager) kautta sivun runkoon lisätään yksi rivi:

1
{{ unite_gallery(page.media.images) | raw }}
2

Se renderöi kaikki sivun mediakokoelmaan ladatut kuvat galleriana.

Atom-haku ja -korvaus Writage.md-vienneille

Kun WordPress-kirjoituksia viedään Markdowniin Writagen kautta, kuvapolut sisältävät media/-etuliitteen, ja lazy loadingin käyttöönotto vaatii figure-img- ja img-fluid-luokat. Jokaisen URL-osoitteen manuaalinen muokkaus on turhaa; Atom ja säännölliset lausekkeet hoitavat sen sekunnissa.

Lazy Image -lisäosa hoitaa lazy loadingin, github.com/unsaturated/grav-plugin-lazy-image.

Etsi (säännöllinen lauseke):

1
(![.*]()(media/)(.*)())

Korvaa lightbox-versiolla (FeatherLight-lisäosa):

1
$1$3)

Korvaa vain laiskalla latauksella:

1
$1$3?classes=figure-img,img-fluid)

Korvauksen jälkeen kuva saa classes-kyselyparametrin, jonka Lazy Image poimii.

Pikkukuvien kanssa työskentely

Grav osaa käsitellä kuvia dynaamisesti: muuttaa kokoa, rajata, välimuistittaa. Sivun pikkukuva asetetaan Markdown-syntaksilla kyselyparametrein:

1
![ALT Image](https://learn.getgrav.org/20/content/media)

Lisää mediaominaisuuksista virallisessa dokumentaatiossa: learn.getgrav.org/content/media.

Ubuntu 24.04 -palvelimen asennus Gravia varten

Grav VPS-palvelimella vaatii PHP:n, SQLiten (lisäosien sisäistä tietokantaa varten) ja mieluiten Memcachedin (sivujen välimuistitukseen). Alla ajantasaiset komennot Ubuntu 24.04 LTS:lle ja PHP 8.3:lle.

PDO SQLiten asentaminen PHP 8.3:een

1
sudo apt-get update
2
sudo apt-get install php8.3-sqlite
3
sudo systemctl restart apache2

Grav käyttää SQLiteä lokien, lisäosien välimuistin ja sisäisen kirjanpidon tallentamiseen. Ilman ajuria hallintapaneeli kaatuu tietokantayhteysvirheeseen.

Memcachedin asentaminen

Ajantasaiset ohjeet: tecadmin.net/install-memcached-with-php-on-ubuntu/.

1
sudo apt-get update
2
sudo apt-get install memcached
3
 
4
sudo add-apt-repository ppa:ondrej/php
5
sudo apt-get update
6
sudo apt-get install -y php php-dev php-pear libapache2-mod-php
7
 
8
sudo apt-get install -y php-memcached
9
 
10
sudo systemctl restart apache2

PHP-tiedostot eivät suoritu versiovaihdon jälkeen (Virtualmin/Webmin)

Kun vaihdat PHP 7.x:stä versioon 8.3, Apache saattaa tarjota .php-tiedostoja tekstinä sen sijaan, että se suorittaisi ne. Tämä on tunnettu käyttäytyminen moduuleja vaihdettaessa. Ongelma on PHP-moduulin asetuksissa olevat SetHandler-direktiivit.

1
sudo nano /etc/apache2/mods-enabled/php8.3.conf

Kommentoi nämä rivit pois:

1
  # SetHandler application/x-httpd-php
2
  # SetHandler application/x-httpd-php-source

Lopullinen php8.3.conf muokkausten jälkeen:

1
<filesmatch ".+\.ph(ar|p|tml)$">
2
  # SetHandler application/x-httpd-php
3
</filesmatch>
4
<filesmatch ".+\.phps$">
5
  # SetHandler application/x-httpd-php-source
6
  # Deny access to raw php sources by default
7
  # To re-enable it's recommended to enable access to the files
8
  # only in specific virtual host or directory
9
    Require all denied
10
</filesmatch>
11
 
12
  # Deny access to files without filename (e.g. '.php')
13
&lt;filesmatch &quot;^\.ph(ar|p|ps|tml)$&quot;&gt;
14
    Require all denied
15
</filesmatch>
16
 
17
  # Running PHP scripts in user directories is disabled by default
18
  #
19
  # To re-enable PHP in user directories comment the following lines
20
  # (from <IfModule ...> to </IfModule>.) Do NOT set it to On as it
21
  # prevents .htaccess files from disabling it.
22
<ifmodule mod_userdir.c="">
23
    <directory /home/*/public_html>
24
        php_admin_flag engine Off
25
    </directory>
26
</ifmodule>

Kun olet muokannut tiedostoa, käynnistä Apache uudelleen:

1
sudo systemctl restart apache2

Video: mikä Grav CMS on ja mistä aloittaa

Lyhyt johdanto Graviin niille, jotka kuulevat tiedostopohjaisesta CMS:stä ensimmäistä kertaa: mitä konepellin alta löytyy, miten sisältö on rakennettu ja miksi ilman tietokantaa toimiminen voi olla nopeampaa.

⁉️🤔 Usein kysytyt kysymykset

Tarvitseeko Grav tietokantaa?

Ei, Grav on tiedostopohjainen CMS. Kaikki sisältö, asetukset, taksonomiat ja metatiedot tallennetaan tekstitiedostoihin (Markdown ja YAML). SQLiteä käytetään valinnaisesti sisäisiin tarpeisiin: liitännäisten välimuistiin, lokeihin ja jonoihin. PostgreSQL ja MySQL eivät ole virallisesti pakollisia. Käytännössä tämä tarkoittaa, että sivuston varmuuskopiointi on pelkkä /user-kansion kopioiminen.

Onko Page Toc -liitännäinen pakollinen sisällysluettelolle?

Sen voi korvata suoralla Twig-koodilla käyttämällä toc(page.content)-funktiota teemapohjassa. Mutta liitännäinen on kätevämpi nopeaan käyttöönottoon ja poistoon lipun avulla tietyn sivun YAML-etumateriaalissa. Jos sivustollasi on yli 50 sivua, hallinta otsikkotietojen kautta on käytännöllisempää kuin ehtolauseiden tekeminen pohjaan.

Miten Highlight eroaa Prism.js:stä tai Highlight.js:stä?

Highlight on virallinen Grav-liitännäinen, joka integroi highlight.js:n suoraan renderöintiputkeen. Se ymmärtää enabled- ja lines-liput YAML-otsikosta eikä vaadi manuaalista JS/CSS-sisällytystä; GPM hoitaa kaiken. Prism.js pitäisi sisällyttää manuaalisesti teemaan.

Onko Grav yhä relevantti vuonna 2026 verrattuna WordPressiin?

Tiettyihin käyttötarkoituksiin kyllä. Grav on ylivoimainen staattisille käyntikorttisivustoille, portfolioille, dokumentaatioille ja laskeutumissivuille, joissa ei tarvita monimutkaista käyttäjähallintaa tai verkkokauppaa. Tiedostopohjainen arkkitehtuuri tarjoaa välittömän vasteajan ilman tietokantaa, ja sisällön versiohallinta toimii Gitin kautta. Mutta blogiin, jossa on tuhansia artikkeleita, medialaaja kirjasto ja dynaamiset arkistot, WordPress on käytännöllisempi liitännäisekosysteeminsä ansiosta.

Mitä teen, jos Gravin hallintapaneeli lakkaa toimimasta PHP-päivityksen jälkeen?

Kolme tyypillistä syytä: (1) php8.x-sqlite ei ole asennettu, ja Grav kaatuu hiljaisesti ilman tietokanta-ajuria; (2) SetHandler-riviä ei ole kommentoitu pois php8.x.conf-tiedostossa Virtualminia käytettäessä, ja Apache tarjoilee .php-tiedostoja tekstinä; (3) cache/-, logs/- ja backup/-kansioiden käyttöoikeudet /user-hakemiston sisällä ovat nollautuneet, joten aja chown -R www-data:www-data user/.

Valmis muistilista: mitä kopioida omaan projektiisi

Kuusi tiedostoa ja liitännäistä, joilla tyypillinen Grav-projekti käynnistyy VPS:llä: otsikko taksonomioilla ja page-toc:lla, Twig-sisällysluettelo pohjassa, Markdown-esikäsittelijä, Highlight, Unitegallery ja Atom-regex vientien jälkikäsittelyyn. Lisää palvelinasetukset Ubuntu 24.04 -osiosta, ja sinulla on täysin valmis ympäristö puolessa tunnissa. Pidä tämä sivu kirjanmerkeissä; päivitämme koodinpätkät vastaamaan ajantasaisia Grav- ja PHP-versioita.