Skip to content

Latest commit

 

History

History
153 lines (115 loc) · 4.22 KB

themes.md

File metadata and controls

153 lines (115 loc) · 4.22 KB

Harmonic themes

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 most likely want to test it locally before publishing it.
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

Then edit your harmonic.json and set "theme": "harmonic-theme-awesome".

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

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

Faster development

To avoid having to npm install your theme every time you make changes, you may instead npm link your theme to a Harmonic project:

# suppose you have a Harmonic theme named `harmonic-theme-awesome` in this dir:
cd harmonic-theme-awesome
npm link
# and a Harmonic project here:
cd ../my_blog
npm link harmonic-theme-awesome

Now, your theme is symlinked to that Harmonic project, meaning any change you make to the theme will be automatically reflected in the Harmonic project's theme dependency (node_modules/harmonic-theme-awesome). Note that you still need to run harmonic build or harmonic run to generate a new site build using the newly modified theme to see it in action.

The next step in the theme development workflow would be to setup a watch task to run harmonic build and auto-reload the browser (e.g. using BrowserSync), but that is outside of the scope of this wiki page. ;)

Publish

If you'd like, add the "harmonictheme" keyword to your package.json, so that users may easily find your theme.

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

<<< Markdown Header | Index >>>