GitHub Download

Theme config.json file

The config.json file stores the main theme configuration and information for the theme renderer.

Publii merges the theme config file with the default one visible below:

    "postTemplates": {},
    "tagTemplates": {},
    "authorTemplates": {},
    "menus": {},
    "renderer": {
        "relatedPostsNumber": 5,
        "includeFeaturedInPosts": true,
        "tagsIncludeFeaturedInPosts": true,
        "authorsIncludeFeaturedInPosts": true,
        "featuredPostsNumber": 0,
        "tagsFeaturedPostsNumber": 0,
        "authorsFeaturedPostsNumber": 0,
"includeHandlebarsInHelpers": false, "create404page": false, "nameFor404page": "404.html" }, "config": [ { "name": "logo", "label": "Website logo", "value": "", "type": "media", "upload": true }, { "name": "postsPerPage", "label": "Posts per page", "value": 5, "type": "number" }, { "name": "tagsPostsPerPage", "label": "Tags posts per page", "value": 5, "type": "number" }, { "name": "authorsPostsPerPage", "label": "Authors posts per page", "value": 5, "type": "number" }, { "name": "excerptLength", "label": "Excerpt length", "value": 30, "type": "number" } ], "customConfig": [], "postConfig": [], "files": { "ignoreAssets": [ "scss", ".DS_Store" ], "assetsPath": "assets", "partialsPath": "partials" }, "customElements": [] }

Fields name, version, author are REQUIRED. Other fields will be merged with the default config.json file if some fields do not exist in the theme's config.json file.

The renderer section contains values which shouldn't be changed in the theme options, but can be changed by the theme developer or more advanced users.

The config section contains some useful options for the user and the theme renderer:

  • postsPerPage - number of posts displayed on the frontpage and tags page (if tags_posts_per_page hasn't been set),
  • tagsPostsPerPage - number of posts displayed on tag pages,
  • excerptLength - length of excerpts in words.

For posts per page, an option value of 0 is defined as an unlimited (though it is not technically unlimited; the maximum is 999 posts per page) number of displayed posts.

The files section allows you to modify the renderer's behavior:

  • ignoreAssets - An array defining the resources (files and directories) to be ignored when copying assets to the output directory,
  • assetsPath - specifies which directory contains the theme's assets
  • partialsPath - specifies which directory contains the partials files of the theme
  • responsiveImages - specifies the size attribute and dimensions (and crop mode) for created thumbnails - if featuredImages configuration isn't defined, then all images will use the settings from contentImages. You can use "auto" instead of a number if you want to resize images according to one dimension.

WARNING! Image dimension names cannot contain non-latin chars, spaces, commas, etc. and should always be lowercase.

The optional menus section is an object with the available menu areas.

WARNING! The keys in this object should only use letters as it will be used in the menu partial as a parameter of the menus object.

Under the optional postTemplates/tagTemplates/authorTemplates sections, you can create a collection of key - value pairs, which will be used to generate the post/tag/author templates list.

The optional customElements section is responsible for adding custom styles for specific elements which can be previewed in our post editor. By adding a "customElements": field you can enable use of all the custom elements offered by the TinyMCE editor.

More examples

An example for the menus section:

"menus": {
    "mainMenu": "Main menu", 
    "footerMenu": "Footer menu"

An example for the customElements section:

"customElements": [
            "label": "Custom style",
            "cssClasses": "custom-style",
            "tag": "span"
            "label": "Custom style 2",
            "cssClasses": "custom-style-2",
            "selector": "p"

tag causes the element to be wrapped by the element specified in the tag, with the CSS classes defined in cssClasses added. If the selector is set, then the specified cssClasses will be added to elements which match the provided selector (it should be used especially when styling paragraphs).

An example for the templates section:

"postTemplates": {
       "alternative": "Post alternative template (from post-alternative.hbs file)"
"tagTemplates": {
       "alternative": "Tag alternative template (from tag-alternative.hbs file)"
"authorTemplates": {
       "alternative": "Author alternative template (from author-alternative.hbs file)"


Get the latest Publii news, updates and more delivered directly to your email inbox

You can change your mind at any time by clicking the unsubscribe link in the footer of any email you receive from us, or by contacting us at By clicking below, you agree that we may process your information in accordance with our Privacy Policy.