Edit this page on Github

Themes are simply sites. Spress uses the power of Twig to render templates. You can reuse parts of your HTML and create templates with a easy language.

Creating a theme

The new:site command lets you create a blank site. --all option enables a complete scaffolding of the site.

$ spress new:site my-site --all


Layouts describes how the content is distributed in a page. Layouts are simple HTML & Twig files located at ./src/layouts and they can inherit from other layouts

In this example, default.html file may hold the general HTML definitions like html and head tags with metas, title and assets:

<html lang="en">
        <meta charset="utf-8">
        <meta name="viewport" content="width=device-width, initial-scale=1.0">
        <meta name="description" content="{{ site.description }}">
        <meta name="author" content="{{ site.author.name }}">
        <title>{{ page.title | default(site.title) }}</title>
        <link href="/assets/style.css" rel="stylesheet" media="screen">
        {% block content %}
            {{ page.content }}
        {% endblock %}

Prior layout contains a content block and this will be filled out with the page content.

Another layout could be added for describing how a post page is: post.html. This one inherited from default.html using the layout attribute:

layout: "default"
{% block content %}

    <h1>{{ page.title }}</h1>

    {{ page.content }}

{% endblock %}

Reusable content

Reusable parts, partials are simples HTML & Twig files located at ./src/includes folder.

To render a partial call include with the identifier surrounded by quotes:

{% include 'nav.html' %}
{% include 'widget/email.html' %}

It's also possible to pass custom variables to a patial using with keyword:

{% include 'nav.html' with {'menu': 'top'} %}

More information about Twig include statement.

Avoids renderizer in some files

In some cases is useful avoid the renderizer phase in some kind of files. A good example of that is a minimized js file with the following content:

a = "{#modernizr{top:9px;position:absolute}}"

The prior fragment of code throws a Twig syntax exception. To avoid that, adds avoid_renderizer attribute to the Front matter block or metadata file of the javascript file:

avoid_renderizer: true

By default, avoid_renderizer is false.

Plugin installation

Plugins extends Spress with amazing capabilities. They are located at ./src/plugins folder. The easy way to install a plugin is using Composer tool. In this example, We will use a plugin called spress/github-metadata-plugin.

Create a file named composer.json at the root of the site and paste the following content:

    "require": {
        "spress/github-metadata-plugin": "2.0.*"

To Install the plugin executes composer install command.

How to install a new theme?

There are several ways to do it.

Download a copy

  • Get a copy of the latest release.
  • Uncompress it.
  • Go to theme folder
  • Run spress site:build --server --watch

With Git

  • Fork theme repository (so you will be able to modify it later on)
  • Clone it: git clone https://github.com/YOUR-USER/THEME-REPOSITORY.git folder-name-for-cloned-theme
  • Go to folder-name-for-cloned-theme folder
  • Run spress site:build --server --watch