Theme Configurations with YAML

It is highly recommended to add some meta-information to your theme. This is quickly done with a small YAML-file, which must have the same name as your theme folder. The YAML-file has up to three parts and is used for the following:

• Display basic information in the author-panel, and generate update notifications.
• Use settings (variables) for your theme, if you made any.
• Let users edit the settings and customize the theme in the author-panel.

Add Basic Informations

The basic informations in the YAML-file look like this:

name: My Theme Name
version: 1.0.0
description: Write what you want
author: Your name here
homepage: http://an-info-website-for-the-theme.com
licence: MIT

As you can see, the YAML-syntax is simple and readable even for non-technical people. Inside TYPEMILL, the YAML-files are converted to one-dimensional or multi-dimensional arrays, so you can think about YAML as a simplified array language, if that helps.

Add a Donation Button

You can also add a donation button for paypal like this:

name: My Theme Name
version: 1.0.0
description: Write what you want
author: Your name here
homepage: http://an-info-website-for-the-theme.com
licence: MIT
paypal: https://paypal.me/yourname
amount: 10

This will add a donation button to the theme-collection of Typemill. If you want to add your theme to the theme collection, please open a new issue on GitHub.

Use Settings

Sometimes you want to use variables in your theme, for example to change the text of a button. With YAML you can easily do this: Just create a new block that starts with settings, and write all your settings as simple key-value-pairs. Indent them with two spaces like this:

settings:
  chapter: Chapter
  start: Start

The settings are automatically merged with all other TYPEMILL settings, and are available in your themes with a simple Twig tag like this:

{{ settings.themes.typemill.chapter }} // prints out "Chapter".

Replace typemill with the name of your theme like this:

{{ settings.themes.mytheme.chapter }}

Image Sizes

In the user-settings, you can also add your own image sizes that you need for your theme. For example, the standard size of content-images is 820px. You can overwrite this size with your desired sizes:

settings:
  chapter: Chapter
  start: Start
  images:
    live:
      width: 820

The standard name for content images is "live". You can add a width or a width and a height. You can even add more renditions like this if you want:

settings:
  chapter: Chapter
  start: Start
  images:
    live:
      width: 820
   thumbs:
     width: 50
     height: 50

Keep in mind that more renditions (image sizes) will make the image processing slow, so do not add more than really needed. The rendition name "thumbs" will be added to the image name. Right now the usage is pretty limited, because there is no logic to provide all images for a page yet.

Make Settings Editable

Finally, you can make your theme variables editable for the user in the author panel. To do this, just add another block that starts with forms and fields. After that, you can define a wide range of input fields with YAML. It starts with the name of the field, followed by the field definition.

forms:
  fields:

    chapter:
      type: text
      label: chapter
      placeholder: Add Name for Chapter
      required: true

    start:
      type: text
      label: Start-Button
      placeholder: Add Label for Start-Button
      required: true

TYPEMILL will use these definitions and generate input fields for the author panel on the fly, so that the user can edit the values and customize the theme. If you have defined settings with the same name as the field name (e.g. chapter), then the input field in the author panel will automatically be prefilled with your settings from the YAML-file.

If you have a lot of fields, you can even group some fields together in a fieldset like this:

forms:
  fields:

    chapter:
      type: text
      label: chapter
      placeholder: Add Name for Chapter
      required: true

    MyFirstfieldset:
      type: fieldset
      legend: Last Modified
      fields:

        modified:
          type: checkbox
          label: Activate Last Modified
          description: Show last modified date at the end of each page?

        modifiedText:
          type: text
          label: Last Modified Text
          placeholder: Last Updated

The fields modified and modifiedText will then be grouped in a fieldset with the legend Last Modified.

If you read the YAML definition for input fields carefully, then you will notice that the definitions are pretty similar to HTML: You simply define types and attributes like input-type, labels, and placeholders. Nearly all valid field-types and field attributes are supported.

Learn more about fields and field-types in the chapter about forms.