Grotius

library(grotius)

Introduction

Grotius combines a document collation tool and a hugo preprocessor.

In a first collation phase, grotius collects source Rmarkdown and markdown documents from local and remote locations.

In a second hugo preprocessor phase, grotius uses rmarkdown to evaluate optional R code and prepare the documents for inclusion in a hugo static site.

grotius.yaml

Grotius uses a grotius.yaml manifest file to specify what it needs to do.

documents:
  - input: rmd/doc1.Rmd
    output: content/doc1.md
  - input: rmd/doc2.Rmd
    output: content/doc2/_index.md

Under documents any number of documents to process can be specified.

input specifies the source file. This can be any file that is accepted by rmarkdown::render.

output specifies the output file. This is where the rendered document should be stored. This path will usually start with content and end with _index.md

Both the input and output path should be in a directory under the parent directory of the manifest.

Input documents can additionally be specified via a getter url to a remote reference:

documents:
  - input: https://domain.com/repo.git//sub/path/doc1.Rmd
    output: content/doc1.md

Getter URL

The remote git URL syntax is based on go-getter.

The format is as follows:

[<protocol>://]<domain>/<path>//<subpath>[?ref=<reference>]

Credentials

Only http-based credential authentication is currently supported. By default grotius will attempt to extract a credential pair from the environment variables GROTIUS_GIT_USERNAME and GROTIUS_GIT_PASSWORD.

If more flexibility is required you can use credentials to define any number of credentials by specifying the following for each:

Example:

credentials:
  - id: github
    matchInput: https://github.com*
    git2r:
      git2r::cred_env:
        username: GROTIUS_GH_USERNAME
        password: GROTIUS_GH_PASSWORD

Inline Documents

Input documents can also be provided inline instead of read from a (remote) file path.

This is mostly useful for short “glue” content such as a parent page for a collection of child pages. By specifying such pages as a doc instead of relying on dowstream tooling (e.g. Hugo) to generate them automatically from filepaths you can customize them further (e.g. setting a title).

The following input content will be treated inline:

Example:

documents:
  - input: |
      inline text to use as render input 
    output: content/myinlinedoc.md
    options:
      title: "Title for my inline doc"

Input Generators

Input documents can be also be provided as a path-providing generator R function.

The generator function can be specified in two ways. You can either specify the function name as a value:

documents:
  - input: somePackage::someFunction
    output: content/mygenerateddoc.md

Or, alternatively, you can specify an object with the function name as a key and the value an object representing the arguments to call the function with:

documents:
  - input:
      somePackage::someFunction:
        foo: bar
    output: content/mygenerateddoc.md

In both cases, the function name needs to be a fully-scoped R function name that resolves to an existing function. The function will be called dynamically during the collation phase and is expected to return a local file path as a scalar character vector. You can use this to fetch/find files in ways not supported out-of-the box by grotius or even dynamically generate the file within the generator function.

Document Batch

An entry under documents can also be a document batch (or tree) instead of a single file.

Batches can be specified by letting input: and output: both refer to directories:

documents:
  - input: rmd/mybatchdir/
    output: content/somedir/
    match: "*.Rmd"
    matchExclude: ["excluded/*"]
    ext: ".md"
    toIndex: true

To filter out non-document files input, you can use match which takes a glob expression. Only matching filenames will be included.

Grotius will walk the document tree recursively and mirror it under the output. match refers to filenames without directories included. If you need to filter out full directories you can use multiple document batches. Alternatively you can use matchExclude to provide an array of glob expressions to filter the match results with. matchExclude runs against the paths relative to the input. In the example above, all documents under rmd/mybatchdir/excluded/ are ignored.

Since the output paths cannot be specified directly Grotius offers batch transforms to construct the output filenames from the input filenames:

Under the example config above, an input file rmd/mybatchdir/subdir/doc.Rmd will be mapped to content/somedir/subdir/doc/_index.md

Tags

You can add tags to a document:

documents:
  - input: my/input/document.Rmd
    output: my/output/document.md
    tags:
      - mytag

Tags can be used to filter the documents to consider for collation. This can be useful to speed up the authoring process if you are working with a large site or if you don’t have the necessary access to read from some remote inputs.

Document Rendering

render format

The default render format is grotius::hugoPage. You can change this via render.format:

render:
  format: grotius::hugoPage

The render format can be also defined on the document level:

documents:
  - input: rmd/doc1.Rmd
    output: content/doc1.md
    format: grotius::hugoPage

Keep in mind that the output format needs to be compatible with the output file extension, and with the site styling.

render options

The front-matter can be overriden via an options block on the document:

documents:
  - input: rmd/doc1.Rmd
    output: content/doc1.md
    options:
      title: my custom title

Options are passed into the output_options argument of rmarkdown, which are passed on to the output format.

For document batches, you can use rule-based options to conditionally apply options to some documents in the batch:

documents:
  - input: rmd/mybatchdir/
    output: content/somedir/
    match: "*.Rmd"
    ext: ".md"
    batch:
      - pattern: somefile.md
        options:
          title: "Some Title"

In the above example, only the file named somefile.md would be rendered with title: "Some Title".

render params

You can set rmarkdown render params in a similar fashion:

documents:
  - input: rmd/doc1.Rmd
    output: content/doc1.md
    params:
      x: 42

These will passed into the params argument of rmarkdown. Render params can be useful for when you want to create multiple pages from the same template.

the grotius::hugoPage format

documents:
  - input: rmd/doc1.Rmd
    output: content/doc1.md
    options:
      title: my custom title
      linkTitle: my link title
      header: |
        my header text
      footer: |
        my footer text

The hugoPage format has a dots argument which allows you provide arbitrary options to the hugo front matter. This is useful because hugo themes often implement custom options. As an example, the Docsy theme has a linkTitle option which allows to set a different title for use in navigation.

The format also has a post-processor which can introduce arbitrary header and footer text. Note that, because this content is inserted in the post-processing step, it will not be parsed by knitr or pandoc. Consequently, you can write content for the Hugo parser directly (and e.g. use shortcodes) without the possibility of it getting misinterpreted. If you do need your content to processed by pandoc, use options.includes (see help(includes_to_pandoc_args, package = "rmarkdown")).

“asis” rendering

There is a special output format "asis" that allows to render document with the (first) output format defined in its yaml metadata. With this setting the original document can be included as an external link, which may be useful for presentations, reports in non-HTML format or documents where particular style is important.

The following example shows how to render a document as hugoPage, and in addition include a link to the original HTML slides at the top of the page:

documents:
  - input: rmd/slides.Rmd 
    output: content/slides/original.html
    format: asis
  - input: rmd/slides.Rmd
    output: content/slides/_index.md
    options:
      title: "Presentation"
      header: |
        {{% pageinfo %}}
        This content was originally created as [slides](original.html)
        {{% /pageinfo %}}

disable rendering

You can disable rendering by setting render: false on a document:

documents:
  - input: rmd/doc1.Rmd
    output: content/doc1.md
    render: false

The documents will still be considered for other actions (such as the linkData). One useful application is to combine render: false with document batches to generate link data for a document tree in the site repository that doesn’t need rendering.

render context

The render context (render.context) allows you to define how the rendering will be executed. Available options are:

Example:

render:
    context: callr
documents:
    # ...