From 75b71f5a3275d0df74f899d9ece5b0bb0db2011d Mon Sep 17 00:00:00 2001 From: Salim B Date: Thu, 26 Mar 2020 22:51:05 +0000 Subject: [PATCH 1/3] properly document the `output_yaml` option [rmarkdown 1.16](https://github.com/rstudio/rmarkdown/releases/tag/v1.16) introduced the `output_yaml` metadata option which allows to explicitly specify the path to the external output options file. This wasn't documented in the book up until now. Besides the documentation wasn't clea enough (IMHO) that you can only outsource _output_ options. --- 03-documents.Rmd | 38 ++++++++++++++++++++++++-------------- 1 file changed, 24 insertions(+), 14 deletions(-) diff --git a/03-documents.Rmd b/03-documents.Rmd index 4b6bf33..f4b4511 100644 --- a/03-documents.Rmd +++ b/03-documents.Rmd @@ -438,30 +438,40 @@ output: Documentation on all available pandoc arguments can be found in the [Pandoc User Guide](http://pandoc.org/MANUAL.html#options). -### Shared options {#shared-options} +### Shared output options {#shared-options} -If you want to specify a set of default options to be shared by multiple documents within a directory, you can include a file named `_output.yml` within the directory. Note that no YAML delimiters (`---`) or the enclosing `output` field are used in this file. For example: +You can outsource part or all of the _output_ options to a separate YAML file. This is very convenient to specify a set of default options for multiple documents and thus avoid redundancies (think of it as an "output option template"). The path to this file can be set by the option `output_yaml`. For example: ```yaml -html_document: - self_contained: false - theme: united - highlight: textmate +output_yaml: config/my_custom_opts.yml ``` -It should not be written as: +Note that -```yaml ---- -output: +- options explicitly defined within a document will always override those specified in the separate `output_yaml` file. + +- if the `output_yaml` option is not explicitly set in a document, it will default to the file `_output.yml` within the same directory and -- if it exists -- automatically inherit its content. + +- in the `output_yaml` file no YAML delimiters (`---`) or the enclosing `output` field are used. A correct example of the file's content could look like: + + ```yaml html_document: self_contained: false theme: united highlight: textmate ---- -``` - -All documents located in the same directory as `_output.yml` will inherit its options. Options defined explicitly within documents will override those specified in the shared options file. + ``` + + But _not_: + + ```yaml + --- + output: + html_document: + self_contained: false + theme: united + highlight: textmate + --- + ``` ### HTML fragments From 55665891e245740d83448e95217cd288f6167169 Mon Sep 17 00:00:00 2001 From: Salim B Date: Fri, 27 Mar 2020 00:04:58 +0000 Subject: [PATCH 2/3] Update 03-documents.Rmd --- 03-documents.Rmd | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/03-documents.Rmd b/03-documents.Rmd index f4b4511..335c2b4 100644 --- a/03-documents.Rmd +++ b/03-documents.Rmd @@ -972,7 +972,7 @@ Consult the documentation on [Pandoc templates](https://pandoc.org/README.html#t ### Other features -Similar to HTML documents, you can enable or disable certain Markdown extensions for generating PDF documents. See Section \@ref(markdown-extensions) for details. You can also pass more custom Pandoc arguments through the `pandoc_args` option (Section \@ref(pandoc-arguments)), and define shared options in `_output.yml` (Section \@ref(shared-options)). +Similar to HTML documents, you can enable or disable certain Markdown extensions for generating PDF documents. See Section \@ref(markdown-extensions) for details. You can also pass more custom Pandoc arguments through the `pandoc_args` option (Section \@ref(pandoc-arguments)), and define shared output options in a separate YAML file (Section \@ref(shared-options)). ## Word document From a5127e9fc64bc48700742e598de12a68511475eb Mon Sep 17 00:00:00 2001 From: Salim B Date: Fri, 27 Mar 2020 00:10:23 +0000 Subject: [PATCH 3/3] Update 03-documents.Rmd --- 03-documents.Rmd | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/03-documents.Rmd b/03-documents.Rmd index 335c2b4..855d19d 100644 --- a/03-documents.Rmd +++ b/03-documents.Rmd @@ -1002,7 +1002,7 @@ For more on how to create and use a reference document, you may watch this short ### Other features -Refer to Section \@ref(html-document) for the documentation of most features of Word documents, including figure options (Section \@ref(figure-options)), data frame printing (Section \@ref(data-frame-printing)), syntax highlighting (Section \@ref(appearance-and-style)), keeping Markdown (Section \@ref(keeping-markdown)), Markdown extensions (Section \@ref(markdown-extensions)), Pandoc arguments (Section \@ref(pandoc-arguments)), and shared options (Section \@ref(shared-options)). +Refer to Section \@ref(html-document) for the documentation of most features of Word documents, including figure options (Section \@ref(figure-options)), data frame printing (Section \@ref(data-frame-printing)), syntax highlighting (Section \@ref(appearance-and-style)), keeping Markdown (Section \@ref(keeping-markdown)), Markdown extensions (Section \@ref(markdown-extensions)), Pandoc arguments (Section \@ref(pandoc-arguments)), and shared output options (Section \@ref(shared-options)). ## OpenDocument Text document @@ -1030,7 +1030,7 @@ output: ### Other features -Refer to Section \@ref(html-document) for the documentation of most features of ODT documents, including figure options (Section \@ref(figure-options)), keeping Markdown (Section \@ref(keeping-markdown)), header and before/after body inclusions (Section \@ref(includes)), custom templates (Section \@ref(custom-templates)), Markdown extensions (Section \@ref(markdown-extensions)), Pandoc arguments (Section \@ref(pandoc-arguments)), and shared options (Section \@ref(shared-options)). +Refer to Section \@ref(html-document) for the documentation of most features of ODT documents, including figure options (Section \@ref(figure-options)), keeping Markdown (Section \@ref(keeping-markdown)), header and before/after body inclusions (Section \@ref(includes)), custom templates (Section \@ref(custom-templates)), Markdown extensions (Section \@ref(markdown-extensions)), Pandoc arguments (Section \@ref(pandoc-arguments)), and shared output options (Section \@ref(shared-options)). ## Rich Text Format document @@ -1055,7 +1055,7 @@ knitr::raw_output(readLines('table.rtf')) ### Other features -Refer to Section \@ref(html-document) for the documentation of most features of RTF documents, including table of contents (Section \@ref(table-of-contents)), figure options (Section \@ref(figure-options)), keeping Markdown (Section \@ref(keeping-markdown)), Markdown extensions (Section \@ref(markdown-extensions)), Pandoc arguments (Section \@ref(pandoc-arguments)), and shared options (Section \@ref(shared-options)). +Refer to Section \@ref(html-document) for the documentation of most features of RTF documents, including table of contents (Section \@ref(table-of-contents)), figure options (Section \@ref(figure-options)), keeping Markdown (Section \@ref(keeping-markdown)), Markdown extensions (Section \@ref(markdown-extensions)), Pandoc arguments (Section \@ref(pandoc-arguments)), and shared output options (Section \@ref(shared-options)). ## Markdown document @@ -1121,7 +1121,7 @@ In many cases, you can simply copy and paste the Markdown generated by `rmarkdow ### Other features -Refer to Section \@ref(html-document) for the documentation of other features of Markdown documents, including table of contents (Section \@ref(table-of-contents)), figure options (Section \@ref(figure-options)), header and before/after body inclusions (Section \@ref(includes)), Pandoc arguments (Section \@ref(pandoc-arguments)), and shared options (Section \@ref(shared-options)). +Refer to Section \@ref(html-document) for the documentation of other features of Markdown documents, including table of contents (Section \@ref(table-of-contents)), figure options (Section \@ref(figure-options)), header and before/after body inclusions (Section \@ref(includes)), Pandoc arguments (Section \@ref(pandoc-arguments)), and shared output options (Section \@ref(shared-options)). ## R package vignette