How to Add Pages Support in Publii Themes

Publii's 0.46 release introduced a powerful new feature: Pages. This allows you to create static content separate from your blog posts, perfect for content like "About Us," "Contact," or "Services" pages. While the official Publii themes released alongside version 0.46 seamlessly integrate Pages, custom or modified themes might require adjustments.

This guide will walk you through adding Pages support to your Publii theme, ensuring you can take full advantage of this new feature without sacrificing your theme's unique design and functionality.

When Do You Need This Guide?

You'll find this guide particularly useful if:

You're using a custom or modified version of an official theme.
You see a message indicating a lack of Pages support when accessing the Pages tab in Publii.
You want to understand the technical aspects of implementing Pages support in Publii themes.

Following these steps, you can extend your theme's capabilities and create rich, static pages within your Publii-powered website.

Step 1: Activating Pages Support

The first step is to inform Publii that your theme supports Pages by adding a flag to the theme's configuration file.

Locate your theme's config.json file. It should be in the following directory:
```
/Documents/Publii/sites/YOUR_SITE/input/themes/YOUR_THEME/config.json
```
Open the config.json file in a text editor.
Find the supportedFeatures section. If it doesn't exist, create it.
Add the Pages support flag as follows:
```
"supportedFeatures": {
    "pages": true
},
```
If other supported features exist, simply add the "pages" line to the existing object.

Step 2: Creating the page.hbs file

Next, we need to create a template file for Pages. The easiest way is to duplicate the existing post.hbs file and modify it.

In your theme directory, find the post.hbs file.
Create a copy of this file and name it page.hbs.
Open page.hbs in a text editor.

Now, let's go through the main changes you must make on the page.hbs file:

Change the main wrapper:
- Replace {{#post}} with {{#page}} at the beginning of the file.
- Replace {{/post}} with {{/page}} at the end of the file.
Remove unsupported sections because they are specific to blog posts and don't apply to static pages:
- Delete the section for displaying tags.
- Remove the post navigation section (previous and next post links).
- Remove the related posts section.

Update configuration references:

Replace all occurrences of @config.post with @config.page e.g. @config.post.displayFeaturedImage to @config.page.displayFeaturedImage

Additionally, you need to update the config.json file to support page-specific configurations. This involves copying the postConfig section and modifying it to pageConfig. Remove any elements that don't apply to Pages, such as displayRelatedPosts and displayPostNavigation. Here's an example:

"pageConfig": [
    {
        "name": "displayDate",
        "label": "Display date",
        "value": 0,
        "type": "select",
        "pageTemplates": "!empty",
        "options": [
            {
                "label": "Enabled",
                "value": 1
            },
            {
                "label": "Disabled",
                "value": 0
            }
        ]
    },
    {
        "name": "displayShareButtons",
        "label": "Display share buttons",
        "value": 0,
        "type": "select",
        "pageTemplates": "!empty",
        "options": [
            {
                "label": "Enabled",
                "value": 1
            },
            {
                "label": "Disabled",
                "value": 0
            }
        ]
    },
    {
        "name": "displayChildPages",
        "label": "Display child pages",
        "value": 0,
        "type": "select",
        "options": [
            {
                "label": "Enabled",
                "value": 1
            },
            {
                "label": "Disabled",
                "value": 0
            }
        ]
    }
]

Add support for child pages (if needed):

{{#if @config.page.displayChildPages}}
   {{#if subpages}}
      <div class="subpages">
         <h2 class="subpages__title">{{ translate 'page.childPages' }}</h2>
         <ul class="subpages__list">
            {{#each subpages}}
               {{#getPage @this}}
                  <li>
                     <a href="{{url}}">{{title}}</a>
                     {{#if subpages}}
                     <ul>
                        {{> subpages-list}}
                     </ul>
                     {{/if}}
                  </li>
               {{/getPage}}
            {{/each}}
         </ul>
      </div>
   {{/if}}
{{/if}}

Update other references:
- Change @customHTML.beforePost to @customHTML.beforePage. Additionally, you need to add the corresponding option in the config.json file. In the renderer section, add a new entry for beforePage:
```
"renderer": {
    "customHTML": {
        "beforePost": "Before every post",
        "beforePage": "Before every page"
    }
}
```
- Make similar changes for other post-specific references

Here's an example of how a section of your page.hbs might look after these changes:

{{> head}}
{{> top}}
<main>
   {{#page}}
      {{#if @customHTML.beforePage}}
         <div>{{{@customHTML.beforePage}}}</div>
      {{/if}} 
      <article>
         <header>
            <h1>{{title}}</h1>
         </header>
         {{#if @config.page.displayFeaturedImage}}
            {{#featuredImage}}
               <!-- Featured image code here -->
            {{/featuredImage}}
         {{/if}}
         <div>{{{text}}}</div>
         <!-- More code here like author name, share buttons, comments ...-->
      </article>
   {{/page}}
   {{> sidebar}}
</main>
{{> footer}}

Step 3: Restarting Publii

After making these changes:

Save all modified files.
Close Publii if it's currently running.
Restart Publii to ensure all new settings are loaded.

Conclusion

You should now be able to create and edit Pages in your Publii project. Remember that the exact implementation may vary depending on your theme's specifics. Always test your changes thoroughly to ensure pages display correctly and don't introduce any errors.

Following this guide, you've successfully extended your Publii theme to support the new Pages feature. This enhancement allows for more versatile content creation and site structure, opening up new possibilities for your static website.