Skip to content

Themes

Jump to bottom
Fabrício Matté edited this page Apr 13, 2015 · 20 revisions

Introduced in [email protected]

Harmonic themes are based on the awesome Nunjucks.
Basically, if you want to create a Harmonic theme, you can use all the Nunjucks features.
Harmonic themes are npm packages, meaning you can easily share and use community themes.

How to create a Harmonic theme

npm package

First, you'll need to create a npm package:

mkdir harmonic-theme-awesome
cd harmonic-theme-awesome
npm init

Configure your npm package the way you want.
In the end, you'll have a package.json.

Building your theme

Harmonic themes must implement 3 template files:

  • index.html (theme main page)
  • post.html (post page for a blog)
  • page.html (for an page)

Also, you can create your own structure, like a partials directory with your html partials.

index example:

<!doctype html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <title>{{ config.title }}</title>
</head>
<body>

    {% include "partials/navigation.html" %}
    <header>
        <section>
            <h1>
                {{ config.title }}
            </h1>
        </section>
    </header>

{% include "partials/footer.html" %}

</body>
</html>

Static files must be placed in a folder called resources.
Everything inside this folder will be copied.
You can also provide a config.json file that will be merged with the current Harmonic config.
Example:

{
    "mycustomdata": "wow",
    "foo": "bar",
    "baz": ["a", "b"]
}

Here's a sample theme structure (actually, the harmonic-theme-default uses this structure):

.
├── config.json
├── index.html
├── package.json
├── page.html
├── partials
│   ├── footer.html
│   ├── header.html
│   └── navigation.html
├── post.html
├── README.md
├── resources
│   ├── css
│   │   └── main.css
│   ├── images
│   │   ├── flag-en.jpg
│   │   └── flag-pt-br.jpg
│   └── js
│       └── main.js
└── tag_archives.html

Using your theme

If you're developing a new theme, you will want to test it locally.
To test your theme locally, you can just install it like any other npm package, but pointing to its path:

npm install ../harmonic-theme-awesome

Note: To install the theme you must init a new Harmonic project before, or use an existing one:

harmonic init "my_blog"
cd my_blog
npm install ../harmonic-theme-awesome

Publish

As Harmonic themes are just npm packages, you can publish it like any other package.
Assuming you already have npm configured (registered user, etc.):

npm publish ./

Now, everybody can use your theme!

harmonic init "my_blog"
cd my_blog
npm install harmonic-theme-awesome
Clone this wiki locally