Theme structure

Every Publii theme should contain some required files, but a few files can also be optionally included in the theme.

The following files are required:

config.json - main theme configuration file,
index.hbs - homepage template,
post.hbs - single post template,
thumbnail.png - that will be displayed in the application settings (required dimensions: 400x300px),
assets/css/main.css - main CSS file which is used to generate the styles.css file (which is merged with the optionally-generated override.css file).

These files are recommended:

tag.hbs - single tag page template,
tags.hbs - single tags page template,
author.hbs - single author page template,
partials/ - location for files which will be loaded with use of the {{> fileName}} code,
partials/footer.hbs - footer used in all pages,
partials/header.hbs - header used in all pages

And these files are optional:

visual-override.js - file which contains a function used to generate the override.css file,
feed-xml.hbs - The structure of the feed XML file - generated as feed.xml (the feed-xml.hbs file will be replaced with the application's default if one does not exist in the theme),
feed-json.hbs - The structure of the feed JSON file - generated as feed.json (the feed-json.hbs file will be replaced with the application's default if one does not exist in the theme),
search.hbs - A dedicated search results page template. This template is necessary for themes that intend to offer enhanced search capabilities or integrate with specific search plugins, such as a Google Search plugin.
partials/pagination.hbs - pagination for all pages (the pagination partial will be replaced with the application's default if one it does not exist in the theme),
partials/menu.hbs - menu structure for all pages (the menu partial will be replaced with the application's default if one does not exist in the theme).
post-template.hbs - an alternative post template file that can be selected for individual posts, offering a customized layout or design distinct from the default post.hbs template.
tag-template.hbs - a custom template file for individual tag pages. This template allows for a unique layout or design for pages listing posts associated with a particular tag.
author-template.hbs - an alternative template file dedicated to each author's page. This template allows you to apply a unique layout or design for pages displaying posts written by a specific author.
helpers.js - a JavaScript file containing definitions for custom Handlebars helpers tailored to the theme's specific needs.
dynamic-assets-mapping.js - a JavaScript file generates a list of asset paths that must be loaded dynamically based on the theme's configuration. The primary use case for this file is to manage assets such as fonts, images, or other media that may vary depending on the user's customization choices or theme options.
theme-variables.js - a JavaScript file dynamically generates CSS custom properties (variables) based on the theme's configuration. The output from theme-variables.js is crucial for defining foundational style parameters such as colors, font families, sizes, and more. The key aspect of this file is that its output is typically injected at the beginning of the style.css file. This positioning ensures that the defined CSS variables are available and can be utilized throughout the rest of the CSS file, providing a consistent and easily customizable styling foundation for the theme.
visual-override.js - The purpose of this JavaScript file is to generate custom CSS styles that allow for specific overrides of the theme's default styles based on user-configured parameters. Unlike theme-variables.js, the output ofvisual-override.js is added to the end of the style.css file. This placement is strategic, as it ensures that the custom overrides precede the previously defined styles, allowing for effective customization and adjustments to the theme's appearance.