Formatting Your Content - Markdown

Now we know which files to edit, but how can we edit these files? How do we format our text, links, headers, …?

Visaul R Markdown

All our files are made up of code and markdown syntax, that becomes formatted into our website. However, if you do not feel comfortable using Markdown (or you just want an easier way to write your pages), see this guide on using Visual R Markdown.

It can be significantly easier to use Visual R Markdown, especially for those who are used to working in Google Docs!

If you want to use Markdown, a basic syntax guide is provided below!

Is this not enough for you?

Bookdown has thorough documentation for specific elements, customizations, and further explanations. For simple elements, everything is provided below. However, there are many more possibilities with Bookdown! Click here to read more!

IMPORTANT NOTE: Now that you’re straying away from CBW’s Bookdown template, there’s a chance you may run into errors. See this page for help!

Chapters

As mentioned earlier, headers are defined by a # before the title. Subheaders get increasingly more nested as add more # symbols before it. For example,

# Hello

would create a chapter title. Since there is only one # symbol, this would also create a new page. Again, try to keep only one chapter title per .Rmd file.

## Subheader

Subheader

This is what a subheader would look like.

### Subheader

Subheader

This is what a subheader with 3 # symbols would look like. You can add as many # symbols as you would like! There is also no limit to the the number of subheaders you can have.

An unnumbered subheader

Chapters and sections are numbered by default. To un-number a heading, add a {.unnumbered} or the {-} at the end of the heading. For example, the above subheader was written like this:

### An unnumbered subheader {-}

Parts

Notice how index.Rmd in our CBW Bookdown template has # (PART) Introduction {-} (followed by # Welcome). This creates the “Introduction” section on the sidebar.

There are already 2 main parts in the template: the introduction and modules sections.

If you want to add more parts, simply paste this: # (PART) [Part Title] {-} into a new .Rmd file, at the top of the file, before the main # header for that page/file.

Note: If you would like to have a un-numbered part: Use this syntax: # (PART\*) [Part Title] {-}

Another Note: A similar un-numbered part is called an “Appendix” and Bookdown. Like a part, paste # (APPENDIX) [Appendix Name] {-} it above the “main” header you would like it to be before. All subsequent headers will be described via letters rather than numbers. (If your following headers are un-numbered, an Appendix looks the same as an un-numbered part).

Text Formatting

Before we go ahead with much more formatting possibilities, let’s get the basics of markdown formatting options for basic text. (Tip: There are many resources online that can help give more information!)

Bold

**bolded text**

bolded text

Italics

*italicized text*

italicized text

Subscript

H~2~O

H2O

Superscript

Na^+^

Na+

Footnotes

^[] is the formatting for a footnote. For example

Here is a footnote: ^[This is a footnote.].

Here is a footnote: 1.

(Scroll to the bottom of this page to see it.)

Horizontal Line

---

Blockquote

> blockquote
>
> --- someone who blockquotes

blockquote

— someone who blockquotes

You can put emojis to help these standout! For example:

⚠️ Warning: Do not push the big red button.

Unordered List

- unordered
  - list
    - element
- cool!
  • unordered
    • list
      • element
  • cool!

Warning: Bookdown currently can not render Markdown to-do lists properly. Alternatively, use this tip instead!

Ordered List

1. First item
    1. a <!-- For nesting inside a list, put 2 tabs before the element -->
    2. b
2. Second item
3. Third item
  1. First
    1. a
      1. c
      2. d
    2. b
  2. Second
  3. Third

Code

There are 2 ways to write code:

  1. `code` which looks like this: code

  2. Or long pieces of code

    ```
1 + 1  # a line of code
```

    which would render into the following on your website

    1 + 1  # a line of code

Find more code options and information in the How to Render Code section.

Images

The basic notation for a file is:

![Alt Text](img/.../...)\

For example:

![bioinformatics.ca logo](img/bioinformatics_logo.png)\

bioinformatics.ca logo

Note: Markdown does not actually require the backslash “\”. However, since Bookdown uses Pandoc, we should add a backslash so that the alternative text does not become a caption for the image. This occurs when the image is not directly following or followed by text. Here is where it’s discussed in the Pandoc documentation!

Note: Before adding the “\”, Bookdown will show you the image that you are referring to (double-click the file address link) and it will remain on screen, within your .Rmd file. You can use this to double check the file address is correct. After adding the “\”, you can double-click to check the file address is pointing to the right image (and it should hover below), but it will not remain on screen.

Note!

If you want to easily annotate and update your images, consider publishing a Google Drawing! See the Developer’s Guide for instructions.

PDFs

Inserting PDFs is essentially the same notation as inserting images! See the module 1 file of the template for an example.

Essentially, it will look like this:

![insert alt text for pdf here](content-files/sample-pdf.pdf){width=100% height=900}\


Recall: Your files for your content should be organized into the “content-files” folder.

The width and height elements are HTML code, and are up to you!

Inserting YouTube Videos

YouTube generates HTML code to insert YouTube videos into your pages! You should specifically edit the width and height (what you edit it to is up to you). CBW recommends that {width=“100%”}.

How to get the HTML Code:

  1. Go to the YouTube video you want to embed.
  2. Click “Share”, which is below the video.
  3. Click the < > Embed symbol.
  4. Select your desired options and press copy.
  5. Paste the code into your .Rmd file.
  6. Edit the width and height options.
  7. Done!

