Theme Development Overview

Hyvor Blogs themes are fully customizable. If you have some experience with HTML, CSS, and Javascript, you can easily build your own theme from scratch. This page is an overview to help you get started. All official themes are in the hyvor-blogs-themes repository. Feel free to review the source code of the other themes.

Here's some of commonly used terms in this documentation:

Themes Rendering in Hyvor Blogs
Rendering in Hyvor Blogs

Basics

Routes

To start theme development, it is essential to understand how Routes work in Hyvor Blogs. Routes are blog-level configurations, which means they are configured by the blogger. Hyvor Blogs comes with default routes that are usually enough for a simple blog.

Before continuing, we recommend you to read our Routes guide to fully understand how routes work.

Single CSS File

There is only a single CSS file in the blog, styles.css.

Flashload

Flashload is added to all blogs by default. Therefore, it is important to keep Flashload in mind while designing themes. Please take a minute and read the Flashload documentation to get the idea of how it works.

Why Flashload? Browser reloads are slow. They load the same CSS/JS resources multiple times making page rendering slower. Flashload starts loading other pages even before the user clicks the link. It makes navigation smoother. It simply turns the blog into a Single Page Application (SPA)!

We previously learned that there's only one styles.css for a blog that contains all CSS of the blog. This styles.css should be loaded inside the <head> of the page. When the user navigates to another page, Flashload sends an AJAX request to that path and pre-fetches the HTML page. Then, it updates only the <body> part. (Remember, we already have all CSS loaded in the first request, so we don't want to load it again).

The simple rule is to add shared resources of the blog to <head>.

Caching

Another important behavior of HB is that we use caching EXTENSIVELY. We use a technique called first-request-caching.

When using a cache, clearing cache is the most important thing. We have to make sure outdated content is not delivered when something changes. Here are the events that we clear cache for each scope.

And,

⚠️
Caching makes the blog super fast. However, it puts some limitations to theme development. You can't render dynamic data like "current date" using Twig. Due to cache, users may see an old date. If absolutely required, you have to use Javascript to render dynamic content inside user's browser. However, displaying the "publish date" of a post works fine because we clear cache whenever the post is updated. Also, displaying the current year will work, because we will make sure to clear the cache on the 1st of January.

Embedding

Blogs are embeddable. Keep that in mind when developing a theme to make sure the theme works fine when embedded. Embedding uses Web Components with Shadow DOM. So, there styles are usually safe. But, you should be careful when writing scripts. More details are in the styles and scripts sections of this documentation.

Starting Development

Let's set up your local development environment.

For the next steps, you need Node.js (and npm). As a front-end developer, we hope you already have it installed :)

npm install -g hyvor-blogs-cli
mkdir my-theme
cd my-theme
hyvor-blogs-cli init

This command will create the following folder structure inside your theme folder.

/
    /assets
    /lang
        en.yaml
    /styles
        index.scss
    /templates
        @base.twig
        author.twig
        index.twig
        post.twig
        tag.twig
    .env
    config.def.yaml
    config.yaml

You can also manually create this folder structure, if you wish.

SUBDOMAIN=dev-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
hyvor-blogs-cli

How it works: The hyvor-blogs-cli command runs two processes under the hood: (1) a http server that works similar to a reverse proxy using our delivery API, and (2) a process that watches your local file changes and syncs it with our production environment. So, whenever you add, edit, or delete a file within your theme folder, it will be synced with the theme files in your DEV blog.

Security Notice 1: Because all files in your theme directory are synced with our production system, never add any confidential files there.

Security Notice 2: Do not share your DEV subdomain publicly. It will allow other users to change theme files in your DEV blog. If you are using GIT for versioning, make sure to add .env to .gitignore.

Folder Structure

As you see, there are four folders in a HB theme folder. Nested folders are not supported.

/
    /templates
    /styles
    /assets
    /lang
    config.yaml

The root folder contains config files. See configuration.