Markdown

1 R Markdown

1.1 Overview

This is an RMarkdown document. Markdown is a simple formatting syntax for authoring HTML, PDF, and MS Word documents. For more details on using R Markdown see https://rmarkdown.rstudio.com (archived at https://perma.cc/4MP3-5RT8)

You can embed an R code chunk like this:

```{r}
summary(cars)
```

summary(cars)

     speed           dist       
 Min.   : 4.0   Min.   :  2.00  
 1st Qu.:12.0   1st Qu.: 26.00  
 Median :15.0   Median : 36.00  
 Mean   :15.4   Mean   : 42.98  
 3rd Qu.:19.0   3rd Qu.: 56.00  
 Max.   :25.0   Max.   :120.00  

1.2 Reference Guide

https://www.rstudio.com/wp-content/uploads/2015/03/rmarkdown-reference.pdf (archived at https://perma.cc/8P7X-9XPV)

2 Lab Wiki

2.1 Best Practices

Adapted from here (archived at https://perma.cc/P75L-3UM9):

• Use a new line for every sentence. This helps with version control—individually changed sentences will be highlighted upon commits (which are easy to parse to identify the specific changes) rather than whole paragraphs (which are a nightmare to parse to identify the specific changes).
  • This formatting is incompatible with a double space after a period. Instead, use a single space after a period. To replace all double spaces with single spaces, do a find and replace for ". " → ". " Be careful not to blanket remove all double spaces because tabbed bullets have 3 spaces.
• Add protocol entries as links to the parent .Rmd file (or to README.md)
• Add linked content (e.g., images) to sub-directories
• Use no spaces in file or folder names. Use a dash (-) instead of a space.
• If you use Visual Studio Code to edit the Lab Wiki, you can view the source code side-by-side with the markdown Preview (after selecting the code type as markdown):
• When making numbered (ordered) lists, just use 1. for all numbers. Markdown will make them sequential automatically. This is helpful if you go back and add additional entries later.
• For all quotation marks, use straight quotes (', ") rather than curly quotes (‘, ’, “, ”).
• Use "[XXX]" to indicate an area that needs editing. This will allow the lab to CTRL+F for "[XXX]" and find areas that need editing.
• To update the list of R packages that are installed for running the .Rmd files, update the DESCRIPTION file.
• When adding a link to an external (non-lab) URL, add both the original link and the perma.cc link to prevent link rot (websites will go offline and disappear over time). For example: http://www.cookbook-r.com/Graphs/Scatterplots_(ggplot2)/ (archived at https://perma.cc/N4TL-JQS4) You can get a perma.cc account through the UI Libraries.
• As noted in the links section, link to the heading label, and do not use the website-derived link for a given heading because it is not a stable link; the heading path can change if other headings are added.

2.2 Updating

To update the lab wiki, perform the following steps:

1. (Perform this step if you do not already have the the LabWiki GitHub repo on your local machine:) Clone the GitHub repo to your local machine.
2. Fetch the latest version of the repo. It is important to do this to make sure you have the latest version locally before making any changes.
3. Edit the relevant .Rmd files using RStudio or Visual Studio Code.
4. Preview the wiki before you commit changes to the site; create the .html files locally (in a folder called _site) by running the following command:
   • rmarkdown::render_site()
5. If the .html files look correct, commit the changes.
6. Push the changes to the GitHub repo. After pushing the changes to the GitHub repo, GitHub Actions will automatically re-run the code and deploy the updated website, assuming there were no errors. You can track the workflow for errors here: https://github.com/DevPsyLab/LabWiki/actions.

For more information about the rmarkdown package that was used to generate the site, see the following links:

• https://bookdown.org/yihui/rmarkdown/rmarkdown-site.html (archived at https://perma.cc/5C4T-SY9V)
• https://bookdown.org/yihui/rmarkdown/html-document.html (archived at https://perma.cc/WQS5-KH4S)

3 Software

You can create/edit R Markdown (.Rmd) files with the following free software:

• Microsoft Visual Studio Code
• RStudio

3.1 Microsoft Visual Studio Code

If you use Visual Studio Code to create/edit .Rmd documents, you can view the source code side-by-side with the markdown Preview (after selecting the code type as markdown):

3.2 RStudio

3.2.1 Creating a Code Chunk

Add a new chunk by clicking the Insert Chunk button on the toolbar or by pressing Ctrl+Alt+I.

3.2.2 Running a Code Chunk

You can execute a code chunk in an R Markdown Notebook by clicking the Run button within the chunk or by placing your cursor inside it and pressing Ctrl+Shift+Enter. To run more than one code chunk, you have several options:

• click the Run button within the chunks you want to run
• select “Run All Chunks Above”
• select “Run All Chunks Below”
• select “Run All”

3.2.3 Creating the HTML Output

When you click the Knit button, a document will be generated that includes both content as well as the output of any embedded Rcode chunks within the document.

When you save the computational notebook (.Rmd), an HTML (.html) file containing the code and output will be saved alongside it (click the Preview button or press Ctrl+Shift+K to preview the HTML file).

The preview shows you a rendered HTML copy of the contents of the editor. Consequently, unlike Knit, Preview does not run any R code chunks. Instead, the output of the chunk when it was last run in the editor is displayed.

4 Computational Notebook

4.1 General Info

You can use an R Markdown Notebook to create a computational notebook. For more information on the value of computational notebooks, see the article titled “The Scientific Paper Is Obsolete” (https://www.theatlantic.com/science/archive/2018/04/the-scientific-paper-is-obsolete/556676/; archived at https://perma.cc/XHW4-K89V)“. For more information about how to create R Notebooks, see here:

https://garrettgman.github.io/rmarkdown/r_notebooks (archived at https://perma.cc/L78P-G73Z)

https://bookdown.org/yihui/rmarkdown/notebook.html (archived at https://perma.cc/P5YT-395F)

4.2 Files

Consistent with the Petersen Lab template for how to structure your repo, you should have two computational notebooks: 1) a “Prepare Data” script (prepareData.Rmd) and 2) a “Computational Notebook” script (computationalNotebook.Rmd). The “Prepare Data” script is used to update the data file by re-exporting, merging, re-running calculations, etc. This script should be separate from the “Computational Notebook” file that is used for running analyses on the data. Every time you run the “Computational Notebook” file with the exact same data, you should get the exact same findings (i.e., reproducibility). Thus, we keep the “Prepare Data script” separate from the “Computational Notebook” file so that you update the data only when you intend to.

4.3 Structure

When creating a computational notebook, follow the structure of the computational notebooks in the Petersen Lab template.

To use the lab templates for the “Prepare Data” and “Computational Notebook” scripts, first install the petersenlab package. Then, in RStudio, select “File” > “New File” > “R Markdown”. Then, select “From Template”, and select either the “prepareData” or “computationalNotebook” template.

If you want to create a computational notebook manually (instead of using the lab template), create a .Rmd file with the following YAML header at the top of the file:

---
title: "INSERT TITLE"
author: "INSERT AUTHOR NAME(S)"
date: "`r format(Sys.time(), '%d %B, %Y')`"
output: 
  html_document:
    toc: true
    toc_depth: 4
    toc_float: true
    number_sections: true
    code_folding: show
    df_print: paged
---

If this is your “Computational Notebook” script, include the following as the first code chunk:

```{r setup, include = FALSE}
knitr::opts_chunk$set(
  echo = TRUE, # print code
  error = TRUE # do not interrupt in case of errors
)

# Use for higher quality figures on Windows devices
trace(grDevices::png, quote({
  if (missing(type) && missing(antialias)) {
    type <- "cairo-png"
    antialias <- "subpixel"
  }
}), print = FALSE)
```

If this is your “Prepare Data” script, include the following as the first code chunk:

```{r setup, include = FALSE}
knitr::opts_chunk$set(
  echo = TRUE # print code
)
```

Then, include whatever text and/or code chunks.

4.4 Creating CSS Commands

Personalized commands can be created in Visual Code through the CSS file within the Wiki folder. To create a new CSS command:

1. In Visual Studio Code, open the css tab within the Wiki Folder

2. Open the # srs.css file under the css tab

3. Enter in your personalized command according to the following structure:

COMMAND_NAME {
  command-specification1: value1;
  command-specification2: value2;
  command-specification3: value3;
  quotes: """ """ "‘" "'";
}

1. The following specifications may be added to your command:
   • font-size: Value = percentage
     • e.g., font-size: 150%
   • font-style: Value = bold, italic, underline
     • e.g., font-style: bold, font-style: italic
   • color: Value = color name or color code
     • e.g., color: green, color: #0e6b1c
   • To edit the command to add quotations, include the following after the end bracket of the command: COMMAND_NAME:before { content: open-quote; } COMMAND_NAME:after { content: close-quote; }
2. An example of a command is presented here:

example {
  font-size: 150%;
  font-style: italic;
  color:#C800FC;
  quotes: """ """ "‘" "'";
}
example:before { content: open-quote; }
example:after  { content: close-quote; }

5 rmarkdown/Quarto Website using GitHub Actions

5.1 Steps to Create

1. Create a new GitHub repo under the DevPsyLab organization in GitHub
2. Create the repository using one of the following templates (and select “Include all branches”):
   • rmarkdown: https://github.com/DevPsyLab/MarkdownWebsite
     • for local rendering: https://github.com/DevPsyLab/MarkdownWebsite-RenderLocal
   • Quarto: https://github.com/DevPsyLab/QuartoWebsite
     • for local rendering: https://github.com/DevPsyLab/QuartoWebsite-RenderLocal

If you do not create the repository from a template, the steps for creating the repo manually are below:

1. Create a README.md file
   • this is the file that people see when navigating to the repo
2. Add a .gitignore file
   • this file says what file types to ignore and not add to the repo
3. Create a new branch called gh-pages
4. Delete all files in the gh-pages branch
5. Switch back the main branch of the repo, and add the following contents (to the main branch, not to the gh-pages branch):
   • /.github/workflows/deploy_markdown.yml file
     • this file tells GitHub Actions was steps to run
     • add the following contents to the file:
       • if using rmarkdown:
         • if the website is intended to be public: https://github.com/DevPsyLab/LabWiki/blob/main/.github/workflows/deploy_rmarkdown.yml
         • if the website is intended to be private: https://github.com/DevPsyLab/SchoolReadinessStudy/blob/main/.github/workflows/deploy_rmarkdown.yml
       • if using Quarto:
         • if the website is intended to be public: https://github.com/DevPsyLab/QuartoWebsite/blob/main/.github/workflows/publish.yml
         • if the website is intended to be private: https://github.com/DevPsyLab/QuartoWebsite-RenderLocal/blob/main/.github/workflows/publish.yml
   • YAML file—this file creates the navbar:
     • if using rmarkdown:
       • _site.yml file
     • if using Quarto:
       • _quarto.yml file
   • LICENSE file
     • this file is the license
   • DESCRIPTION file
     • this file tells GitHub Actions what R packages to install
6. Add each .Rmd file (for rmarkdown) or .qmd file (for Quarto)
7. Add folders for the font, images, and includes
   • includes contains css files, javascript files, footers, and Google Analytics
8. If the rmarkdown website is intended to be public, create a new Google Analytics property, and replace the URL and gtag in the google_analytics.html file
9. Commit the repo to GitHub
10. To deploy the website on GitHub Pages:
    1. Make the repo public (Settings > General > Change Visibility)
    2. Activate GitHub Pages (Settings > Pages)
       • Source: “Deploy from a Branch”
       • Branch: gh-pages/root
       • Click “Save”
    3. Make sure “Read and write permissions” are enabled in Settings -> Actions -> General -> Workflow permissions

5.2 Quarto Manuscripts

• Quarto Journal Templates: https://github.com/quarto-journals
• Sample Manuscripts: https://quarto.org/docs/manuscripts

Example:

• https://github.com/mine-cetinkaya-rundel/indo-rct
  • https://mine-cetinkaya-rundel.github.io/indo-rct/

To prevent code from re-running unless code is altered:

execute:
    freeze: auto

5.3 Troubleshooting

If you get the following error in GitHub Actions:

remote: Permission to GITHUB_USERNAME/REPO_NAME.git denied to github-actions[bot].
fatal: unable to access 'https://github.com/GITHUB_USERNAME/REPO_NAME.git/': The requested URL returned error: 403

Check if “Read and write permissions” are enabled in Settings -> Actions -> General -> Workflow permissions: https://stackoverflow.com/a/75308228/2029527 (archived at https://perma.cc/R57Z-9JUS)

6 Including Plots

You can embed plots, for example:

```{r, echo = FALSE}
plot(pressure)
```

Note that the echo = FALSE parameter was added to the code chunk to prevent printing of the R code that generated the plot.

7 Headings

7.1 Subheading

7.1.1 Subsubheading

7.1.1.1 Subsubsubheading

# Headings {#heading-label1}

## Subheading {#heading-label2}

### Subsubheading {#heading-label3}

#### Subsubsubheading {#heading-label4}

8 Lists

To add another element in a list while preserving the continuity of the list, indent the element four spaces or one tab.

8.1 Unordered Lists

To create an unordered list, add a dash (-) in front of line items. Adding an asterisk (*) or plus sign (+) in front of line items will also create an unordered list; however, the lab convention is to use dashes for unordered lists. We use asterisks for adding emphasis to text.

- one item
- one item
- one item
    - one more item
    - one more item
    - one more item
        - lower level
            - sub-item 1
            - sub-item 2

• one item
• one item
• one item
  • one more item
  • one more item
  • one more item
    • lower level
      • sub-item 1
      • sub-item 2

8.1.1 Checkboxes

- <input type="checkbox" unchecked> Box 1</input>
- <input type="checkbox" checked> Box 2</input>

• Box 1
• Box 2

8.2 Ordered Lists

1. the first item
    1. test
    1. test
        1. new test
        1. new test
1. the second item
    1. test
    1. test
1. the third item
    - one unordered item
        - subitem
    - one unordered item
1. fourth item
    1. test
    1. test
    1. test

1. the first item
   1. test
   2. test
      1. new test
      2. new test
2. the second item
   1. test
   2. test
3. the third item
   • one unordered item
     • subitem
   • one unordered item
4. fourth item
   1. test
   2. test
   3. test

9 Blockquotes

> Dorothy followed her through many of the beautiful rooms in her castle.
> 
> Continued...

Dorothy followed her through many of the beautiful rooms in her castle.

Continued…

10 Comments

10.1 Markdown

```markdown
[This is how to write a hidden comment in Markdown.]: # 
```

[This comment will be hidden.]: # 

[This is how to write a hidden comment in Markdown.]: # 

10.2 HTML

<!-- This text will be hidden -->

<!--
This multiline
text comment will be
hidden
-->

11 Emphasis

This text is **bolded text**.
This text is *italicized text*.
This text is ***bolded and italicized text***.
This text is <mark>highlighted text</mark>.
This text is <mark style="background-color: lightblue">highlighted text in a different color</mark>.
This text is `unicode text`.
This text is <code><i>code in italics;</i> this text is <b>code in bold</b></code>.
This text is ~~strikethrough text~~.
This text <u>will be underlined</u>; this text <ins>will also be underlined</ins>.
<font color="red">This text is red!</font>

This text is bolded text. This text is italicized text. This text is bolded and italicized text. This text is highlighted text. This text is highlighted text in a different color. This text is unicode text. This text is code in italics; this text is code in bold. This text is strikethrough text. This text will be underlined; this text will also be underlined. This text is red!

For underlining text, the lab convention is to use: <u>text to be underlined</u>.

12 Formatting

<center>This text is centered.</center>

This text is centered.

13 Code/Syntax Highlighting

To use syntax highlighting to display code without running the code:

```r
summary(cars)
```

summary(cars)

or

::: {.cell}

```{.r .cell-code}
`r ''`
summary(cars)
```
:::

summary(cars)

or

    summary(cars)

which yields:

summary(cars)

14 Math Formulas

Inline:

This is the formula: \(x = y + 5\). Solve for \(x\).

Separate line:

$$
y = \frac{x}{7} \cdot 4 + 3 \times 2 - 1_{a1}/2^{1c/2} \dots
$$

\[ y = \frac{x}{7} \cdot 4 + 3 \times 2 - 1_{a1}/2^{1c/2} \dots \]

15 Links

To link to a heading that is in the same wiki, make sure the heading has a label (e.g., {#label}), as shown here. Then, link to the heading with the following syntax: [text to show](#label). For example, to link to the links section, you would specify: [text to show](#links). If the heading is on a different page of the same wiki, specify the html file before the label, e.g.: [text to show](dataManagement.qmd#saveData). If the heading is on a different page of a different wiki, specify the full path before the label, e.g.: [text to show](https://devpsylab.github.io/LabWiki/manual.html#basicsLab). Do not use the website-derived link for a given heading because it is not a stable link; the heading path can change if other headings are added.

[I'm an inline-style link](https://www.google.com)

[I'm an inline-style link with title](https://www.google.com "Google's Homepage")

[I'm a reference-style link][Arbitrary case-insensitive reference text]

[I'm a relative reference to a repository file](../blob/master/LICENSE)

[You can use numbers for reference-style link definitions][1]

[I am a link to another file in this project](pca.qmd#overview)

[I'm a link within this document](#headings)

[I'm a link that opens in a new tab](https://example.com){target="_blank"}

URLs and URLs in angle brackets will automatically get turned into links. 
http://www.example.com or <http://www.example.com>

Some text to show that the reference links can follow later.

[arbitrary case-insensitive reference text]: <https://www.mozilla.org>
[1]: <https://slashdot.org/>

[![DevPsyLab](images/formalLogo.png)](https://developmental-psychopathology.lab.uiowa.edu/)

I’m an inline-style link

I’m an inline-style link with title

I’m a reference-style link

I’m a relative reference to a repository file

You can use numbers for reference-style link definitions

I am a link to another file in this project

I am a link to another file in this project

I’m a link within this document

I’m a link that opens in a new tab

URLs and URLs in angle brackets will automatically get turned into links. http://www.example.com or http://www.example.com

Some text to show that the reference links can follow later.

Link from an image:

DevPsyLab

16 Footnotes

Here is a simple footnote[^1].

A footnote can also have multiple lines[^2].  

You can also use words, to fit your writing style more closely[^note].

[^1]: My reference.
[^2]: Every new line should be prefixed with 2 spaces.  
  This allows you to have a footnote with multiple lines.
[^note]:
    Named footnotes will still render with numbers instead of the text but allow easier identification and linking.  
    This footnote also has been made with a different syntax using 4 spaces for new lines.

Here is a simple footnote¹.

A footnote can also have multiple lines².

You can also use words, to fit your writing style more closely³.

17 Symbols

- degree: (°) °

• degree: (°) °

17.1 Arrows

- left arrow: ← ←
- upward arrow: ↑ ↑
- right arrow: → →
- downward arrow: ↓ ↓

• left arrow: ← ←
• upward arrow: ↑ ↑
• right arrow: → →
• downward arrow: ↓ ↓

17.2 Dashes and Hyphens

- hyphen: -
- en dash: –
- em dash: —

• hyphen: -
• en dash: –
• em dash: —

17.3 Subscript/Superscript

17.3.1 Markdown

H~2O
X^2

H~2O

X^2

17.3.2 HTML

H<sub>2</sub>O
X<sup>2</sup>

H₂O

X²

17.4 Definition List

term
: definition

term

definition

17.5 Task list

- [x] Create the website
- [ ] Conduct the study
- [ ] Write it up

• Create the website
• Conduct the study
• Write it up

18 Table

| Syntax      | Description |
| ----------- | ----------- |
| Header      | Title |
| Paragraph   | First paragraph. <br><br> Second paragraph. |

| Syntax      | Description |
| ----------- | ----------- |
| Header      | Title |
| List        | Here's a list! <ul><li>Item one.</li><li>Item two.</li></ul> |

Syntax	Description
Header	Title
Paragraph	First paragraph. Second paragraph.

Syntax	Description
Header	Title
List	Here’s a list!

You can easily create tables in Markdown from an Excel or csv file using the following website: https://www.tablesgenerator.com/markdown_tables (archived at https://perma.cc/53TQ-DQJ9)

19 Adding a Drop Down List

Note:: When creating dropdown menus, it is important to have spaces between font breaks </font>. Without these breaks, Markdown cannot detect how to

<details>
<summary>**<font size = "6">This is a dropdown menu**</summary>

<font size = "4">

Insert Text Here

</font>
</details>

This is a dropdown menu

Insert Text Here

20 Embedding a Picture

![Insert Figure Caption here](Insert image filename and location here)

For instance:

![Visual Studio Code](images/vsCode.png)

21 Embedding a Video

• If the file is to be stored on a GitHub repo, the video file needs to be less than 50 MB. You may need to convert the video to a lower quality to make it smaller than 50 MB.

• By contrast, if the file is to be stored on a GitLab repo (on the UI Enterprise version of GitLab), the file may be larger than 50 MB, but first make sure the repository is configured for large file storage. Follow the instructions here to do so.

• A helpful example repository for embedding videos can be found here (archived at https://perma.cc/6RWF-PNR7)

<video width="100%" controls="" preload="none"> #video settings
<source src="images/lv2-saving-procedures.mp4" type="video/mp4"> #location and type of video
</video>

22 Embedding a PDF in a Markdown document

PDF’s can be embedded within markdown documents. Make sure the document you wish to embed is in a local folder (if you are adding it to a Wiki document).

• Note: Height and width can be adjusted to fit the page

<embed src="path to file" width="1000" height="600">

23 Embedding a HTML file within a Markdown document

The below line of code will embed a html document in a markdown file. The best way to configure formatting for this is still in progress.

Note: The htmltools package will need to be installed as a package dependency

htmltools::includeHTML("path to html file")

24 Converting Word Documents to Markdown

The process of converting word documents to Markdown is aided by having knowledge of the best practices steps.

To convert documents, follow these steps:

1. Open both word doc to be converted and new markdown document
2. Copy and paste the text to convert
3. Follow the best practices to convert the document to Markdown format
   • For example, in the manuals for the School Readiness Study, each new header should denote a new task
4. Importantly, each sentence will correspond to one line in markdown. To convert sentences out of paragraph form:
   • Press Ctrl f
   • search .
   • Next, click the arrow on the left side of the search window to open up the replace function in Visual Studio Code.
   • The goal of this process is to create one sentence per line. Creating one sentence per line. By using one sentence for line, changes can be tracked easier.
   • In the Replace line, type Ctrl Enter to create a new line.
   • Go through each find to determine if a new line should be created. Do not replace all. Bulleted lists may also contain a . that should not be removed.

25 Video formatting for Wiki

Handbrake can be used to lower video quality, and convert files to .mp4 format, in order for them to be incorporated into the wiki. It is important to lower the quality (i.e., file size) of videos so that we do not exceed the 1gb file size limit on any given repo.

25.1 Lowering File Size

• Open Handbrake and drag and drop the video that you would like to lower the file size of.
• Select the video tab and lower the Constant Quality to 30, and the Framerate (FPS): to 20
  • We have found this lowers file size, but saves video quality

Footnotes

1. My reference.

2. Every new line should be prefixed with 2 spaces.
   This allows you to have a footnote with multiple lines.

3. Named footnotes will still render with numbers instead of the text but allow easier identification and linking.
   This footnote also has been made with a different syntax using 4 spaces for new lines.