Learn R Programming

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!

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.

Copy Link

Version

Version

0.41

License

GPL-3

Maintainer

David Springate

Last Published

February 15th, 2017

Functions in samatha (0.41)

check.layouts

check layout files
doc.index.list

Produces an unordered list of links to rendered documentation files
escape.html

Escapes html tags
doc.to.html

Converts an Rd file to an html fragment
check.pagesPosts

check state of pages and posts
build.tagpage

Generates page content for a tag, to be rendered with a layout
catch_char_zero

catch if there is a zero length string
content

concatenates html tags
extract.tags

Extracts the tag names from a markdown post file tags should be the first line of the file and preceeded with the percent sign tags are delimited by spaces, commas or semicolons
collate.tags

Builds a list of post tags and links to their associated posts Extracts tags from the top of all .md files in a list of posts
img.link

image tag representaion
import.tagfile

Reads in a JSON tagfile
html_head

Wraps input in head tags
file.states

Gets modification times for a vector of files
html_body

Wraps input in body tags
extract.title

reads a markdown post file and extracts the title Title is taken as the first line in which the line underneath is a double underline i.e. a h1 tag in markdown n.b. the title must be in this format, not e.g. # This is a title
get.postpath

returns the path to the post in the site
include.css

CSS include representation
get.site.state

Gets modification dates for all source and dest files in a site
include.js

js include representation
orphan.items

find orphaned pages and posts
m

Generic representaion of an HTML tag in R
link.to

link tag representaion
mail.to

mail to tag representaion
knit.post

knits an Rmd post to md
refresh.site

Refresh all posts and pages if : - layouts newer than any html files : rebuild everything - DONE - no corresponding html for source OR source newer than html file : build - html files with no source : delete html - otherwise do nothing and return false todo - Error testing
include.textfile

reads a text file into a character vector A wrapper around readChar
include.markdown

renders the contents of a markdown file as an html character vector A wrapper around markdown::markdownToHTML
render.all.docs

Builds a list of Samatha.Page objects for all Rd documents in a given directory
render.doc

renders an .Rd file as a Samatha.Page object
render.page

Render a page using the Samatha html dsl
write.tags.to.file

writes a json file of post tags and links to their associated posts Seperate from collate.tags to maintain functional style
stop.server

stops the R server
render.opts

Render html attributes
skeleton

Sets up directory structure for a new Samatha site 2 main subdirectories: template (for source code for the site) and basename(site) for the html etc. of the site itself
write.docs

Renders a directory of Rd files to html and writes within a Samatha site directory
write.html

Writes the html content of a Samatha.Page object to the file specified in the file element.
setup_example_site

Sets up an example site
samatha

Samatha: Runs an infinite loop, updating the site as necessary This is the main command to update your site. You can leave this running while you make edits to source files
rssdoc

Representation of an RSS page in R
render.post

Render a post from an R markdown file
run.server

runs the R server for viewing site
render.rss

Builds an rss file with all posts in the site Typically, the parameters would be population from a config.R file
unordered.list

unordered list representation
tag.links

create a set of links for tags without counts
update.site

Checks if source files were modified after the corresponding dest files if : - layouts newer than any html files : rebuild everything - DONE - no corresponding html for source OR source newer than html file : build - html files with no source : delete html - otherwise do nothing and return false todo - Error testing
html.postlist

builds a list of links to all blog posts. List is in decreasing order of post date
webdoc

Representation of a webpage in R
itemise.post

wraps the details of a post up as an rss item tags and title are extracted from the post for the item description
html.taglist

returns a character string of an html formatted list of tags, with numbers of posts associated with each and links to the tag pages This is a useful addition to an index page
make.samatha.page

Contstuct a page from the individual elements
javascript.tag

Functions for creating HTML elements. These are all wrappers around the m() function javascript tag representation
render.tagfiles

Renders new html pages listing the associated posts for each tag loops over elements of a taglist, building pages for each tag
ordered.list

ordered list representation
rss.category

Creates rss feeds for the given categories. items are parsed from the main rss feed using xpath New rss category feeds are placed in site/site/tags/CATEGORY_NAME.xml