Understanding _output.yaml in generating websites

[cboettig]

Pandoc has the very convenient feature of being able to specify an external yaml file to provide metadata that would be re-used across multiple files; as shown in the docs:

pandoc chap1.md chap2.md chap3.md metadata.yaml -s -o book.html

At first I'd imagined that this is how _output.yaml was working too, but at closer inspection it appears that's not the case. This is rather frustrating as it was very convenient to be able to define arbitrary template metadata in a metadata.yaml that I could then use in custom templates (e.g. rather analogous to _config.yaml in Jekyll). Unfortunately, if I just create an _output.yaml like this:

html_document:
  self_contained: false
  css: 
    - http://www.carlboettiger.info/assets/css/bootstrap.min.css
    - //netdna.bootstrapcdn.com/font-awesome/4.0.3/css/font-awesome.css
rss: http://www.carlboettiger.info/blog.xml
rss-title: "Carl Boettiger's Lab Notebook"
site.url: http://carlboettiger.info
analytics: UA-XXXXXX-1 
author: 
  name: Carl Boettiger
  twitter: cboettig
  github: cboettig

it seems some variables, like css, are recognized, but arbitrary template variables like author.twitter are not (whether or not they are nested under html_document). If instead I run pandoc directly and use the above yaml file as an external metadata block like in the metadata.yaml case illustrated above, everything works. Would it be possible for rmarkdown to support something like this?

[jjallaire]

Yes, _output.yaml covers only the output section of document metadata. I agree it would be nice to have a mechanism for other shared metadata -- perhaps for now you can do this via custom pandoc_args passing your shared metadata file?

[cboettig]

hmm, interesting idea. Seems like pandoc_args requires key-value pairs though, where-as metadata.yaml is just being provided as another input file?

[jjallaire]

Oh, good point! Not sure what the right workaround is then -- perhaps
wrapping the call to render with something that appends the shared metadata
file?

On Tue, Oct 28, 2014 at 5:44 PM, Carl Boettiger notifications@github.com
wrote:

hmm, interesting idea. Seems like pandoc_args requires key-value pairs
though, where-as metadata.yaml is just being provided as another input
file?

—
Reply to this email directly or view it on GitHub
#297 (comment).

[cboettig]

The way _output.yaml currently works seems to have a bit too much magic for me (e.g. I look at the pandoc command that's being run, as echoed by rmarkdown, and it's not clear where _output.yaml is getting used. seems like if I were to run the pandoc command manually I'd be getting something else entirely -- i.e. the mechanism isn't transparent to a pandoc user? or maybe I'm just confused).

yeah, wrapping render (or maybe adding an option to render?) to somehow append a shared metadata file sounds promising, not quite sure I can envision the implementation though. Would be preferable not to need two yaml files to set global metadata.

If backwards compatibility weren't an issue, I think I'd prefer that _output.yaml was written as one would write the metadata.yaml, as a full yaml block that includes an output: html_document element etc.

[jennybc]

@cboettig Sadly, I don't have anything constructive to add. I will say that my pain point with _output.yaml has been that I really would like to have some subdirectory structure but that seems essentially impossible with the current implementation of _output.yaml (and how shared elements work):

http://rmarkdown.rstudio.com/html_document_format.html#creating-a-website

But that's not really what you're asking about here.

[cboettig]

@jennybc Thanks all the same. My current workaround is to call knit and pandoc separately in my Makefile. This lets me specify a common metadata.yaml and template without the use of _output.yaml, so might sidestep the subdirectory problem?

On the downside, my approach means wiring information like template choice into the Makefile rather than in yaml. That's really an issue of pandoc not supporting template as a yaml option; even though rmarkdown does. Some further discussion of this on the pandoc-listserve

[yihui]

Closing this old issue since I believe @cboettig's original issue is no longer a problem with bookdown (shared YAML goes to index.Rmd), and @jennybc's subdirectory issue is gone with blogdown. Sounds like each issue took me one year :)

[github-actions]

This old thread has been automatically locked. If you think you have found something related to this, please open a new issue by following the issue guide (https://yihui.org/issue/), and link to this old issue if necessary.