Blueprints.yaml – how to add fields?

Hi there
I am just starting my first GRAV project and I am quite ready to start. Only some custom fields are needed.

While the docs are pretty detailed and well described (both thumbs up!!) I feel like that part is a little short.

Do I have to put my field settings into user/themes/themename/blueprints.yaml?
Or do I have to create a new file? Do blueprints definitions (names) have to match the names of pages or template files?

Could someone please post an example of how to add a new (e.g. text) field?

Many thanks!

  • Sebastian

Actually, the file user/themes/themename/blueprints.yaml will indicate the details about the theme you are using, who is the author, version, etc. so it is not the file that you should use.
Instead, you can edit files that are in the folder user/themes/themename/blueprints/yourfile.yaml

Create in this folder your blueprints, for example, you can create a blueprint named biography.yaml in this folder, and then, if you want to use it on a specific page, browse to your user/pages/ folder and rename the file inside your page folder from to and it’s done.

Regarding the details on how to make your custom fields, there is some good example on

Hope it helps!

paulmassendari, thanks for your help.

I got the principles of adding new fields but the »example page blueprints« wasn’t that helpful for me. For example I couldn’t figure out how to add another markdown editor. Do I need to add an "Editor Field«? And where is the documentation of how the blueprints have to structured, what kind of fields I can add and how to reorder them?

If you want to add another markdown editor, you can use the code below in your blueprint:

    type: markdown
        type: textarea

If you just want to add a textarea, you can use:

              type: textarea
              label: this is some text area

Yaml syntax is a bit tricky indeed, and the only way to know you made a mistake is because you will notice that the default blueprint is loaded instead of yours.

I read somewhere that indentation of the code must be with spaces (2 or 4 spaces most of the time) so you should always avoid tabs.

I don’t know if it is because it’s a WIP but it’s true that this page does not mention the possibility to add a markdown editor. Maybe there’s a reason to that?

Let me know how it works!

It works! Don’t want to bother … but any idea to change the position of the fields? Currently my custom fields go below the Page Media. Maybe this is not a big problem, because I need to have almost completely custom pages for all pages (only 6 ).

It’s because you extended the default blueprint with these lines

title: Gallery
    type: default
    context: blueprints://pages

So anything written after these lines will appear after the page media field.
In the future grav update you will be able to embed pre existing blueprints but for now, you should start with a totally custom template like here:

Then, the fields will appear in the same order as in the file

Thanks! Actually that was obvious :slight_smile: But there is so much new for me I must have missed that.

How did you transform the extra markdown fields to HTML in twig? Below you can find my blueprint yaml file. It gives a markdown editor in the grav admin, but when printing in twig, the raw markdown is rendered.

— twig
{{ page.header.details }}

--- yaml
title: Solutions
    type: default
    context: blueprints://pages

      type: tabs
      active: 1

              type: markdown
              label: Details 

Seriously, you’ll find a lot of answers in the documentation. It’s very well!

— {{ page.header.details|markdown }}

Oh, and regarding the ordering:

On that page of the help, you will also find a way to unset, replace fields like for example the default editor and how to import partials of blueprints. I find Grav superb (apart from some small limitations) for creating very custom pages. But I have to admit I just started a few weeks ago.

Thanks! You’re right, great docs. Must have missed it.