Themes Documentation

Using a pre-existing theme in Bestatic is very easy (you have probably already figured that out). Creating a theme for Bestatic takes a little bit of effort, but actually, you just have to follow a few simple steps.

Let's go!

Using a theme

It involves three steps:

Download a theme from the GitHub repo. You will need the themes directory from there. You can also use GitHub directory downloader for downloading just the themes folder from the repo.
In the root directory of your site, create a themes folder. Then create a folder with theme name, such as "Amazing". Put all the content of themes inside that folder. This is demonstrated in the directory structure section.
Update the config file with theme key, for example, theme: Amazing. See an example config file here. You can also supply this as a command line argument, such as -t Amazing or --theme Amazing. See details here.

That's it!

Creating a theme

A themes directory structure would typically look like this:

└── themes
    └── Amazing
        ├── static
        │   ├── Images
        │   │   ├── Bottom logo.png
        │   │   ├── Logo_1.png
        │   │   ├── Young1.png
        │   │   └── favicon.ico
        │   ├── css
        │   │   ├── banerstyle.css
        │   │   └── styles.css
        │   └── js
        │       ├── fuse-search.js
        │       └── vanilla-back-to-top.min.js
        └── templates
            ├── 404.html.jinja2
            ├── home.html.jinja2
            ├── layout.html.jinja2
            ├── list.html.jinja2
            ├── page.html.jinja2
            ├── partials
            │   ├── footer.html.jinja2
            │   ├── head.html.jinja2
            │   ├── header.html.jinja2
            │   ├── katex.html.jinja2
            │   └── nav.html.jinja2
            ├── post.html.jinja2
            └── taglist.html.jinja2

As you can see, to create a new theme for Bestatic, you primarily need to create two subdirectories: a) static and b) templates.

The static folder should contain all of your...well, "static" files, i.e. the files that do not need to directly processed by Bestatic system, but still essential for correct functioning of the generated website. All of your Images, Javascript, CSS, etc. files should be included in this folder. When Bestatic generates your website, it will copy this into _output/static path (or into <your choice of directory name>/static path) in a nested fashion, maintaining directory structure.

Now the templates folder. This should contain all of your page templates. Bestatic, a program written in Python, naturally uses Jinja2 based templates. Extensive Jinja2 documentation is available. You can actually learn the basics of Jinja2, such as variables, if-elif-else conditions, for loop, etc. in 10 min from here.

Once you have done learned those, please feel free to start playing with Jinja2 blocks within this (make sure to save the files with extension .jinja2):

{% block something %}
.
.
.
{% endblock %}

Now, a couple of things to remember here while designing theme for Bestatic:

You are free to organize your partials in any way you prefer (although we recommend putting them in ./themes/theme-name/templates/partials directory). For reference, "partials" are parts of HTML codes that you can typically reuse to build different templates, such as head, header, footer, navbar, etc.

We recommend (but not required) using layout.html.jinja2 (and layout2.html.jinja2, layout3.html.jinja2 etc., for complex themes) to assemble these partials. A very simple layout file may look like this:

<!DOCTYPE html>
<html lang="en">
<head>
{% include 'partials/head.html.jinja2' %}

{% if condition %}
... 
{% endif %}

<meta name="description" content="{% block description %}{{ description }}{% endblock %}"/>
<title>{% block title %}{{ title }}{% endblock %}</title>
</head>

<body>

{% include 'partials/nav.html.jinja2' %}

<div class="container">

{% block content %} {% endblock %}

</div>
<br>

{% include 'partials2/footer.html.jinja2' %}

</body>

</html>

For this file, you can modify the title, description, and content as you wish. We recommend building new files such as post.html.jinja2, page.html.jinja2, etc. by extending layout files like this. You can start those files with {% extends "layout.html.jinja2" %} and then provide your custom title, description, content, etc. and you are good to go!

A few things to remember regarding how Bestatic passes variables to Jinja2 templates:
- The main title of the site and description (that you can mention in config.yaml file or from Bestatic CLI) is provided as title and description respectively.
- The type of the page is provided with typeof variable: It can be home (for separate homepage; also see homepage customization for relevant details), posts (for separate blog post pages), lists (for blog post listing pages), or tags (for tag-based blog post listing pages).
- Regarding blog-posts: Disqus shortname or Giscus repo id (as mentioned in mention in config.yaml file) are provided as disqus and giscus variables, respectively. Tags (for taglist pages) are provided as tags variable.
- All information regarding pages or posts can be accessed by page.content format or post.content (note: .content can be replaced by .metadata,.summary, .tags, .katex, .text, .title, .slug, or .path_info).
- All information provided in post/page front matter will be available as post.metadata or page.metadata which can be further extracted as post.metadata["date"], post.metadata["title"], etc.
- Few more available variables: next_slug (useful for linking next post in blog page), prev_slug (useful for linking previous post in blog page), page_index, and page_range (these two provide information on number of blog listing pages, which can be used to dynamically create blog page index like Blog Page 2 of 21).
- Finally, Bestatic expects six templates to be present in templates directory: post.html.jinja2, page.html.jinja2, home.html.jinja2, 404.html.jinja2, list.html.jinja2, and taglist.html.jinja2. The Last two are necessary if you have a blog section for your website or if your website is a blog. The 404.html.jinja2 can be skipped if custom 404 page is not required. Others can be skipped if user provide template: key in their page/post front matter or prefers different approach of home page (see here and here for more details).

That is all! If you are facing any issue to create a theme, please talk with us over our GitHub discussions page. We would love to help. Thank you for trying out Bestatic!