Writing

Topics

  • Markdown syntax
  • Referencing

Markdown syntax

When writing the body of your document, you will use the Markdown format.

Markdown is a lightweight markup language that you can use to add formatting elements to plaintext text documents. - Markdown Guide

A World With Markdown

Code

Welcome to my markdown document. 
We can have **bold**, _italic_, 
***bold and italics*** text.
Also, we have:

- An
- Unordered
- List

Not bad right?

Output

Welcome to my markdown document. We can have bold, italic, bold and italics text. Also, we have:

  • An
  • Unordered
  • List

Not bad right?




Markdown is the

lingua franca

to creating any kind of document

Markdown in the wild: Reddit

Demo using markdown to make a post on the website Reddit.com

Writing a post using markdown on Stanford’s Subreddit

Markdown in the wild: GitHub

Demo using markdown to create an issue on the website GitHub.com

Writing an issue using markdown on GitHub

Markdown Sneak Peek: Text Formatting

Markdown Syntax Output 
*italics* and **bold**
 italics and bold 
superscript^2^ / subscript~2~
 superscript2 / subscript2 
~~strikethrough~~
 strikethrough 
`verbatim code`
 verbatim code

Markdown sneak peek: Headers

Markdown Syntax Output 
# Header 1

Header 1

 
## Header 2

Header 2

 
### Header 3

Header 3

 
#### Header 4

Header 4

Markdown sneak peek: Quotes

Code

> "Never gonna give you up,
>  never gonna let you down..."
>
> --- Rick Astley

Output

“Never gonna give you up, never gonna let you down…”

— Rick Astley

Markdown sneak peek: Math

  • Anything inside dollar signs $ is treated as “inline” maths
  • $$ is a standalone equation
  • Whitespace matters: $x$ is an equation, $x $ is not
  • Equations follow “LaTeX” rules

Markdown sneak peek: Math

Code

Inline math: 
$a^2 + b^2 = c^2$

Display math (centered math):
$$1 - x = y$$

Output

Inline math: \(a^2 + b^2 = c^2\)

Display math (centered math): \[1 - x = y\]

Markdown sneak peek: Lists unordered

Code

My **un**ordered list:

- Write Selection Simulation
- Conference Abstracts
     - UseR
     - Learning at Scale

Output

My unordered list:

  • Write Selection Simulation
  • Conference Abstracts
    • UseR
    • Learning at Scale

Markdown sneak peek: Lists ordered

Code

My **ordered** list:

1. Apples
1. Bananas
1. Chobani
    1. Pineapple
    1. Everything else

Output

My ordered list:

  1. Apples
  2. Bananas
  3. Chobani
    1. Pineapple
    2. Everything else

Markdown sneak peek: Summary

Important

Make sure a new line (space) exists between text and the first list item. For sublists or nested lists, indent four spaces to create a new level in the list.

Tip

To simplify ordered lists and allow for moving items in the list around, use 1. for each item. If a list needs to be broken, numbering is only continued if each entry is labeled using 1., 2., 3., … format.

Markdown sneak peek: Tables

Code

| Left                    | Center          | Right   |
|-------------------------|:---------------:|--------:|
| Hey, check it out       | Colons provide  |    873  |
| its **Markdown**        | alignment thus  |   1000  |
| right in the table      | *centered* text |         |

Output

Left Center Right
Hey, check it out Colons provide 873
its Markdown alignment thus 1000
right in the table centered text

Table: Tip

Tip

Visual mode provides a Table menu to setup quarto tables or use the table generator website.

Callout blocks

  • Call-out blocks highlight sections of text that interrupt the flow of your regular text. Maybe it’s a definition, a warning, or a sidenote

  • When rendering your document to HTML, callout blocks are interactive and can be collapsed and opened.

    My First Callout Block!

    Say things here

Callout blocks

Note

Note that there are five types of callouts, including: note, tip, warning, caution, and important.

Warning

Callouts provide a simple way to attract attention, for example, to this warning.

This is important

Danger, callouts will really improve your writing.

Callout blocks

Tip with caption

Run this first

Caution, under construction

Here is something under construction

Callout markdown syntax

Expand To Learn About Collapse

This is an example of a ‘folded’ caution callout that can be expanded by the user. You can use `collapse=“true”` to collapse it by default or `collapse=“false”` to make a collapsible callout that is expanded by default.

Tabsets

Split up and flip between sections of a page, alternative to just two columns

library(ggplot2)
fig = ggplot(airquality, aes(Temp, Ozone)) + 
  geom_point() + 
  geom_smooth(method = "loess", se = FALSE)
fig

Markdown quick reference in RStudio

Opening the built-in Markdown quick reference sheet inside of RStudio by going to the help menu and selecting 'Markdown Quick Reference'.

Accessing the “Markdown Quick Reference” Guide inside of RStudio

Learning Markdown

You can familiarize yourself with Markdown in a couple of minutes using the following link: https://www.markdownguide.org/cheat-sheet/.

You can also use the Visual Editor in VS Code or RStudio, to see Markdown syntax previewed in it’s final format as you write. The Visual Editor also has some common Word-like shortcuts, such as Ctrl + B to make text bold.

Markdown exercise

  1. Go to the Writing/Reference section on the website and refer to the text provided in the Exercise section.

  2. Copy the text into your Quarto document, like an Introduction of sorts, and reformat it with Markdown Syntax

  3. Render the document to HTML.

10:00

Referencing

BibTex Keys

Now that we know how to write in Markdown, let’s add some references!

Adding reproducible references happens with BibTex keys. A typical BibTex key might look like as follows:

@article{nash51,
  author  = "Nash, John",
  title   = "Non-cooperative Games",
  journal = "Annals of Mathematics",
  year    = 1951,
  volume  = "54",
  number  = "2",
  pages   = "286--295"
}

Working With BibTex Keys

We will work with with bibliographies in the form of .bib files (BibTeX Bibliographical Database). .bib files are text files which contain a list of references in the form of BibTex keys.

Here is an example of another BibTex key for a reference used in this workshop:

@misc{RMarkdownWritingReproducible,
    title = {{RMarkdown} for writing reproducible scientific papers},
    url = {https://libscie.github.io/rmarkdown-workshop/handout.html},
    urldate = {2023-04-18},
}

Working With BibTex Keys

The typical workflow is as follows:

  1. Find a reference that you need in your manuscript.
  2. Save it to your Zotero library via the browser extension
    Zotero automatically updates your .bib file through syncing with Zotero desktop and updating the .bib file.
  3. Cite the references using the @ + reference identifier:
    • In-text citations: @nash51 OR @RMarkdownWritingReproducible
    • Bracketed citations: [@nash51] OR [@nash51, @RMarkdownWritingReproducible]
---
bibliography: references.bib
---

More info: https://quarto.org/docs/authoring/footnotes-and-citations.html

References on the fly

  • Alternatively, when using the Visual Editor option - you can use the citation dialog/option to insert citations directly.

  • Let’s go to RStudio!

Exercise

Go to the Referencing section on the website and refer to the instructions in the Exercise section.

You will go through the workflow of creating a .bib file that will be automatically updated by Zotero and integrating it with your Quarto document.

10:00

APA Style

  • You need to use a csl (citation style guide) file to make sure references are properly formatted

  • I have included the apa7.csl file in the project folder

    • This will format references/citations in accordance with APA 7th edition

Exercise

  • Add the csl to your YAML and include the apa7.csl file

  • Render your document

02:00