How to render a custom template in pre-existing theme

[piccolopi]

Hi there

I am trying to create a customized template to render the homepage of a website. I am using the FUTURE2021 theme, and for all the other pages except the homepage, I want to use the pre-existing templates that came with the theme.
Online, I have read that I basically have to use TWIG syntax together with the flat HTML (index.html) that I currently have in order to make the template of the homepage.
Knowing this, I got started with adding the TWIG into my HTML (index.html.twig). My issue came when trying to link the actual Homepage (which initially is in the “default” template) to the index.html.twig template.
The things that I have tried without results:

1. Adding the index.html.twig file to the grav-admin/user/themes/future2021/templates/ ; then look for the template in the Dashboard to assign it as a template to the “home”.
   1.1 Result: the template “index” does not show up in the grav GUI dropdown menu.
2. Adding the index.html.twig file to the grav-admin/user/themes/future2021/templates/ ; then change in the folder “pages”, go to “01.home” and change the md file to “index.md”
   2.1 Result: the page renders as if it were still rendering the “default.md”.
3. Adding the index.html.twig file to the grav-admin/user/themes/future2021/templates/ ; then, since I saw that the path on the browser changed accordingly to the name of the content folder (ex: 01.home), I also tried changing the name of “01.home” to “01.index”. This is a bit silly maybe but I had to try.
   3.1 Result: Did not work, the page renders as if it were still rendering the “default.md” & if I point the browser to http://localhost:8000/index, it shows “error page does not exist”

In the documentation, in “cookbook > Migrate an HTML theme to Grav”, I see the process described for creating your own theme, which is not my case because I do not want to create a blank theme, but in any case I followed the logic there for the template process and can’t make it to work.

I was thinking that maybe it does not render because of mistakes in my TWIG code, but seems unlikely that this is the case because how would then people customize if they cannot see what’s actually doing the code?
I want to link the my custom template to the page because I am learning TWIG and I need to see what am I coding right and what wrong. I need the visual support of the page being rendered to learn how to do it.

Can this be done? Maybe a theme can only be used with its own templates and non else? Or am I missing a thing? (I think so… but can’t find any more clues of what I am missing online…)

Thanks a lot in advance just for reading this long question!

[pmoreno]

Hi @piccolopi . Have you tried to clear cache?. Sometimes the changes in your code have not effect until you clear the Grav cache.

[piccolopi]

Hi @pmoreno !

Yes I had tried clearing the cache from the browser several times (forgot to mention it in my question, sorry!!) but did not work. However, since you specified “Grav cache” I went to the Configuration > Twig Templating > Twig caching and disabled it.
After doing so, it worked! Now I can see the plain HTML show up on the homepage Thanks a lot once again Pedro!
Picture here for easiness in case anybody has the same issue:

[anon76427325]

@piccolopi, You should not disable caching of Twig. It is part of Grav’s performance strategy to cache parsed Twig.

What you should do is clearing the cache from the Dashboard in Admin, or run $ bin/grav cache from the command prompt.

These commands will clear the current cache and Grav will restart parsing and caching pages, Twig, etc. with the current definitions of Twig templates, pages, configurations etc.

[piccolopi]

@anon76427325 Thanks a lot! Like this will I do. And much faster to do it using the command, thanks!

[piccolopi]

Sorry for asking something again @anon76427325 @pmoreno … but is there specific documentation/rules regarding creating a custom template within an original theme and its linking to the custom.css? I’ve been hours troubleshooting why the custom template does not link to the custom.css file.
I have tried the following AND each time I have tried each step listed below I also done both of the below:
a) Have cleared cache like you showed me above (bin/grav cache)
b) in system.yaml I have tried with ‘assets: css_pipeline: false’ and with ‘assets: css_pipeline: true’ (this one because I saw your answer @anon76427325 here: Css custom attributes not working)
For context: the body of the HTML is marked all with a TWIG {% block %}. Like: {% block content %} <‘body’> … </‘body’> {% endblock %}

