Themes

Teddy Version: Latest

Creating a new theme and walkthrough of the theme directory structure.

Definition

A theme contains the layout and styling that can be applied to a static site. A single theme may be applied to zero, one or more sites. A theme is a collection of HTML-based templates, utilising Mustache templating syntax and placeholders, and static CSS, JavaScript, image and/or font assets.

Creating a new Theme

The easiest way to create a new theme, and to ensure that all the theme prerequisites are met, is to simply make a copy of the default Bear theme directory found in $TEDDY_BASE/themes (ensure the copy is created in the same parent directory), and to then iteratively develop the copy based on your specific theme requirements. If you do not wish to use the default Bear theme as a template, then simply create a new directory in $TEDDY_BASE/themes. The name of the new directory, and hence the name of the new theme, must only contain alphanumeric, hyphen and underscore characters. Lowercase theme names are recommended, for example bear. For the purposes of this guide, we will hereafter refer to your theme directory, for example $TEDDY_BASE/themes/bear, as $THEME_BASE.

Theme Directory Structure

As a minimum, the following files and child directories must exist in $THEME_BASE.

$THEME_BASE/
├── templates/...
├── theme.json

Theme Configuration

The theme.json theme configuration file must exist in the root of $THEME_BASE. For further information regarding the theme configuration schema, and mandatory configuration namespaces, please read the theme configuration guide.

Templates

The $THEME_BASE/templates directory contains theme-specific HTML-based templates. As described in the pages guide, when a static site that applies the theme is built, each language-specific markdown-based page is converted into HTML and injected into a specified theme HTML template. The templates themselves typically utilise a combination of HTML, Mustache templating syntax, and placeholders to define the base layout and structure of pages that apply the template. For example, the default Bear theme contains a template named page.html, found in $TEDDY_BASE/themes/bear/templates/page.html, that defines the base layout and structure of general pages that apply the Bear theme, as follows.

<!DOCTYPE html>
<html lang="${page.metadata.language}">

    <head>

        <!-- Metadata -->
        {{> partials/head/head-metadata.html }}

        <!-- Favicon -->
        {{> partials/head/head-favicon.html }}

        <!-- Fonts -->
        {{> partials/head/head-fonts.html }}

        <!-- CSS -->
        {{> partials/head/head-css.html }}

    </head>
    <body>

        <!-- Menu -->
        {{> partials/body/body-menu.html }}

        <!-- Page Content -->
        <section class="pt-5 pb-5">
            <div class="container">
                <div class="row">
                    <div class="col-lg-12">
                        ${page.content}
                    </div>
                </div>
            </div>
        </section>

        <!-- Footer -->
        {{> partials/body/body-footer.html }}

        <!-- Javascript -->
        {{> partials/body/body-js.html }}

    </body>

</html>

This template uses a combination of Mustache partials to include section-specific templates, for example {{> partials/body/body-menu.html }} to include the template responsible for rendering the main menu, and placeholders, for example ${page.content} to inject the markdown page content into the desired location. Please read the templates guide for further details regarding templates including how to access and retrieve localised metadata and page-specific metadata within templates.

Static Assets

Themes will usually contain a combination of theme-specific static CSS, JavaScript, font and/or image assets that define the base styling and behaviour of sites that apply the theme. These theme-specific assets will be copied to $SITE_BASE/public/{env}/assets when static sites that apply the theme are built. Theme-specific static assets should be placed in $THEME_BASE/assets and conform to the following directory structure.

$THEME_BASE/
├── assets/
│   └── css/
│   └── fonts/
│   └── images/
│   └── js/
│   └── videos/

Should you wish to minify any custom theme-specific CSS and/or JavaScript assets during the build, then you should list the relative paths to those asset files in the theme.assets.custom.css (relative to $THEME_BASE/assets/css) and theme.assets.custom.js (relative to $THEME_BASE/assets/js) theme configuration arrays respectively. Please read the theme configuration guide for further details.