YAML

In an R Markdown (.Rmd) document, the section enclosed between two lines of --- at the beginning is called the YAML header (or YAML front matter).

It specifies metadata about the document and controls how the document is rendered.

Your example:

---
title: "The Carbon Footprint of Nations"
output: html_document
---

contains two parameters:

title: The title of the document, displayed at the top of the rendered output.
output: The format of the rendered document. Here, html_document produces an HTML page.

1. Common YAML header parameters

Parameter	Meaning	Example
`title`	Document title	`"The Carbon Footprint of Nations"`
`subtitle`	Subtitle displayed below the title	`"A Global Analysis"`
`author`	Author's name	`"John Smith"`
`date`	Document date	`"2026-10-27"`
`output`	Output format	`html_document`
`abstract`	Document abstract (supported by some formats)	`"An analysis of emissions"`
`bibliography`	Bibliography file	`references.bib`
`csl`	Citation style file	`apa.csl`
`lang`	Document language	`en`

For example:

---
title: "The Carbon Footprint of Nations"
subtitle: "A Global Analysis"
author: "John Smith"
date: "2026-10-27"
output: html_document
bibliography: references.bib
---

Not every parameter is supported by every output format.

2. Output formats

The output parameter determines the type of document produced.

Value	Output
`html_document`	HTML webpage
`pdf_document`	PDF document
`word_document`	Microsoft Word document
`github_document`	GitHub-flavored Markdown
`md_document`	Markdown document
`ioslides_presentation`	HTML slides
`slidy_presentation`	HTML slides
`beamer_presentation`	PDF slides using LaTeX Beamer

You can specify multiple formats:

---
title: "The Carbon Footprint of Nations"
output:
  html_document: default
  pdf_document: default
  word_document: default
---

The available formats depend on the installed R packages.

3. HTML document options

When using html_document, you can customize the appearance and behavior of the generated webpage.

---
title: "The Carbon Footprint of Nations"
author: "John Smith"
output:
  html_document:
    toc: true
    toc_depth: 3
    toc_float: true
    number_sections: true
    theme: flatly
    highlight: tango
    code_folding: hide
    df_print: paged
    self_contained: true
---

Here are the meanings:

Parameter	Meaning
`toc`	Include a table of contents
`toc_depth`	Number of heading levels included in the table of contents
`toc_float`	Display a floating table of contents
`number_sections`	Automatically number sections
`theme`	Bootstrap theme controlling document appearance
`highlight`	Syntax highlighting style for code
`code_folding`	Allow readers to show or hide code
`df_print`	How data frames are displayed
`self_contained`	Embed supporting resources into a single HTML file
`css`	Path to a custom CSS stylesheet
`includes`	Include additional HTML content
`keep_md`	Preserve the intermediate Markdown file

For example, code_folding: hide initially hides code blocks but allows readers to reveal them.

Available themes

The theme option uses Bootstrap/Bootswatch themes. You can consult the Bootswatch theme gallery to compare the visual styles.

You can also set theme: null to disable the Bootstrap theme.

Available syntax highlighting styles

The classic html_document format supports the following highlight values:

Highlight	General appearance
`default`	Standard syntax highlighting
`tango`	Light background, colorful syntax
`pygments`	Traditional syntax highlighting
`kate`	KDE Kate editor-inspired colors
`monochrome`	Minimal, largely monochromatic
`espresso`	Dark, warm-toned syntax highlighting
`zenburn`	Dark background, muted colors
`haddock`	Haskell Haddock-inspired highlighting
`breezedark`	Dark editor-inspired palette
`textmate`	TextMate-inspired syntax colors

You can use highlight: null to disable syntax highlighting.

Recommended combinations

Theme	Highlight	Suggested use
`flatly`	`tango`	Academic reports
`cosmo`	`textmate`	Modern technical documents
`readable`	`pygments`	Long-form reports
`spacelab`	`kate`	Data analysis
`darkly`	`zenburn`	Dark-themed documents
`slate`	`breezedark`	Dark technical reports
`journal`	`tango`	Articles and essays

4. PDF document options

For PDF output, typical options include:

---
title: "The Carbon Footprint of Nations"
author: "John Smith"
output:
  pdf_document:
    toc: true
    number_sections: true
    fig_caption: true
    latex_engine: xelatex
fontsize: 11pt
geometry: margin=1in
---

Parameter	Meaning
`toc`	Include a table of contents
`number_sections`	Number sections automatically
`fig_caption`	Enable figure captions
`latex_engine`	LaTeX engine used to generate the PDF
`fontsize`	Main document font size
`geometry`	Page layout, including margins

PDF rendering generally requires a LaTeX installation, such as TinyTeX.

5. Custom parameters

You can define your own parameters using params:

---
title: "The Carbon Footprint of Nations"
output: html_document
params:
  country: "Italy"
  year: 2025
  include_plots: true
---

Inside the R Markdown document, access them using:

params$country
params$year
params$include_plots

This is useful for generating different versions of the same report without changing its source code.

6. Important distinction: YAML versus R Markdown

The YAML header is not R code. It follows YAML syntax:

Indentation is significant; use spaces rather than tabs.
Key-value pairs use :.
Boolean values are true and false.
Nested options are represented through indentation.
Strings can be quoted, especially when they contain special characters.

Also, some options are interpreted by Pandoc, others by the rmarkdown package, and others by knitr. Consequently, there is no single exhaustive list of YAML parameters that applies to every R Markdown document.

For authoritative documentation, see the R Markdown: The Definitive Guide and the R Markdown output formats documentation.

For a typical HTML-based analytical report, a good starting header is:

---
title: "The Carbon Footprint of Nations"
author: "John Smith"
date: "`r Sys.Date()`"
output:
  html_document:
    toc: true
    toc_depth: 3
    number_sections: true
    theme: flatly
    code_folding: hide
---

This produces a structured HTML report with a table of contents, numbered sections, a visual theme, collapsible R code, and an automatically updated date.