Markdown for Beginners

Short Introduction

Markdown is a lightweight writing syntax. Instead of clicking formatting buttons, you type small symbols directly into plain text. Quarto builds on standard Markdown and adds publishing features that are especially helpful for technical and academic work.

Why This Matters For Researchers

Markdown is worth learning because it is:

  • fast to write
  • easy to read in raw form
  • suitable for version control
  • flexible across websites, reports, and manuscripts

Once you are comfortable with Markdown, most of Quarto opens up to you.

Core Syntax

Headings

# Main Title
## Section
### Subsection

Emphasis

*italic* and **bold**

Lists

- bullet item
- another bullet

1. first step
2. second step

Code

Wrap a short snippet in single backticks to format it as inline code within a sentence.

For longer code, use a fenced block: open with three backticks and a language name, then close with three backticks. The block displays the code with the right syntax highlighting, but does not run it:

```bash
quarto render
```

```python
print("Hello from Python")
```

```r
print("Hello from R")
```

Wrapping the language name in curly braces instead, such as {r}, turns the block into an executable chunk that Quarto runs when the document renders, placing the result in the output.

Quarto-Focused Additions

Quarto keeps standard Markdown, but it also makes room for:

  • callout blocks for notes, warnings, and tips
  • cross-references for sections, figures, and tables
  • executable code chunks
  • layout features for richer publishing
TipBeginner mindset

You do not need to memorize every Markdown feature at once. For most workshop tasks, headings, lists, links, emphasis, and fenced code blocks are enough to get started.

Concrete Academic Example

A methods note written in Quarto might use:

  • headings to separate data collection, cleaning, and analysis
  • bullet points for decisions and open questions
  • links to protocols or repositories
  • fenced code blocks to show commands used in the workflow

Mini Practice

Task

Write a short research note with:

  1. a title heading
  2. one short paragraph
  3. a list of three tasks
  4. a link to a project repository or journal website

If you are not sure how to create the file or render it, the Setup and rendering steps just below walk you through it.

Setup and rendering

  1. Create a file called practice.qmd.

  2. Give it this header:

    ---
title: "Markdown Practice"
format: html
---

  3. Write the task above in the body, underneath the header.

  4. Render the document by running this in your terminal:

    quarto render path/to/practice.qmd

    Replace path/to/practice.qmd with the real path to your file, including the filename. This step requires Quarto to be installed; see Installing Quarto if you have not set it up yet.

Next Step

Continue to YAML Headers to see how Quarto stores document settings at the top of a file.