Access top-level YAML metadata in output_format

[mattwarkentin]

Hi,

Is it possible to access the top-level YAML meta-data in the output_format function? It seems like knitr::metadata isn't yet populated at the time of running the output format function.

Anyone have a good workaround?

[cderv]

Is this for a custom format function ?

When creating a custom format with output_format(), it is best to use the post_knit, or pre_processor or post_processor functions which will each have access to the metadata

otherwise, metadata object is in rmarkdown not knitr (rmarkdown::metadata), but I would recommand using the processing functions to access the metadata in output_format()

[mattwarkentin]

Thanks @cderv for the suggestions. I will see if I can use the pre- and post- knit and processor hooks to do what I need. I was just surprised to see that:

html_noisy <- function(...)  {
  print(rmarkdown::metadata)
  rmarkdown::html_document(...)
}

---
title: My Title
author: Me
output: html_noisy
---

When rendered via rmarkdown::render(...) will print an empty list() before rendering. I would've thought the output format might have access to the metadata but apparently this is not so.

[cderv]

@mattwarkentin

I would've thought the output format might have access to the metadata but apparently this is not so.

rmarkdown::metadata is filled after the evaluation of the format function. So at the time html_noisy() is evaluated rmarkdown::metadata is still empty. The hooks mechanism with processing functions are there to apply what you need to do in the right place of the rendering process (before / after knit and pandoc).

[mattwarkentin]

Thanks for the insights.

[mattwarkentin]

Out of curiosity, are the different components of the R Markdown output formats documented anywhere? I haven't came across any comprehensive documentation as of yet. In particular, explaining when each of the hooks are called, what the input arguments are, and what the return value must be?

str(rmarkdown::html_document(), 1)
#> List of 11
#>  $ knitr                  :List of 5
#>  $ pandoc                 :List of 7
#>  $ keep_md                : logi FALSE
#>  $ clean_supporting       : logi TRUE
#>  $ df_print               : chr "default"
#>  $ pre_knit               :function (...)  
#>  $ post_knit              :function (...)  
#>  $ pre_processor          :function (...)  
#>  $ intermediates_generator:function (original_input, intermediates_dir)  
#>  $ post_processor         :function (metadata, input_file, output_file, clean, verbose)  
#>  $ on_exit                :function ()  
#>  - attr(*, "class")= chr "rmarkdown_output_format"

[cderv]

@mattwarkentin

Out of curiosity, are the different components of the R Markdown output formats documented anywhere?

For now that would be in the help page

Define an R Markdown output format — output_format

Please submit some feedback to improve the current help page if some useful information are missing.

Then looking into other packages to get some examples is the best way to learn.

Otherwise, there will probably be a chapter in next version of the cookbook

Examples on how to create new formats from scratch or based on other format

But it is not yet undergoing work.

[mattwarkentin]

Ah yes, the help page is great. Thanks for sharing.

I look forward to a more detailed chapter on creating custom formats and hopefully some best practices for using the pre/post hooks. I think it would be great if there were some examples of cool uses of the hooks too, based on internal or community packages/formats!