Harp Project Organization

I have written a series of blog posts on Harp, the static site generator. I want to begin to wrap up this series of blog posts by talking about project organization in Harp. After this blog I will write up one more with some concluding thoughts in the tool. If Harp is brand new to you it might be helpful to first read Getting Started with Harp. Otherwise read on and I'll explain some of the basics that every project will need to cover and then at the end I will go over some concepts that I developed for myself that greatly helped me keep my project organized.

Site Content

In my previous blog post, Hosting Harp on Github Pages, we decided to create two directories in the root of the project:

• my-project/
• src/
• docs/

As explained in that blog post this allows us to compile the src code into a docs folder that can be used on any web server. That made it easy for us to host on Github pages but it would be a fairly similar process to host the docs directory on other web servers.

Metadata

Inside of the src folder we will add out top level web pages and begin the hierarchy of out website with sub directories. Each of these directories should contain a _data.json file that can be used to create contextual features as described in the Breadcrumbs Component in Harp blog post.

Assets

In addition to this we will want to create an "/my-project/src/assets" directory that can contain shared JavaScript, CSS, and images. In this directory I have a main.js file and a main.css file.

Images

For images I recommend creating folders that specify the dimensions of the images. In my example Harp website at jacksfamilypizza.alexlockhart.me I have the following two directories containing my images assets:

• /src/assets/images/4_3
• /src/assets/images/16_9

This way when I reference an image elsewhere I know it's dimensions and can specify which version of an image I want to use by just changing that part in the path.

Structure

So far this has been fairly straightforward. However now I want to explain a few concepts that I developed for myself when using Harp. This first begins with creating a directory called "/my-project/src/_structure". The underscore tells harp not to compile the contents of this directory. Within this directory I add EJS partials that meet the following criteria:

• Partials in this structure directory should use direct references to contextual data sources such as "public._data.title" and "current.path".
• Partials in the structure directory _should not_ rely only upon passed in data from the partials parameters.

These partials can be used to provide contextual features on your site and can be powerful for providing things like headers, footers, navigation, and breadcrumbs. However they have the downfall of relying upon the structure of your metadata provided in the _data.json files and their behavior is dependent upon where they are placed.

Components

The idea of components is another concept I developed specific to how I used Harp. Let's again start by creating a directory called "/my-project/src/_components". Again the underscore means that these files will not be rendered. Within this directory we can add EJS partials that meet the criteria listed below. This is essentially the reverse criteria from the previous section.

• Partials in the components directory should rely only upon passed in data from the partials parameters.
• Partials in this components directory _should not_ make direct references to any contextual data source such as "public._data.title" and "current.path".

These partials, that I am calling components, are designed so that they can be used anywhere on the site and will always have the same behavior. They do not rely on the metadata provided in _data.json. However they have the reverse downfall of the structure partials from the previous section in that they require any data to be provided through the partials parameters.

Elements

Out last Harp project organization concept comes in the form of elements. This is the name I gave to the files within the directory at "/my-project/src/elements". Notice that there is no underscore here and so these files will be rendered. I added to this directory JavaScript files, each of which implemented a web component. I included these javascript files onto the page from an ES6 import from the main.js file.

This allowed me to use these web components in the html throughout my EJS templates and partials. I can pass in metadata into these web components through data attributes. This provides an entry point for implementing more complex UI behaviors and features.

And that is it! Thank you for reading and stay tuned for my final post on Harp where I will do a review of this static site generator and provide some final thoughts.