How to work with files in Grav?

[dudenas]

Hi hosters,

I happily installed Grav and immediately got confused - how do I work with it? Naturally I need editing files - theme, CSS and so on. I can access the files via ftp only as root.
But it seems very inefficient and insecure to develop it as root. Also I’d have to keep changing file permissions back to grav/www-data. Intuition tells me that working in Atom or Vscode via ftp plugins connecting as root is also a bad idea.

So what would be the civilized way to work with Grav?

[tituspijean]

You have an admin panel with an integrated editor if you want, available if you add /admin after the path where you installed Grav.

SFTP can be a solution too, and indeed the files ownership is an issue that has not been adressed yet. Try the editor first.

[dudenas]

Default UI does not let you work with files other than pages. There is also a weird plugin called ‘editor’, which allows editing files by extension - only of given extensions and only existing files. Not even remotely fit for creating a new theme.
I’m thinking, is it possible to give SFTP access rights to ‘grav’ user? Might it be a solution?

[tituspijean]

Ah, I knew I saw something related to your issue recently. Here is a tutorial that’s yet to be merged in the documentation: SFTP on apps permissions by zamentur · Pull Request #1836 · YunoHost/doc · GitHub

Let us know if that suits your needs.

In the example for Wordpress there, you can replace any instance of “wordpress” by “grav” and use your username instead of “USER”. You can ignore the line about /var/www/wordpress/wp-config.php

[rodinux]

Hi, to make a child theme, is a little different with grav. I do one, but it was not so easy.
See doc: https://learn.getgrav.org/16/themes/theme-tutorial

• You need install the DevTools Plugin
• Navigate in the command line to the root of your Grav installation cd /var/www/grav, I do this with root user (first sudo -i)
• then sudo -u grav php7.3 bin/plugin devtools new-theme
  This process will ask you a few questions that are required to create the new theme: you can create a simple inheritance style template that inherits from another base theme. I have use this using an inherit Quark theme.
• In order to see your new theme in action, you will need to change the default theme from quark to yourtheme, so edit your user/config/system.yaml and change it:

pages:
    theme: yourtheme

something like sudo nano user/themes/yourtheme/yourtheme.yaml
to add at the end of the file the same as the inherit file /user/themes/quark/quark.yaml

for example for me a theme inherit of quark

streams:
 schemes:
   theme:
     type: ReadOnlyStream
     prefixes:
       '':
         - 'user://themes/mytheme'
         - 'user://themes/quark'

enabled: true
production-mode: true
grid-size: grid-lg
header-fixed: true
header-animated: true
header-dark: false
header-transparent: false
sticky-footer: true
blog-page: '/blog'
spectre:
  exp: false
  icons: false

Next

These items are critical and your theme will not function reliably unless you include these in your theme.

• blueprints.yaml - The configuration file used by Grav to get information on your theme. It can also define a form that the admin can display when viewing the theme details. This form will let you save settings for the theme. This file is documented in the Forms chapter.
• yourtheme.php - This file will be named according to your theme, but can be used to house any logic your theme needs. You can use any plugin event hook except onPluginsInitialized(), however there is a theme specific onThemeInitialized() hook specific for themes that you can use instead.
• yourtheme.yaml - This is the configuration used by the plugin to set options the theme might use.
• templates/ - This is a folder that contains the Twig templates to render your pages.

Ok, I let you continue reading the documentation here Theme Tutorial | Grav Documentation

You will need edit user/themes/yourtheme/blueprints.yaml, same as yourtheme.yaml I just copy the inherit file user/themes/quark/blueprints.yaml and paste it at the end of the file.

then, to change css, you can edit a file nano user/themes/yourtheme/css/custom.css

To change the footer mkdir user/themes/yourtheme/templates/partials and nano user/themes/yourtheme/templates/partials/footer.html.twig

etc…

hope it will help you

[dudenas]

Thank you so much! Very detailed instructions. I’ll definitely try them out.
Maybe this is worth to be added to yunohost/grav documentation?

[rodinux]

The link in the Grav doc to customize and the steps I suggest you is this one: Customization | Grav Documentation