An example of a YouTube video inserted into a Bookdown page is shown below!

Citations

Bookdown can help us create citations!

First, tell bookdown your sources!

# automatically create a bib database for R packages
knitr::write_bib(c(
  .packages(), 'bookdown', 'knitr', 'rmarkdown'
), 'packages.bib')

This R code created a file called ‘packages.bib’ (which is in the bookdown template) which is now filled with a bunch of bibliography entries. ‘book.bib’ also has a manually entered bibliography entry. We must tell bookdown the files with bibliography information via the YAML bibliography key in index.Rmd. A bibliography entry essentially looks like:

@type{key,
  title = {...},
  author = {...},
  organization = {...},
  year = {...},
  url = {...},
  ... # see more possible fields at https://en.wikipedia.org/wiki/BibTeX
}

@type refers to what type of source it is (ex. an article, book, manual, …). @key refers to the name we refer to it by in in-text citations.

For example, @R-bookdown renders to Xie (2025). Adding square brackets also adds parentheses once it’s rendered: so [@R-bookdown] becomes (Xie 2025).

Note: The RStudio Visual Markdown Editor can also make it easier to insert citations!

On any page that you cite, a References section will be autogenerated at the bottom of that page (scroll down)!

Note: When you cite, Bookdown also generates a citation list that it adds at the end of the last page of your website. However, Bookdown does not create a title, so on your very last page, add a # Reference main header. (To avoid having a “2 main headers in the same file” error, you can create a new .Rmd file with only # Reference).

Equations

Equations are written in latex. You can refer to them with a label you specify after writing it out!

\begin{equation}
  f\left(k\right) = \binom{n}{k} p^k\left(1-p\right)^{n-k}
  (\#eq:binom) # the label!
\end{equation}

\[\begin{equation} f\left(k\right) = \binom{n}{k} p^k\left(1-p\right)^{n-k} \tag{1} \end{equation}\]

You may refer to using \@ref(eq:binom), for example: see Equation \@ref(eq:binom) becomes “see Equation (1)”. The number (1) depends on the chapter and the number of equations already in said chapter (the first equation will be numbered [chapter number].1).

Theorems and Proofs

We also have specific syntax for theorems and proofs, for example, this code:

::: {.theorem #tri}
For a right triangle, if $c$ denotes the *length* of the hypotenuse
and $a$ and $b$ denote the lengths of the **other** two sides, we have
$$a^2 + b^2 = c^2$$
:::

Theorem 1 For a right triangle, if \(c\) denotes the length of the hypotenuse and \(a\) and \(b\) denote the lengths of the other two sides, we have \[a^2 + b^2 = c^2\]

Labeled theorems can be referenced in text using \@ref(thm:tri), for example, check out this smart theorem 1.

Learn more about styling and syntax for theorems and proofs here!

Callout blocks

CBW’s Bookdown template comes equipped with a “warning”, “tip” and “note: callout blocks!

Here are the code you will use to add them to your template and the rendered output.

:::: {.redbox data-latex=""}
::: {.center data-latex=""}
**WARNING!**
:::

Write your warning text here.
::::

WARNING!

Write your warning text here.


:::: {.bluebox data-latex=""}
::: {.center data-latex=""}
**NOTE!**
:::

Write your note here.
::::

NOTE!

Write your note here.


:::: {.greenbox data-latex=""}
::: {.center data-latex=""}
**TIP!**
:::

Write your tip here.
::::

TIP!

Write your tip here.


Formatting Tip:

Put <br> on the line after :::: to create a line between your callout and the next piece of content. If this line break is too big, try adding this instead <p style="font-size: 8px;"></p>, and change the font size to increase/decrease the line height.

This formatting is a div that is specified in Pandoc (recall: a library Bookdown uses to create our .html website pages). Bookdown will help colour your divs so that you hopefully won’t forget to include the proper amount of colons. This ends your div properly. If you stick to our callouts, you will need 4 colons at the end (::::).

Known Error:

If you do not end your div, all following code will not render (as if your book ends with the unfinished div)!

Warning about Callout Blocks

Our Callout blocks are written with white text. Hence, code does not appear well in our callout blocks, since it has a light white/grey background.

Creating your own callouts can be difficult, and you should account for making sure both the wesbite and pdf (which uses LaTeX, so you will likely have to edit preamble.tex) generate properly.

The R Markdown Cookbook provides more help on how to use custom div blocks to design your own callouts: https://bookdown.org/yihui/rmarkdown-cookbook/custom-blocks.html.

TIP: Markdown Not Working/Not Enough? Use HTML!

Recall from this diagram that all files are rendered into .html files for the final official website.

Both Knitr and Pandoc will ignore HTML code, so if a certain part of Markdown’s formatting isn’t working, or you’re not satisfied with Markdown’s formatting options, use HTML/CSS formatting instead!

Here are some examples:

  1. Markdown has no formatting options for underlining. Hence, underline text in a .Rmd file with the following HTML syntax:

    <u> underlined text</u>

    underlined text

  2. Bookdown currently renders to-do lists incorrectly. Instead, you can use the following HTML code:

    <div style="list-style-type: none;">
  <label><input type="checkbox"> check box</label><br>
</div>


References

Xie, Yihui. 2025. Bookdown: Authoring Books and Technical Documents with r Markdown. https://github.com/rstudio/bookdown.

  1. This is a footnote.↩︎