Every Project Needs a Home

Recently I created home page for my project Scaldi. I wanted to make it for a long time, but from the other hand I don’t want to spend much time finding some hosting and maintaining its infrastructure, making page design, etc. Github page is nice, but still I would like to have somethng more simple and unique as a project’s front page. So my main goals were:

• Use very nice feature of Github - gh-pages to host my pages
• Use markdown to create my pages without spending much time making page design
• Design that comes out-of-box should be clean and pretty
• Integrate pages generation and publishing in SBT build process

Pamflet

And I finally found solution that addresses all these requirements. Pamflet is very nice Scala library that allows you to define your site using markdown. It’s very easy to use: you just create your pages that are named according to their position in the resulting table of contents with .md or .markdown extension. You can also define some properties in the template.properties which you can use in your pages (they would be processed using StringTemplate). If you want, you can add some custom CSS in order to make it even more prettier. So resulting file structure should look like this:

• 00.md
• 01.md
• 02.md
• custom.css
• template.properties

Pamflet has even more features, but it was enough for me to start creating Scaldi’s home page. So I ended up with following files in my project’s docs folder. It was pretty straightforward to create, but now I need to generate actual HTML from my markdown markup.

SBT Integration

In order to generate my pages and publish them to the gh-pages I need following SBT plugins:

• pamflet-plugin - it generates actual site
• xsbt-ghpages-plugin - adds generated pages to the gh-pages branch and pushes changes to github

At first you need to create  gh-pages branch in your git repository. You can make it like this:

After executing this, you need to add SBT plugins in your project/project/Build.scala:

After adding these plugins, you should be able to generate HTML pages. All you need to do is to execute write-pamflet task and your pages would be generated in target/docs folder.

Now comes your main build.sbt file:

I hope comments will help you in understanding what each of these settings does. So now in order to publish my pages I need to execute ghpages-push-site task. I can also run ghpages-synch-local in order to add pages to the gh-pagesbranch locally.

As bonus, Scalasodocs would be also published by xsbt-ghpages-plugin.

Conclusion

It was pretty easy to integrate Pamflet with SBT and gh-pages. I ended up with nice looking site and published Scaladoc. And it’s really easy to manage and publish them.

I hope this post will also help you to setup your project’s home page in a matter of minutes, because, you know, every project needs a home :)