theme.json | Automad

Every theme needs a theme.json file. All subdirectories of the packages directory that contain a theme.json file side by side with at least one template are considered valid themes. Besides some basic meta data, the theme.json file controls how the fields of your theme are presented in the dashboard.

Fields

name String: The name of the theme as it is displayed in the dashboard. In case the name is missing, the path of the theme directory is used.
description String: A short description of the theme.
author String: The name of the author.
license String: The license of the theme.
version String: The version of the theme following the semantic versioning convention. Note that this field is not required for themes that are installed as Composer packages, since the version is taken from Composer in that case.
masks Object: Masks can be used to hide fields from either the page or the shared settings in order to keep the dashboard nice and tidy. Each mask is an array of field names. See the example below for more details.
fieldOrder Array: The order of fields in the dashboard. Fields that are not listed here are appended at the end.
labels Object: Alternative labels for fields. By default, labels are generated from the field names.
options Object: The available choices for fields that start with select. See options below for more details.
tooltips Object: Tooltips that are displayed as help text next to fields in the dashboard.

Options

Fields that start with select are rendered as dropdowns in the dashboard. The available choices are defined in the options object, where each key is the value that is stored and each value is the label that is displayed.

"options": {
  "selectColorTheme": {
    "light": "Light theme",
    "dark": "Dark theme"
  }
}

In case multiple fields share the same set of choices, a set can be defined once and then be referenced by name. A string value is resolved to the options object with the matching key. Wrapping such shared sets in double underscores helps to distinguish them from actual field names.

"options": {
  "__dateFormat__": {
    "M Y": "Month and Year",
    "Y": "Year only",
    "Y-m-d": "Y-m-d"
  },
  "selectPageDateFormat": "__dateFormat__",
  "selectPagelistDateFormat": "__dateFormat__"
}

Translations

Labels, tooltips and options can be translated into the languages that are supported by the dashboard. Translations are stored in an i18n directory inside the theme. Each file is named after a dashboard language, like i18n/de.json for German, and can contain a labels, a tooltips and an options object. Entries that are missing in a translation file fall back to the ones defined in theme.json.

{
  "labels": {
    "authorName": "Name des Autors"
  },
  "tooltips": {
    "+main": "Der Hauptinhalt der Seite"
  },
  "options": {
    "__dateFormat__": {
      "M Y": "Monat und Jahr",
      "Y": "Nur Jahr"
    }
  }
}

Example

The following example is a shortened version of the theme.json file of the Standard Lite theme that ships with Automad:

{
  "name": "Standard Lite",
  "description": "The new Standard for Automad version 2",
  "author": "Marc Anton Dahmen",
  "license": "MIT",
  "masks": {
    "page": [
      "+pageNotFoundContent",
      "checkboxDisableAnimations"
    ],
    "shared": [
      "+hero",
      "+main"
    ]
  },
  "fieldOrder": [
    "+hero",
    "+main",
    "+footer",
    "authorName",
    "selectColorTheme"
  ],
  "labels": {
    "+pageNotFoundContent": "Content for the 404 page",
    "authorName": "Author name"
  },
  "options": {
    "selectColorTheme": {
      "switcher": "Show theme switcher, visitor can select theme",
      "light": "Light theme",
      "dark": "Dark theme"
    }
  },
  "tooltips": {
    "+hero": "The hero section",
    "+main": "The main content block area"
  }
}