The goal of Rtistic
is to provide an easy 'hackathon-in-a-box' activity groups of R users. Users can collaborate to create a collection of custom themes for ggplot2
, RMarkddown HTML documents, and xaringan
.
The focus of Rtistic is to provide the basic outline for an R package that can be forked and used for the 'infrastructure' of a styling and theming package developed in a group setting. A lot of the boilerplate RMarkdown and ggplot2
code is already written, so participants can focus on the fun and creative process of picking colors, fonts, spacing, etc.
While Rtistic
is intended to be fun and light-hearted. It also has real benefits for team building and training, including:
ggplot2
and RMarkdown customization optionsroxygen2
-style documentationOf course, depending on how much time you want to spend on this activity and where you want to focus (e.g. learning ggplot2
options versus learning basic CSS for RMarkdown), any number of the parts can be scaled back. For example:
ggplot2
or RMarkdown themes instead of bothR
file instead of working with a package structure (e.g. )Tactically, this may work the best if individuals break off into small groups to work on separate themes. Ideas of prompts could be each team creates their own theme for:
R/palette-infrastructure.R
contains all of the fuctions that users will ultimately call to apply the different palettes. This should be left as-is except for renaming all the functions from *_rtistic
to whatever is desirable. Specifically, it defines the following scales:
scale_(color/colour/fill)_discrete_rtistic(palette = "test", extend = FALSE)
scale_(color/colour/fill)_opinionated_rtistic(palette = "test")
scale_(color/colour/fill)_continuous_rtistic(palette = "test")
scale_(color/colour/fill)_diverging_rtistic(palette = "test", midpoint = 5)
Additionally, to help keep track of all of the community-contributed themes, it provides the get_rtistic_palettes()
function which prints out a characted vector of the names of available palettes (based on scanning the package namespace for objects ending in "_pal
")
The following files are available in the scratchpad/
directory to help with the design process by quickly iterating on style choices:
rmd-theme-demo.Rmd
: An RMarkdown document with an in-line CSS chunk. Ultimately, CSS will be moved to a separate file for your final theme package, but having it embedded in the document allows for fast and transparent iteration to see the effects of different optionsgg-theme-demo.Rmd
: An RMarkdown document with dummy data and ggplot2
with a lot of theme options. The current ggplot is pretty ugly, but this is an attempt to provide a near one-stop-shop overview into ggplot2
theme options that participants can manipulateBoilerplate package code exists in the R/
and inst/
directories:
gg-palette-test.R
: Defines colors of choice and uses them to create discrete (fixed number, interpolated, and opinionated) and continuous (monotonic and diverging) color palettesgg-theme-test.R
: Defines theme function for custom ggplot2
srmd-html-test.R
: Defines render function for custom RMarkdown themes. This depends upon:inst/rmarkdown/resources/html-styles-test.css
: Custom CSS to style RMarkdowninst/rmarkdown/resources/favicon.png
: Custom favicon for documentinst/rmarkdown/resources/logo-test.png
: Custom logo for document footerrmd-slides-test.R
: Defines render function for custom xaringan
themes. This depends upon:inst/rmarkdown/resouces/slide-styles-test.css
: Custom CSS to style slidesBoilerplate code also exists in the vignettes/
directory:
gg-palette-test.Rmd
: contains an array of basic plots to demonstrate the new palette and scales createdgg-theme-test.Rmd
: demonstrates the effect of a custom theme on a plot, optionally paired with any of the custom palettesThese are the files that participants should ultimately save under new names, edit, and PR back to the package. Other files should not be edited.
Admin Instructions:
Initial Set Up - Template Approach
git clone {put HTTPS URL here}
)Rtistic
) to your desired package nameCtrl+Shift+F
available
package to make sure your name does not conflict with an existing packagepkgdown
site with all of the themes. Vignettes created by individual teams will beome articles to display all of the different new palettes and themes as a "gallery". (For help also customizing this, you'll find a template style sheet and config file in the pkgdown/
directory. Contents should be organized reasonably (e.g. like functions and vignettes grouped together) if teams follow appropriate naming conventions.)Initial Set Up - Forking Approach
git clone {put HTTPS URL here}
)Rtistic
) to your desired package nameCtrl+Shift+F
available
package to make sure your name does not conflict with an existing packagegit remote set-url origin {put HTTPS URL here}
)Ongoing Process
pkgdown
site with all of the themes. Vignettes created by individual teams will beome articles to display all of the different new themes as a "gallery". (For help also customizing this, you'll find a template style sheet in pkgdown/extra.css
)Participant / Team Instructions:
git clone {put HTTPS URL here}
)git checkout -b my-new-theme
will create a branch called my-new-theme
)scratchpad/
directory to determine CSS and ggplot2
options that you likeR/
and inst/
folders and migrate your options accordinglygit commit -m "{describe what you changed}"
)git push origin my-new-theme
- or whatever your branch is called)R/gg-palette-test.R
file in the same folder. Rename it as gg-palette-{theme}.R
where {theme}
represents something descriptive about your theme.test_pal
, test_pal_cont
, and test_pal_div
and rename the test
prefix to something appropriate (probably the {theme}
stub)vignettes/gg-palette-test
in the same folder. Rename it as gg-palette-{theme}.Rmd
scratchpad/gg-theme-demo.Rmd
file and play around with the supplied theme to understand the optionsggplot2
has very nice defaults, so don't feel obligated to make major -- or any -- changes if you don't want to.R/gg-theme-test.R
file in the same folder. Rename it as gg-theme-{theme}.R
theme_{theme}
vignettes/gg-theme-test
in the same folder. Rename it as gg-theme-{theme}.Rmd
+ theme_test()
scratchpad/rmd-theme-demo.Rmd
file and play around with the supplied CSS to understand the optionsggplot2
, RMarkdown has very nice defaults, so don't feel obligated to make major -- or any -- changes if you don't want to.inst/rmarkdown/resources/html-styles-test.css
file in the same folder. Rename it as html-styles-{theme}.css
. Move your CSS code from the scratchpad into this fileR/rmd-html-test.R
file in the same folder. Rename it as rmd-html-{theme}.R
html_{theme}
css
and footer
to the files you have definedrmarkdown::html_document()
, learn about the other parameters you can pass in, and decide if there are any other changes that you want to makeFavicons are the small icon that show up in the browser tab for a website or other HTML document.
png
, gif
, or ico
work the best.favicon.png
in inst/rmarkdown/resources
. You will have to delete the image that is currently there (the Rtistic
logo).rmd-html-{theme}.R
## TODO FAVICON
in_header = favicon_file
inside of includes = rmarkdown::includes()
## TODO: FOOTER
. This dynamically generates a footer and saves it to a temp file.logo-{theme}.png
in inst/rmarkdown/resources
and change the line footer_logo <- pkg_resource('rmarkdown/resources/logo-test.png')
to reference your new image fileafter_body = footer_file
inside of include = rmarkdown::includes()
xaringan
CSS inst/rmarkdown/resources/slide-styles-test.css
file in the same folder. Rename it as slide-styles-{theme}.css
. Move your CSS code from the scratchpad into this fileR/rmd-slide-test.R
file in the same folder. Rename it as rmd-slide-{theme}.R
slides_{theme}
css
to the files you have definedxaringan::moon_reader()
, learn about the other parameters you can pass in, and decide if there are any other changes that you want to makeUnderstanding core R, ggplot2
, and CSS concepts before the hackathon will make it easier to suceed.
ggplot2
and works its way up to a final section including plot customization. This will be useful for those wanting to create a new plot theme. The course does not have to be taken end-to-end, so those familiar with ggplot2
can skip directly to the "Customization" section.Looking at existing themes can spark creativity. More tactically, one can also borrow from these themes in their own designs.
ggplot2
themes. It also bears mention to participants that there are countless more themes in other projects and packages.There is particularly good support for building xaringan
themes
xaringan
wiki page describes different elements of the CSS and the relationship between different CSS filesxaringanthemer
R package provides a user-friendly R API for generating the CSS code you need. If this is more appealing than working in raw CSS, the package's write_xaringan_theme()
function will convert your R code to CSS code that can be saved in this package. Boilerplate RMarkdown code is largely inspired by Michael Harper's repo as referenced in the book RMarkdown: The Definitive Guide.
Boilerplate code for ggplot2
themes and palettes is inspired by Simon Jackson's blog on corporate color palettes, Florian Teschner's code-through on creating a unicorn theme, and Garrick Aden-Buie's ggpomological
package
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.