Skip to content

Themes

Jump to bottom
Jaydson Gomes edited this page Apr 1, 2015 · 20 revisions

Introduced in Harmonic@0.1.12

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

How to create an Harmonic themes

npm module

First, you'll need to start a npm module:

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

Configure your npm module as you want. At the end, you'll have a package.json.

Building your theme

Harmonic themes must to 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 dir 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 to 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, is common to test this theme locally.
To test your theme locally, you can just install it like any other npm module, but pointing to your path:

npm install ../harmonic-theme-awesome

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

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

Publish

As Harmonic themes are just npm modules, you can just publish it like any other module.
Assuming you already have npm configure(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