Designing a theme for Leafpub is very straightforward. If you're not familiar with Handlebars yet, I'd suggest familiarizing yourself a bit before diving into this tutorial.

The easiest way to create a new theme is to start with an existing one. The default theme is called Range and gets distributed along with Leafpub, so let's use that.

theme.json

First, duplicate content/themes/range and rename the folder. Then open up theme.json and change the name, description, version number, etc.

theme-json.png

Important: Make sure you use valid JSON! Unlike JavaScript, properties always need to be double quoted. You can check for errors using this tool.

Now you can switch to your new theme in Settings.

Templates

Leafpub themes consist of Handlebar templates that control your website's markup. These files exist at the top level of your theme folder and end in .hbs. (You may need to configure your text editor to recognize this extension.)

When someone visits your website, Leafpub looks at the requested URI, determines which template to use, fetches the appropriate data, and renders it for the user.

The default theme ships with all the required templates. Poke around and get familiar with each one. Try changing some things and refresh your browser to see the changes. Range's templates are commented pretty heavily, so they should be easy to understand.

If you have questions about templates, feel free to ask over on the community forum.

Caching

Handlebar templates are cached for optimal performance, so if you're not seeing your changes after modifying a template, it's probably because caching is enabled. You can disable this in Settings > Advanced.

settings-cache.png

Feel free to leave caching off as you design your theme — just make sure to turn it back on before moving to production. You might not notice any difference, but your web server will, especially if it gets a lot of traffic!

Partials

Most themes have a folder called partials that contain additional .hbs files. These are called partials, and can be included into a template using the following syntax:

{{> header}}

This expression will insert the contents of partials/header.hbs directly into the calling template.

Partials are great for headers, footers, sidebars, and any other content that needs to be included by more than one template.

Linking to Assets

You can include scripts, styles, images, and other assets into your theme from any template. The only thing you need to remember is to use the {{theme_url}} helper:

{{theme_url 'css/styles.css'}}
{{theme_url 'js/scripts.js'}}

Using a relative path might appear to work at first, but there are a number of conditions where they can fail. To make your theme as portable as possible, always use a helper to reference local assets.

Alignment Classes

Leafpub tries to avoid adding inline styles to your markup. Instead, it favors classes. This is more semantic and it gives you better flexibility to style things.

For example, most editors produce something like this when aligning a paragraph:

<p style="text-align: center;">...</p>

But in Leafpub, aligning a paragraph will yield this instead:

<p class="align-center">...</p>

So make sure to include appropriate styles for the following classes in your theme.

  • align-left
  • align-center
  • align-right
  • align-justify

For a more detailed example, refer to the default theme's stylesheet.

Conclusion

That's pretty much all you need to know to get your feet wet. (I told you it was easy!)

Want to do more with your themes? Check out the Helper Reference for some more advanced features.

Now that you've created your first Leafpub theme, why not show the community?  Better yet, why not share it for others to use by posting the source on GitHub?