Document editing with R Markdown + GitHub Actions

This repository holds a template for establishing a CI workflow towards collaborative document editing in R Markdown. The goal is that edits to a single .Rmd file will trigger automatic builds of .pdf, .docx, .html, and .md versions of the same document via rmarkdown.

Slides for a talk which describes this workflow are found here.

How this was set up

Let's first create the skeleton of an .Rmd document that we wish to render.

skeleton <- glue::glue('
---
title: "My document"
output: 
  github_document: default
  word_document: default
  html_document: default
  pdf_document: default
---

Introduction
---

Some highly informative text.

')

dir.create(here::here("my-document"))
cat(skeleton, file = here::here("my-document", "my-document.Rmd"))

The quickest way to get a GitHub Actions template for rendering a document is to grab this example action from r-lib which renders generic readme file. The below line initializes the file and renames it for editing.

# create yaml file
usethis::use_github_action("render-readme.yaml")

# rename to render a generic doc
fs::file_move(
  here::here(".github/workflows/render-readme.yaml"),
  here::here(".github/workflows/render-doc.yaml")
)

We then edit the .yaml in session:

usethis::edit_file('.github/workflows/render-doc.yaml')

You can view the resulting file within the repo, but for ease of reading:

on:
  push:
    paths:
      - docs/my-document.Rmd

name: Render my document

jobs:
  render:
    name: Render my document
    runs-on: macOS-latest
    steps:
      - uses: actions/checkout@v2
      - uses: r-lib/actions/setup-r@v1
      - uses: r-lib/actions/setup-pandoc@v1
      - uses: r-lib/actions/setup-tinytex@v1
      - name: Install rmarkdown
        run: Rscript -e 'install.packages("rmarkdown")'
      - name: Render my document to all types
        run: Rscript -e 'rmarkdown::render("docs/my-document.Rmd", output_format = "all")'
      - name: Commit results
        run: |
          git add docs/my-document*
          git commit -m 'Re-build my-document' || echo "No changes to commit"
          git push origin || echo "No changes to commit"