Theme Configurations with YAML

Every theme for Typemill must have a theme configuration file. This is quickly done with a small YAML-file, which must have the same name as your theme folder. The YAML-file contains some basic informations and some optional configurations:

• Basic information: With a readable theme name, a description, a version number, and more.
• Settings: Some default variables, that you want to use for your theme.
• Forms: The definition of forms. Users can customize the theme with these forms in the author panel.
• CSP: A domain-whitelist, if you want to include content from other domains (like libraries).

• Theme Configurations with YAML
  • Add Basic Informations
  • Add a Donation Button
  • Default Settings
  • Forms
  • Content Security Policy (CSP)

Add Basic Informations

The basic information 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
license: MIT

The version number is critical for update checks and notifications, following a recommended schema like 1.2.3 (major.minor.bugfix).

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
license: MIT
paypal: https://paypal.me/yourname
amount: 10

The button will appear in the theme configuration of the author panel. If your theme is uploaded to the official theme-website of Typemill, then a donation button will appear on the overview page and on the detail page. If you want to add your theme to the theme collection, please open a new issue on GitHub.

Default 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 settings of Typemill.

All settings 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 }}

Forms

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.

You can group fields together with a fieldset. This is highly recommended to structure your settings visually:

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 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.

Content Security Policy (CSP)

Typemill uses a content security policy (csp) that blocks all content from external domains. If you want to include content from other domains (e.g. libraries hosted on other domains), then you have to whitelist these domains. Add a simple list of domains at the end of your configuration file.

csp:
  - *.google.com
  - https://cdn.paddle.com