Automate All the Things

Erin M. Buchanan

2023-04-15

Outline

What and Why Markdown
The parts of a Markdown doc
Options to tweak documents
Options for output

What is Markdown?

“Markdown is a lightweight markup language for creating formatted text using a plain-text editor”
“Markdown is a lightweight markup language that you can use to add formatting elements to plain text text documents.”
“R Markdown provides an authoring framework for data science.”
In short, it’s a set of simple codes that help us transform text into formatted documents.

Flavors? Is this Ice Cream?

Markdown has multiple “flavors”
A good analogy is language dialect
R Markdown is for R, GitHub uses similar version and so on

Why should I use it?

You can create many types of things in markdown:
- Websites
- Books
- Academic/scientific reports
- Presentations (like this one!)
- and more!

Why should I use it?

Portable: since it is text, you can open it in many ways
Platform independent: technically since it’s raw text
Lots of people use it, so the skill transfers to unexpected places (Reddit, Slack)

Why should I use programming markdown?

Things like R markdown, Jupyter notebooks, Quarto, …
You can integrate text and code into the same document!
You can create reproducible reports
You can annotate your notes with reminders for later
Put everything in one place!
Have more control over documents
Cut and paste errors minimized

How it works

Some Useful Rmd Links

What do I need?

R, RStudio (software)
LaTeX for PDF documents

install.packages("tinytex")
tinytex::install_tinytex()

Word or something like it (Libre, OpenOffice) for DOC(X)
Powerpoint for PPT(X)

Other Packages

For today:

install.packages(c("rmarkdown", "knitr", "flextable", "dplyr", 
                   "rio", "ggplot2", "ggthemes", "treemapify"))

Specific goals:
- papaja is great for APA journal articles, and rticles has many journal article templates
- bookdown and blogdown for building open source text books and websites with markdown
- officedown and officer for Word document formatting

Let’s Get Started!

Let’s create a markdown template to show off the components
File > New File > Rmarkdown

Let’s Get Started!

Select your desired output (start with HTML)
Enter a title
Pick a template if you want
Create!

Rmd Document Parts - YAML

yet another markup language
Header of your document
The way you can control the type and options for the overall document

---
title: "Untitled" 
author: "Erin M. Buchanan"
date: "2023-04-15"
output: html_document
---

Rmd Document Parts - YAML

A note about YAMLs: it is very picky about indentation
YAML depends on the output options you pick
Let’s try a few of them out
“Knit” the document in html format to get an idea of what this looks like when you start

Knitting

The most important thing to remember: when you hit knit, everything you have in your environment is ignored
- You start with a blank slate
- You must load the libraries in the markdown
- The order matters!
Other things learned the hard way
- Don’t put View() in a markdown
- Don’t install packages in a markdown
- Watch out for funky symbols

HTML - YAML

Add a table of contents

output:
  html_document:
    toc: true
    toc_depth: 2

HTML - YAML

Floating table of contents

output:
  html_document:
    toc: true
    toc_float: true

output:
  html_document:
    toc: true
    toc_float:
      collapsed: false
      smooth_scroll: false

HTML - YAML

Number your sections

output:
  html_document:
    number_sections: true

HTML - YAML

theme: here are the options default, bootstrap, cerulean, cosmo, darkly, flatly, journal, lumen, paper, readable, sandstone, simplex, spacelab, united, and yeti
highlight: default, tango, pygments, kate, monochrome, espresso, zenburn, haddock, breezedark, and textmate
code_folding: hide or code_folding: show allow you to show your code but enable people to hide it

output:
  html_document:
    theme: united
    highlight: tango

PDF - YAML

Many of the same features still work
Tables of contents, code highlighting
Options for the Pandoc engines (aka how it knits)

Word - YAML

Many of the same features still work
Tables of contents, code highlighting
Best feature: creating a custom style

output:
  word_document:
    reference_docx: my-styles.docx

Rmd Document Parts - Narrative

Any section you write raw text
You can add the official markdown here
You can add LaTeX to create fancy equations and symbols \(\beta\)
You can use raw LaTeX or HTML that will be converted
And more!

## R Markdown

This is an R Markdown document. Markdown is a simple formatting syntax for authoring HTML, PDF, and MS Word documents. For more details on using R Markdown see <http://rmarkdown.rstudio.com>.

When you click the **Knit** button a document will be generated that includes both content as well as the output of any embedded R code chunks within the document. You can embed an R code chunk like this:

Rmd Document Parts - Narrative

A note about spacing: you have to leave a blank line between items if you want to make a new paragraph
What are the most common things we can add?
Text styling, links, citations and more

Narrative - Headers/Blocks

# First-level header

## Second-level header

### Third-level header

Narrative - Text Styles

italic: _text_or *text
Bold: *text*
M_Group: M~Group~
R²: R^2^
Links: [text](link)
Images: ![alt text or image title](path/to/image)
- Or use the knitr package: include_graphics("path/to/image")
Footnotes¹: ^[This is a footnote.]

Narrative - Lists

You can make numbered or bulleted lists

- one item
- one item
- one item
    - one more item
    - one more item
    - one more item

Narrative - Citations

There are a few ways to enter citations but generally are listed as @citationname
This @citationname is found stored in a separate .bib. file that might have an entry like this:

@Manual{R-base,
  title = {R: A Language and Environment for Statistical
    Computing},
  author = {{R Core Team}},
  organization = {R Foundation for Statistical Computing},
  address = {Vienna, Austria},
  year = {2017},
  url = {https://www.R-project.org/},
}

Narrative - Citations

How can I create the bib file or organize the citations?
You can use a free/paid manager like Zotero or Endnote
You can export them from the journal website
You can let RStudio do it for you with the Visual editor