Harpjs one week later

I’ve been working with Harp.js for a bit more than a week now, and I would not like to share how I’ve been using it so far.

The not so good

Up to now I must say I like Harp a lot! It’s nice and simple, easy to use, but thanks to Jade and Less it is also very easy to extend for more “complex” needs. Like I showcased in my previous post I first started using Bootstrap to built my layout based on one of their Bootstrap starter template. For handling Bootstrap and Font-Awesome dependencies I used Bower and that’s when I found my first issue :

Hickup #1 : Font-Awesome

When using Font-Awesome “like a PRO” (that is using LESS), you need to define the @FontAwesomePath variable.

# ~/public/css/main.less
@import "../../vendor/font-awesome/less/font-awesome.less";
@FontAwesomePath: "../font";
@import "../../vendor/bootstrap/less/bootstrap.less";
...

Unfortunately this does not play well when running harp server and even worth when compiling your project. Why? Simply because the vendor/ directory is Not in the public/ directory - and that is correct that way, we do not want all the assets sources to be publicly available - therefore the font files (_.woff, _.ttf, *.svg) are not available publicly. The only solution I could think of was to refer to the absolute url of the font directory :

# ~/public/css/main.less
@import "../../vendor/font-awesome/less/font-awesome.less";
@FontAwesomePath: "http://netdna.bootstrapcdn.com/font-awesome/3.2.1/font";
@import "../../vendor/bootstrap/less/bootstrap.less";
...

Hickup #2 : Sitemap generation

When working on web projects in general, I always try to put all the chances on my side to get good visibility on search engine. One way to do so easily is by generating a sitemap.xml of your site. For this issue I still haven’t found any solution. I think there should be a global object available throughout the project which holds a complete list of public slugs. I have reported this in github and there seem to be an easy solution to that.

Hickup #3 : Concatenate JS

When using LESS for handling the stylesheets of a harp project, it automatically compiles and concatenate all the CSS and LESS files imported in your main.less file. This is great! But right now there is no way to do just the same for JS/Coffeescript files. This too has been reported and I’m really looking forward to getting it solved. This would be great when using Bower!

These are the only few points I’m still having issues with. Now comes the good!

The good!

Less / Jade

Although this is not directly linked to Harp, I still want to point out how great LESS and Jade work together with Harp! I’m all new to these 2 solutions, but I already feel like they are making me save a lot of time when designing my styles and templates. I stumbled upon a very nice and lean design the other day : http://sebastien.saunier.me/ and I decided that this was exactly what I was looking for. I took me 1 hour or so to convert my old layout to this new one (including moving from the original CSS to its much more flexible LESS version). small. I just found and tried html2jade and it works great! While converting Sébastien’s layout to Jade, I tried as much as possible to move all the personal related data to harp.json making the layout very flexible and easy to use for other projects / persons. Here is what it looks like as of today :

{
    "globals": {
        "title"           : "Me myself and I",
        "author_name"     : "Kevin Saliou",

        "site_name"       : "Kevin Saliou",
        "site_description": "...",
        "site_keywords"   : "php, symfony2, python, django, javascript, jquery, angular, css, html, bootstrap, web development, scrum master",
        "site_url"        : "http://kevin.saliou.name",

        "twitter"         : "kbsali",
        "github"          : "kbsali",
        "linkedin"        : "kevinsaliou",
        "gplus"           : "111159323197167868157",

        "debug"           : false,

        "disqus_enabled"  : false,
        "disqus_shortname": "saliou",

        "ua_id"           : "UA-328215-1"
    }
}

With those global variables I am able to control most of the meta data of the project, but also the linking to my different social networks account (twitter, github, linkedin, google plus), my google analytics ID, as well as disqus.

Blog engine / RSS feed

For this project, one of my goal was to be able to publish posts on a regular basis, just like blog engines do! Using Metadata as described in the documentation, you can easily get this done. I use pretty much the same _data.json structure, but I have added a few more fields :

{
"2013-10-21-harpjs-one-week-later": {
    "title": "Harpjs one week later",
    "excerpt": "I've been working with Harp.js for a bit more than a week now, how I like and dislike so far",
    "date": "Oct 21, 2013",
    "ispublished": true
},
...

The ispublished variable allows, you guessed it, to control whether a post should be listed in the posts’ lists page or not. Likewise, the excerpt is simply used to show a short intro of the post itself.

Syndication of post is a pretty basic feature of any decent blog engine. With Harp.js I was able to do this very easily. The only “trick” was to disable the layout for this file and find a way to convert the post date to RFC-1123 - which is the standard date format for RSS feeds :

# ~/public/feed.xml.jade
doctype xml
rss(version="2.0")
    channel
        title #{ site_name }
        link #{ site_url }
        description #{ site_description }
        language en
        for post, slug in public.posts.data
            if post.ispublished
                item
                    title \#{ post.title }
                    description \#{ post.excerpt }
                    link \#{ site_url }/posts/\#{ slug }.html
                    guid(isPermaLink="true") \#{ site_url }/posts/\#{ slug }.html
                    pubDate
                        = new Date(post.date).toUTCString()

# ~/public/_data.json
{
    "feed": {
        "layout": false
    }
}

Partials

Harp allows to use partials (through Jade), and so far I use 3 of them :

for showing the aside on my index page,
for adding the google analytics tag
for showing the disqus comment plugin after each posts

To do

It would be nice to be able to easily switch between local assets dependencies and their CDN versions.
As mentioned earlier, I would really like to be able to publish a sitemap of my project for better integration with search engines.
All the generated code (CSS and HTML) is always compressed, it would be nice to be able to get the formatted/beautified versions too.
Explore the possibility to override global variables to dynamically change the meta description for instance depending on the page shown.
- Fixed! This was as simple as assigning a new value to the global var at the top of the post source :
```
- site_description = excerpt
- site_keywords = keywords
...
```