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
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:
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.
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.
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 :)