Samatha v0.4.0

Copyright David Springate 2013 (CC BY 3.0)

@datajujitsu

Samatha is an R package for quickly building Github-ready static sites in R. It contains a simple, functional-style DSL for rendering HTML, an engine for compilation of static websites as you build them and a development web-server for viewing your sites of line before you deploy.

This project is still in active development. Feel free to contact me with any issues/bugs/suggestions

The Static site engine uses the Samatha DSL to build layout templates which it then combines with content to generate individual pages. templates are written as a nested R expression, with no need for extenal templating systems. There are two ways to build pages:

1. Pages are written entirely in the Samatha DSL and compiled with a layout file. This is ideal for introductiory pages and index pages.
2. Blog posts are written in .Rmd format, which is then converted to md using knitr and then to html using markdown. Posts are then rendered within the layout for that post.

The Samatha engine samatha() now functions as expected. It compiles your site and then updates in real time according to the following rules:

• if a layout file is altered
  • The whole site is re-built
    • pages compiled to html
    • posts knitted and then compiled to html
    • rss and tag files generated
• if any page/post source files are newer than their corresponding html or if the html doesn't exist:
  • Pages in question are knitted and/or re-compiled
  • rss and tag files re-generated
• Any html files without a corresponding source are deleted

Extra features:

• simple wrapper functions for including snippet files containing md or html/js (e.g. for external comments site code and analytics)
• You can include tags for posts in the first line of a post .Rmd file by starting the line with %. All words on the rest of the line are coerced to tags and included in the RSS file.
• Automatically generates an RSS file at the top level of your site with global paths and per item tags, content and full links to images etc. Tags/categroies for the whole site can be set in the template/config/config.R file. This is the format required by Rbloggers for blog submission.
• The rss.category.feeds variable in the config.R file can be used to add extra rss feeds for specific categories. For example, R Bloggers require that all posts sent to them only concern R. You can therefore set rss.category.feeds = c(R) and Samatha will produce another rss feed just with your R content (matching tags for "R") and put it in site/site/tags/R.xml. You can then send this link to Rbloggers and be feee to publish on other subjects, knowing only R content will go to Rbloggers.
• Helper functions for building lists of tags and lists of posts

Sites are created with the following structure:

• basename
  • template the source for your site
    • layouts layout templates for pages and posts
    • config contains config.R file for rss, tags, post layoutss and figure path
    • pages Content of pages built with the Samatha dsl
    • posts Rmd files of blog posts
    • resources html/js/md snippets
  • basename the compiled site. Copy the contents to a git repo to have a functioning site
    • css Put your css files (e.g. from twitter bootstrap) here
    • img plots from knitted Rmd are automatically placed here
    • pages html for site pages
    • posts
    • tags

Examples

My personal blog was built using Samatha, twitter bootstrap and Github pages. I used the Readable theme. See here for the file structure of a Samatha site.

This gist Gives code to quickly setting up an example site.

Install

You should be able to install the current version of Samatha with devtools:

# check install_github()
require(devtools)
install_github("samatha", "DASpringate")

Simple Startup

library(samatha)
site <- "/dir1/dir2/dirSite"
skeleton(site)
setup_example_site(site)

samatha(site, rss = FALSE, initial = TRUE)
samatha(site, rss = FALSE, initial = TRUE)

run.server(site)  # open browser to localhost:8000 to see the site

Documentation

I'm still working on it!

• Wiki
• API docs These have been auto-generated from the .Rd documentation using Samatha
• Quick-start gist

Glaring ommisions (To be fixed very soon):

• Automatic creation of config files and example default templates. For now, check my site structure for setup details.