Theme config.json file

The config.json file plays a crucial role in customizing the look and feel of your website generated by Publii. It serves as the primary configuration hub for the theme renderer, dictating various aspects of how your content is displayed.

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"
    },
    "supportedFeatures": {
        "authorImages": true,
        "blockEditor": true,
        "errorPage": true,
        "searchPage": true,
        "tagImages": true,
        "tagsList": true,
        "pages": true
    },
    "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": [],
    "pageConfig": [],
    "files": {
        "ignoreAssets": [
            "scss",
            ".DS_Store"
        ],
        "assetsPath": "assets",
        "partialsPath": "partials",
        "useDynamicAssets": false
    },
    "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

The renderer section contains values that shouldn't be changed in the theme options but can be changed by the theme developer or more advanced users. For more in-depth configuration of renderer options, refer to the Publii documentation article on How to configure rendering process of your website.

The supportedFeatures section

The supportedFeatures section in the config.json file is used to indicate which Publii features are supported by the theme. This allows users to easily identify whether a theme offers the desired functionality and makes it easier to choose a theme that meets their needs.

To learn more about the supportedFeatures section and supported features, please refer to the Theme Supported Features article.

The config section

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

• postsPerPage - number of posts displayed on the homepage 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
• useDynamicAssets - specifies if theme uses dynamic assets or not,
• 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 that will be used to generate the post/tag/author templates list.

The optional customElements section adds custom styles for specific elements that can be previewed in our post editor. By adding a customElements field, you can use 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)"
},
"pageTemplates": {
       "alternative": "Page alternative template (from page-alternative.hbs file)"
},
"tagTemplates": {
       "alternative": "Tag alternative template (from tag-alternative.hbs file)"
},
"authorTemplates": {
       "alternative": "Author alternative template (from author-alternative.hbs file)"
},