library(grotius)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 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.mdUnder 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.mdThe remote git URL syntax is based on go-getter.
The format is as follows:
[<protocol>://]<domain>/<path>//<subpath>[?ref=<reference>]git2r. http by default.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:
id: name for the credentialmatchInput: glob wildcard pattern for the remote inputs that use this credentialgit2r: function that provides a credential of the format used in the git2r package. If subentries are specified they will be passed as arguments.Example:
credentials:
- id: github
matchInput: https://github.com*
git2r:
git2r::cred_env:
username: GROTIUS_GH_USERNAME
password: GROTIUS_GH_PASSWORDInput 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"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: trueTo 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:
ext: set the filename extensionindexPage: create an _index.md file in a folder named after the input file. In Hugo terms, this creates a Page Bundle. To create a Leaf Bundles, which can't contain other pages you additionally set indexPageType: "leaf"subStringRewrites: array of rewrites which are applied in the order they are specified in. Each rewrite consists of a pattern and a replacement and replaces the former with the latter anywhere in the path.Under the example config above, an input file rmd/mybatchdir/subdir/doc.Rmd will be mapped to content/somedir/subdir/doc/_index.md
Grotius can also produce a data file with links to use in the oa-modified docsy theme.
To enable this feature, specify a name for the data file:
documents:
linkData:
output: repo_linksThe same name needs to be configured in the hugo site parameters under link_data:
# cat config.toml
[params]
link_data: repo_linksGrotius currently expects 3 functions for the 3 different types of link: editPage, newPage and issues. See https://www.docsy.dev/docs/adding-content/repository-links/ for their purpose.
You can override the default functions:
linkData:
editPage: myPackage::myEditPageFunction # call with default arguments
newPage: myPackage::myNewPageFunction
issues:
myPackage::myIssuesFunction: # or pass custom parameters
customParam: 42Link data functions are expected to take a single mandatory first argument sourceRef that contains metadata about the origin of the source page.
The default render format is grotius::hugoPage. You can change this via render.format:
render:
format: grotius::hugoPageThe render format can be also defined on the document level:
documents:
- input: rmd/doc1.Rmd
output: content/doc1.md
format: grotius::hugoPageKeep in mind that the output format needs to be compatible with the output file extension, and with the site styling.
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 titleOptions are passed into the output_options argument of rmarkdown, which are passed on to the output 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 textThe 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")).
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 %}}You can disable rendering by setting render: false on a document:
documents:
- input: rmd/doc1.Rmd
output: content/doc1.md
render: falseThe 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.
The render context (render.context) allows you to define how the rendering will be executed. Available options are:
parent (default): call rmarkdown::render directly from the R session in which grotius was called with default arguments. Of particular relevance is the envir argument which will be set to the default parent.frame(): i.e. the document will be rendered in the same environment as the calling parent.
callr : render documents in the global environment of a fresh new R session through the callr package. This guarantees that each document will run in an independent clean environment and therefore avoids any session crosstalk between documents.
Example:
render:
context: callr
documents:
# ...