DOCSEARCHbyAlgolia
Submit Docs

Publii Developer Documentation

website·Indexed 38 days ago

https://getpublii.com/dev/

Technical documentation for developing Publii themes, featuring guides on Handlebars helpers (such as {{#getPages}}, {{#getAuthor}}, and {{#isNot}}), global variables, theme configuration, and the rendering process for static websites.

Tokens
42.5K
Snippets
229
Records
293
Agent score
73%

What's inside Publii

  1. Overview of Publii Post Editor API

    The Publii post editor is powered by TinyMCE. It supports modifications through theme-specific CSS, custom configuration overrides, and the definition of custom HTML elements via the theme configuration.

  2. Understand the Publii theme rendering process

    The Publii renderer operates in several modes depending on the context: Post preview, Tag page preview, Author page preview, Homepage preview, and Full page mode (used for website synchronization).

    The full-page rendering sequence follows these steps:

    1. Theme validation
    2. Site config loading
    3. Translation loading
    4. Website data retrieval from database
    5. Theme config loading
    6. Theme files loading
    7. Registration of Publii Handlebars helpers
    8. Registration of custom theme helpers from helpers.js (if present)
    9. Content structure loading and caching
    10. Common data loading for all views
    11. Registration of standard and custom partials
    12. Rendering of Homepage and pagination
    13. Rendering of Post pages
    14. Rendering of Tag pages and pagination
    15. Rendering of Author pages and pagination
    16. Rendering of Error page (if used)
    17. Rendering of Search page (if used)
    18. CSS generation
    19. Copying config files, assets, and media to output directory
    20. Rendering of RSS and JSON feeds
    21. Sitemap creation

  3. Understand how Publii renders Handlebars templates

    Publii uses Handlebars to compile .hbs files. The final HTML output is generated by combining a .hbs template file with a context object containing data related to the current view.
    <!-- If context is { "message": "Hello World!" } -->
<div>{{message}}</div>
<!-- Output: <div>Hello World!</div> -->

  4. Manage Tag configuration options in Publii

    Tag config options allow for customization of tag-related content. These options are managed in two places:

    1. Theme Settings: Under the 'Tag Options' section, where global default values are set for all tags.
    2. Edit Tag Screen: In the right-sidebar under 'Other Options', where defaults can be overridden for individual tags.

    Configuration options are defined in the tagConfig section of the config.json file.

  5. Understand Publii Handlebars template file roles

    Publii uses specific Handlebars (.hbs) template files to render different sections of a website. Each file has access to a specific set of Handlebars tags, categorized into 'template-related tags' (available only in that specific template) and 'common tags' (available across multiple templates).

    The primary template files and their purposes are:

    • index.hbs: Renders the homepage and its pagination.
    • post.hbs: Renders single post pages.
    • page.hbs: Renders single pages.
    • tag.hbs: Renders tag post listings and pagination.
    • tags.hbs: Renders the listing of all tags.
    • author.hbs: Renders author post listings and pagination.
    • feed-xml.hbs and feed-json.hbs: Generates the XML and JSON feed files.
    • search.hbs (optional): Renders the search page.
    • 404.hbs (optional): Renders the 404 error page.

  6. Manage author configuration defaults and overrides

    Author configuration options allow for tailoring author-related content. Global default values are set in the Theme Settings screen under the Author Options section. These defaults can be overridden for individual authors in the right-sidebar of the Edit Author screen under the Other Options section. All author config options are defined within the authorConfig section of the config.json file.

  7. Understand Publii theme file types

    Publii themes are composed of several key file types that determine structure, style, and logic:

    • .hbs (Handlebars): Used for the HTML structure and templating.
    • .css: Used for styling, positioning, and visual character.
    • .js (JavaScript): Used for complex interactive features.
    • .json: Used for storing configuration settings and theme translations.

  8. Understand Handlebars helpers in Publii

    Publii uses Handlebars helpers, which are custom functions used within theme templates. These are categorized into two types:

    1. Conditional Helpers: Used for logic and flow control. These are identified by a hash character (#) at the start of the helper name (e.g., {{#checkIf}}).
    2. Inline Helpers: Used to output specific values or formatted data directly (e.g., {{date}}).

  9. Define supported features in a Publii theme

    Since Publii v.0.37.0, theme developers can specify which features their theme supports by adding a supportedFeatures section to the theme.config.json file. These flags inform the user and the system about the theme's capabilities. This is distinct from renderer settings; while renderer settings control whether a feature is active, supportedFeatures declares if the theme is capable of supporting it at all.
    "supportedFeatures": {
  "authorImages": true,
  "authorPages": true,
  "blockEditor": true,
  "customComments": true,
  "customSearch": true,
  "errorPage": true,
  "embedConsents": true,
  "searchPage": true,
  "tagImages": true,
  "tagPages": true,
  "tagsList": true,
  "customThemeOptionsCss": true,
  "pages": true,
  "postsPage": true
}

  10. Understand Publii post content modification pipeline

    Publii applies a series of automatic modifications to content generated in the post editor (TinyMCE or Markdown) before it is displayed in the theme. These operations are performed in a specific sequence by the Publii renderer to ensure optimal page speed and correct HTML structure.

  11. Implement a page selector in Publii theme settings

    Use the pages-dropdown field type in your theme settings to allow users to select one or more specific pages from their site (e.g., designating a 'Privacy Policy' or 'About Us' page).

    • Return Value: The field returns the ID(s) of the selected page(s).
    • Single Selection: When multiple is false, a single page ID is returned.
    • Multiple Selection: When multiple is true, a comma-separated string of page IDs is returned.
    • Integration: Because this field returns IDs, it should be used in conjunction with the getPage or getPages helpers to retrieve the actual page data.
    {
    "name": "homepageAboutUsPage",
    "label": "About Us Page",
    "group": "Homepage",
    "value": "",
    "type": "pages-dropdown",
    "multiple": false
}

  12. Understand Publii image types

    Publii categorizes images into six types, each serving a specific purpose and having different configuration methods:

    • Featured Image: Added via the 'Edit Post' sidebar. Used for article headers and post previews (Home, Tag, Author pages).
    • Tag Image: Used to visually represent tag categories.
    • Author Image: Used for author page backgrounds or headers to represent a persona/brand (distinct from small avatars).
    • Content Image: Images inserted directly into the post body via the editor or drag-and-drop.
    • Option Images: Theme-specific images uploaded via 'Theme Options' (e.g., hero sections or sliders).
    • Gallery Images: Images uploaded to a Gallery inserted into a post via the Post Editor.

    Content and Gallery images are handled automatically by Publii, while Featured and Option images are more flexible and configurable via the theme's config.json.