{% block stylesheets %}
{% do assets.css(‘theme://css/custom.css’, 100) %}
{% endblock %}
→ did not work. I also tried without integer and with the following integers: 101, 105, 110 and 10.

<'link type=“text/css” rel=“stylesheet” {{ source(‘custom.css’) }}">
→ I found this online and I tried… It did not work, I get the mistake of "Template “…/assets/css/custom.css” is not defined & it points me to the ‘grav-admin/system/src/Grav/Common/Twig/Twig.php’ and there I don’t see what should I touch, therefore I prefer to not mess up.

{% block stylesheets %}
{% do assets.addCss(‘theme://css/custom.css’, 101)|raw %}
{% endblock %}
→ Since the HTML is still in pure without the TWIG, I thought that maybe adding raw would help (after reading so much Q&A online I just start trying things…)

{% block stylesheets %}
{% do assets.addInlineCss(‘theme://css/custom.css’) %}
{% endblock %}
→ Thought this could be an option to make it work but also not.

{% extends ‘@future2021/partials/base.html.twig’ %}

{% block stylesheets %}
{{ parent() }}
{% do assets.addCss(‘theme://css/custom.css’) %}
{% endblock %}
→ I thought that maybe by linking it to another template, the custom one would render something that I am currently missing (by ‘something’ I imagine some type of connection with the asset manager)

{% block stylesheets %}
{% do assets.addCss(‘theme://future2021/assets/css/custom.css’) %}
{% endblock %}
→ I started doubting the syntax of the link, maybe I am just not linking it correctly. I have tried several paths, none with positive result.

I have found information about customizing a full theme using inheritance, but I am not able to find an explanation for such a basic problem of linking the css. Is this something I am trying (have a totally custom Homepage to a original theme) something too out of the box?
Asking because if it’s something GRAV is not thought for, then I stop trying, because I clearly don’t know enough to be making it happen and I don’t want to bother more with rookie questions.

Thanks a lot for any help

[anon76427325]

@piccolopi, Either I’m confused about your issue, or you are going into the wrong direction…

It seems you want to

• add/adapt one or more templates of an existing theme
• and/or want to add some custom css.

If so, you’ll need to create a so called “child” theme which inherits everything from the “parent”/“original” theme. In the child theme, you can add templates and/or override/adapt inherited templates, add/adapt page blueprints and add/adapt css/js.

For theme customisation using inheritance see Theme Inheritance and use method Inheriting using the CLI to inherit (ie. create a child theme) from the original theme.

If you do not use inheritance but edit the original theme, your changes will be lost when the original theme gets updated.

[piccolopi]

Hi @anon76427325, thanks a lot for your answer.

I was going in the wrong direction, indeed. I thought I did not have to do the theme inheritance because that was only if I wanted to modify the original templates. I actually want to ADD a template, not to modify, and with your comment I saw that also for ADDING (not modifying) a custom template I need to do theme inheritance.

I did the steps from the documentation and created a child theme ‘future2021custom’. Besides the steps described here in inheriting using the CLI, I did as well the part of Using SCSS. The first thing that I noticed is that my child theme had not created an scss folder as the documentation “assumes”. I created it myself. I then did steps 2-4 but then I was not able to find the gulpfile.js neither the package.json files within the parent theme. This confused me so I thought that perhaps Future2021 is a different case than Quark and I needed to regress on these set of steps. I deleted the folder and my changes. Can it be that Future2021 does not have same process as Quark? What made a lot of sense to me is to do step2 (to change the @imports) and which after deleting I no longer have present in my custom template.
While doing the above until step 4, I also did the below. Then, after the deletion of the Using SCSS steps, I also tried rendering my custom template with the below only:

1. Added my custom twig template (index.html.twig) ‘user/themes/future2021custom/templates/’

2. Added my custom.css in ‘user/themes/future2021custom/css/’

3. Added the stylesheet block at the beginning of my index.html.twig as follows:
   {% block stylesheets %}
   {% do assets.add(‘themes://future2021custom/css/custom.css’) %}
   {% endblock %}
   Within this part…:

   • I tried also assets.addCss
   • I tried using ‘extend’ of the base.html.twig template located in the original Future2021 folder

I am wondering what might it be wrong that is avoiding the index.html.twig file to just render the custom.css. How do you do it normally? Inherit theme, create custom twig template and call the custom.css only?
Is it maybe that my index.html.twig is just html with an open and close tag of {% block body %}…{% endblock %}?

Thanks a lot again for your patience and help

[anon76427325]

@piccolopi, themes are not equal… but do share some common concepts.

Since you’ve been fooled by the docs before, it might be wise to use the default Quark theme first. Most of the docs refer to Quark. After you’re getting a feel of Grav, Twig templates, folder structure, blueprints etc., you might switch to another theme and adapt your knowledge to the way the other theme has been build.

If you want to go fast, go slow… A lack of basic knowledge of Grav’s concepts inhibits you to adapt the docs to other themes/situations. That’s slowing you down at the moment…

CSS:

• Future2021 does not use SCSS. You shouldn’t follow the SCSS path.
• In your theme, create file assets/css/custom.css (note the assets folder) and add your css there. Because Future2021 already loads file assets/css/custom.css in /templates/partials/base.html.twig (line 43), it will also be added in your child theme. That’s how inheritance works: It first looks for a file in the child theme and if not existing, it will fallback to the parent theme.

Twig:

• To load your assets/css/custom.css, you don’t need to create a new template.
• If you want to make changes to an existing template, you copy that template from the parent into your child in the same folder path.
• If you really do want to create a new template (index.html.twig) because you want an entirely new type of page, should extend the new template from /partials/base.html.twig.
  Wrt custom.css, since tempate /base.html.twig in the parent theme already loads assets/css/custom.css, you don’t need to add it manually.

Again, you might consider going for theme Quark and start slow…

[pmoreno]

Hi @piccolopi

Inheritance in the Future2021 theme works the same as in any other Grav theme and is well explained in the Grav documentation.

The Future2021 theme does have a SCSS file structure from which you get the final main.css file. On the other hand, it does not have a gulpfile.js file nor does it have a package.json, like Quark; is a theme ported to Grav from HMTL5Up, preserving its original structure. To compile the SCSS files, in my case I use VS Code with the Live Sass compiler extension, running it over the main.scss file, and doing some additional configuration of the extension, you can get a main.css file from Future2021.

Regarding custom styles, you can do the steps suggested by @anon76427325. However, I have created a child theme of the Future2021 theme, in which I have included (as the official Grav documentation for the Quark theme suggests) a main.scss file that imports the SCSS files from the parent theme and also includes a _custom file. scss, to include your custom styles directly in the resulting main.css (in this case this line in main.scss is commented out).

You can use this child theme and follow @anon76427325’s instructions, and tell us how your system is working.

[piccolopi]

Hi @anon76427325 and @pmoreno, thanks a lot again.

First of all, I did not want to imply that the documentation does not explain things well or anything like this, I can’t imagine the difficulty to write a detailed guide for people ranging from noobs like me to more skilled people and that helps everybody in their needs. I actually think that the documentation is very well-written and extremely useful

Answering first to your comment pamtbaau:

• I followed your steps in the child theme folder I had created and it worked. My CSS finally showed up! For this to happen I did:

  • Created the assets folder with /css/custom.css
  • Extend the partials to index.html.twig
  • Make a partials folder and copy there the base.html.twig from the parent theme to the child theme (if I did not do this, the crikey error would tell me that the base.html.twig was not specified.
    → Everything was showing as normal: navbar, header, fafa icons

Thanks a lot, I will save this question thread for the future since all both your answers clarified a lot for me. I am starting a side project with Quark too, I’ll make the learning experiments in there from now on.

Even though with my own created folder structure it worked, I believe it would be even better if I used @pmoreno’s child theme folder structure (thanks a lot!!!). After downloading it, I did:

• Add custom.css

• Add base.html.twig template into the templates>partials folder

• Change the theme in system.yaml. I try loading the homepage. Then:
  → It was throwing me errors in crikey saying that X template were not specified, when I copied the template into the child theme themes directory, then crikey would throw an error for another Z template that was not specified. So I did:

• Copied all templates to the child theme templates folder.
  → The homepage then was showing my own CSS. However the navbar was unstyled (as in plain html only). So what I did:

• Copied all the CSS files in the assets>css folder from the parent theme.
  → The CSS styles show normal now. However I noticed that the fafa icons from the navbar submenus was not showing, so:

• I copied the webfonts folder along with the js and fonts folder from the parent theme to the child one (just to be safe).
  → Everything showed up correctly!
  However, I was left with the doubts of:

• Why would for my own folder structure show up without having to copy files from the parent to the child one? I had not set up any @imports contrary to what you actually did in sass>main.scss. Is somehow the child-theme not importing them anyway? I thought of uncommenting the line of ‘@import ‘custom.scss’;’ but I don’t see why this would change anything.
  Is it maybe that I have to change all the base.html.twig stylesheet block arguments to ‘…/…/…/future2021/assets/css/main’? However this would not explain why it is not importing the templates.
  

  

Then, if I have copied all the above (templates & css) to my child theme and you update the parent theme, updates would not reflect in my child theme? For what I have read, this is what I think would happen but I am not 100% sure.

• I also noticed an anomaly (to me) and it’s that in the Dashboard, the child-theme does not show up even though it is set up in the system.yaml and it does show up in my themes folder. It shows none being active, even though de facto, the future2021-child-theme is the one active. When I write in system.yaml to have the “future2021custom”, then this one does appear as active like normal.
  (I cleared cache various times and logged in and out as well to see if it would appear, but nope).

  • To try troubleshooting this part, I copied the future2021.yaml content to the future2021-child-theme but without result.

  • I compared the blueprints from parent and child but they are the same.

  • The only difference I can think of, is that for “Future2021custom” I used the inheritance method using the CLI, whereas for “Future2021-child-theme” I gitcloned your child-theme into my themes directory. Should I instead inherit with the CLI, AND AFTER, copy your folder into the child-theme?

Here the pic of “Future2021-child-theme” is configured as active in system.yaml but not showing in GUI.

Apologies for this biblical-long comments, I am trying to describe things as good as I can, for you and me but also for future noobs like me that maybe stumble upon the same rookie mistakes.

[anon76427325]

@piccolopi,

Make a partials folder and copy there the base.html.twig from the parent theme to the child theme (if I did not do this, the crikey error would tell me that the base.html.twig was not specified.

That should not be needed!

Steps:

• Create an inheriting theme using the CLI method. Let’s name it ‘myquark’.
• Create file user/themes/myquark/templates/index.html.twig and add the following:

  {% extends 'partials/base.html.twig' %}
  
  {% block content %}
    {{ page.content|raw }}
  {% endblock %}
  

  Inheritance will search for templates/partials/base.html.twig in your own theme and if not found, it will search in the parents theme.
• Create file /pages/03.index/index.md and add some content
• Browse to https://mydomain/index

Note:
This should work for inheriting from Quark or any other theme that contains /templates/partials/base.html.tiwg.

Using SCSS in ‘myquark’ based on Quark:

• Create an inheriting theme using the CLI method. Let’s name it ‘myquark’.
• Create file /themes/myquark/scss/theme.scss and add the following:

  @import '../../quark/scss/theme.scss';
  
  p {
    color: red;
  }
  

• In VSCode, use the following settings for Live Sass

    "liveSassCompile.settings.formats": [
        {
            "format": "expanded",
            "extensionName": ".css",
            "savePath": "~/../css-compiled",
            "savePathReplacementPairs": null
        },
        {
            "format": "compressed",
            "extensionName": ".min.css",
            "savePath": "~/../css-compiled",
            "savePathReplacementPairs": null
        }
    ],
    "liveSassCompile.settings.forceBaseDirectory": "/user/themes/myquark/scss",
  

• Enable Live Sass to watch your /myquark/scss folder.
  Of course, you can replace this with your own scss workflow, as long as the input and output locations are correct.
• Folder /myquark/css-compiled/ should no contain the generate css files.
• Browse to http://mydomain and paragraphs should now be shown in red.

Using SCSS in ‘myfuture’ based on Future2021:

• Create a child theme using CLI. Let’s name it ‘myfuture’
• Create file /myfuture/assets/sass/main.scss and add:

  @import '../../../future2021/assets/sass/main.scss';
  
  p {
    color: red;
  }
  

• In VSCode, use the following settings for Live Sass

    "liveSassCompile.settings.formats": [
        {
            "format": "expanded",
            "extensionName": ".css",
            "savePath": "~/../css",
            "savePathReplacementPairs": null
        },
        {
            "format": "compressed",
            "extensionName": ".min.css",
            "savePath": "~/../css",
            "savePathReplacementPairs": null
        }
    ],
    "liveSassCompile.settings.forceBaseDirectory": "/user/themes/myfuture/assets/sass",
  

• Enable Live Sass to watch your /myfuture/assets/sass folder.
  Of course, you can replace this with your own scss workflow, as long as the input and output locations are correct.
• Folder /myfuture/assets/css/ should now contain the generate css files.
• Browse to http://mydomain and paragraphs should now be shown in red.

Hope this clarifies how to inherit a theme using $ bin/plugin devtools new-theme and reuse/extend the scss provided by the parent theme.
Once you understand the procedure, you’ll know how to do it for each and every theme that uses scss.

Note:
The template errors you mentioned in your previous post after downloading the child theme of Future2021 are probably caused by an incorrect name of the folder of the child theme. Grav will not be able to find the partials in that case. The folder name and the filenames (*.php and *.yaml)) inside it should match.

[pmoreno]

@import ‘…/…/…/future2021/assets/sass/main.scss’;

Thanks @anon76427325 for your correction in main.scss of the future2021 child theme. I’ll fix it in the GitHub repo.

If you want to go fast, go slow…

I wanted to go faster.

[piccolopi]

Hi both,
I don’t use vscode but nvim, so for the methods you described I need to check the alternative to compile scss to css in this case, but I have been researching and there are options For the meantime I will use the first method.

Thanks a lot both for nailing the answers down so accurately.

I will keep the advice and go slow as well. This discussion has been very helpful for me, thanks a lot truly because it makes the learning journey much less lonely.