Week 2 exercises:
Markdown and project organization

Author
Affiliations

Jelmer Poelstra

CFAES Bioinformatics Core, Ohio State University

Dept. of Plant Pathology, Ohio State University

Week starts on

August 31, 2026

Page last modified

October 17, 2026

Introduction

In these exercises, you’ll practice mostly with writing Markdown and organizing and documenting a research project.

You’ll write a separate file for each exercise, which should all go in a folder week02/exercises inside your personal dir at /fs/ess/PAS3493/people/<user>.

Solutions for most questions are at the bottom of this page — but do give each question a genuine try before looking!

Setting up

Start a VS Code (Code Server) session at OSC OnDemand, as we did in class and as described in the VS Code lecture. Make sure the Working Directory is your personal dir, /fs/ess/PAS3493/people/<user>.

Exercise 1: Fixing a broken Markdown file

In this exercise, you’ll fix a Markdown file that has several problems in it.

  1. In the VS Code file explorer, you should see the week02 and week03 folders you created in class. Hover your mouse over the week02 folder: a couple of small icons will appear to the right of the folder name. Click the “New Folder…” icon (the one that looks like a folder with a +) and create a folder called exercises.

  2. Now hover over your new exercises folder and click the “New File…” icon to create a file called 1_fixing-markdown.md. Because you created it directly in the file explorer, you don’t have to save it in the right place afterwards.

  3. Copy-paste the text below into 1_fixing-markdown.md (hover over the top-right of the box for a copy button).

#Week 2 notes
These are my notes for week 2.
- Project organization
-Markdown
- VS Code

I started a VS Code session at OSC.
Then I opened a Markdown file.

The guide is (Markdown Guide)[https://www.markdownguide.org].

I saved my file as `notes.md and then previewed it.

This week was **really* useful.
## Things to try next week
bash
date

| topic      | when   |
| Markdown   | week 2 |
| Unix shell | week 3 |

  1. Open the preview to the side and compare it with the source.

  2. The Markdown below has nine or ten problems in it. Some of them are invisible in the source but obvious in the preview, and some are the other way around. Fix the problems one at a time, checking the preview after each fix.

  • Two problems with characters that need a space after them.
  • Two problems with missing blank lines between elements.
  • One problem with two sentences that should be on separate lines.
  • One problem with the order of the parts of a link.
  • One problem with inline code formatting.
  • One problem with the characters used for bold text.
  • One code block that lost its backticks.
  • One problem with the table at the bottom of the file (see Markdown self-study slides).

Exercise 2: Writing a Markdown document

In this exercise, you’ll build a Markdown document from scratch. The idea is to practice the syntax, so don’t spend a lot of time thinking about the content.

  1. Create a file 2_writing-markdown.md in your week02/exercises folder.

  2. Open a preview of the Markdown document to the side. Keep an eye on the preview after every step below.

  3. On the first line, add a level-1 header with the document’s title: Markdown practice.

  4. Add a level-2 header Course tools, and below it a paragraph of two sentences about the tools you’ve used so far in this course.

  5. Below that paragraph, add a bulleted list with three tools. For each item, put the name of the tool in bold, followed by a dash and a few words about what it’s used for.

  6. Add a level-2 header Starting a VS Code session at OSC, and below it a numbered list of steps to start a VS Code session.

  7. Add a level-2 header Useful links with a bulleted list of three links to the OSC websites we discussed (links can show or hide the URL — as you wish).

  8. Add a level-2 header A quote, and below it a blockquote with one sentence that you found interesting from this week’s reading (Markowetz 2015). Below the blockquote, in a regular paragraph, say where the quote is from.

  9. Add a level-2 header Code, and below it:

    • A sentence that mentions the file name README.md, formatted as inline code.

    • A code block with bash syntax highlighting containing these two lines:

      # Print the current date and time
date

  10. Add a horizontal rule, followed by a level-2 header To do and a bulleted list of two things you want to practice more.

  11. In the OnDemand file browser, use the Upload button to upload an image from your own computer into your week02/exercises folder. Then embed it in 2_writing-markdown.md, and check that it shows up in the preview.

  12. Browse the Markdown Guide’s cheat sheet, find one syntax element that we didn’t cover in class, and try it out in your document.

Exercise 3: File names

Create a file 3_file-names.md in your week02/exercises folder. For each of the file names below, write in your file:

  • The original name (as inline code)
  • A better name (as inline code)
  • One line about what was wrong with the original
  1. sample2_R1.fastq — from a folder that also contains sample10_R1.fastq and will eventually hold files for 40 samples
  2. RNAseq counts FINAL.csv
  3. plot1.png — for a plot showing a Principal Component Analysis of all samples
  4. 2019_3_7_field_notes.txt

Exercise 4: A project folder

In this exercise, you’ll build the skeleton of a research project folder, with placeholder files and a README.md. Start by picking one of the two project options below.

Use a research project of your own; either one you are working on now, or one you expect to start soon.

Only pick this option if you can name about ten files that the project has or will have, and can say several things about its data: where it came from, when, and from whom.

Since this is just for practice, it’s fine if you make up some placeholder/dummy file names and details, but if you feel like you’d have to make up too much, use Option B instead.

You are studying how drought stress affects gene expression in maize (Zea mays).

You grew 24 plants (12 well-watered “control” plants and 12 drought-treated plants) and harvested leaf tissue from each plant. The CFAES Molecular Biology and Genomics Core prepared and sequenced the RNA-seq libraries, and you downloaded the raw sequence data from them on May 1, 2026. The next day, you downloaded the maize reference genome (assembly GCF_902167145.1) from NCBI.

These are the files you have so far:

  • SampleSheet Final.xlsx — the spreadsheet from the sequencing facility with sample IDs, treatments, and harvest dates
  • ctrl01_R1.fastq.gz and ctrl01_R2.fastq.gz — raw reads for control plant 1
  • drought10_R1.fastq.gz and drought10_R2.fastq.gz — raw reads for drought-treated plant 10
  • GCF_902167145.1_genomic.fna — the reference genome you downloaded
  • 01_align-reads.sh — a script that aligns the reads to the reference genome
  • counts.csv — the gene count table produced by that script
  • 02_plot-counts.R — a script that makes figures from the count table
  • Fig 1 FINAL v3.png — a PCA plot of all samples, made by that script
  • diary.md — your lab notebook, with an entry for each day you worked on the project

Final notes:

  • You also have the reads for the other 22 plants, but there is no need to list all of those.
  • _Most of these names are already fine: only two of them need to be changed.

Now, whichever project you picked:

  1. Within your week02/exercises folder, create a folder for the project.

  2. Inside it, create the top-level subfolders you would use. For example, data, scripts, results, and doc, but you’re free to use a different (consistent!) set of names.

  3. Add any subfolders you need, such as data/raw and data/meta.

  4. Create an empty placeholder file for each of the project’s files, in the folder where it belongs and with a name that follows the file naming rules:

    • Option A — use about ten files that your project has or will have.
    • Option B — use the file list above, fixing the two file names that don’t follow the rules.

  5. In the top level of your project folder, create a README.md with:

    • A level-1 header with the project name
    • A paragraph describing what the project is about
    • A level-2 section Folder structure with a list of your folders, each with a few words about what goes in it. Format the folder names as inline code.
    • A level-2 section Data describing where the data came from, when, and from whom
    • A level-2 section Contact with your name and your email address as a clickable link

  6. In your doc folder, open (or create) the lab notebook file diary.md, and add one entry: a level-2 header with a date, followed by a couple of sentences about what you did that day.

    • Option A — use today’s date and describe this exercise.
    • Option B — use 2026-05-03, the day you ran the alignment script.

  7. Check both Markdown files in the preview and fix any formatting problems.

Solutions

Exercise 1

The ten problems, and the fixed file.

The problems were:

  1. No space after the # of the title, so it isn’t a header.
  2. No blank line between the paragraph and the list below it. VS Code’s preview is forgiving and still shows a list here, but stricter renderers (including Quarto’s, which you’ll use from week 12) will not — so always leave the blank line.
  3. No space after the - of the second list item, so it isn’t a list item and is added to the previous one instead, one the same line.
  4. The link has its two parts reversed: the [link text] comes first, and then the (URL).
  5. The inline code for notes.md has an opening backtick but no closing one, so it doesn’t show up as inline code in the preview.
  6. **really* has two asterisks on one side and only one on the other. Only one asterisk on each side is used, so you get italic instead of bold, with a leftover (literal) * in the output.
  7. No blank line before the ## Things to try next week header. Again, VS Code’s preview accepts this, but not every renderer will.
  8. The bash/date code block lost its triple backticks, so it shows up as regular text and as a single line. Note: Within a code block, you do not need blank lines to avoid merging lines together! Since there are no “paragraphs” in a code block, the renderer will not merge lines together.
  9. The table is missing the row of dashes below the header row, so it isn’t rendered as a table, and once again is collapsed into a single line.

Finally, the two sentences “I started a VS Code session at OSC.” and “Then I opened a Markdown file.” are on separate lines in the source but end up in one line in the output: a single line break is ignored. While notable, this isn’t necessarily a problem, and you may in fact deliberately write Markdown with short lines like this, so that the source is easier to read. But in the solution below, we assumed that the two sentences were meant to be two paragraphs, and we added a blank line between them.

And here is the fixed file:

# Week 2 notes

These are my notes for week 2.

- Project organization
- Markdown
- VS Code

I started a VS Code session at OSC.

Then I opened a Markdown file.

The guide is [Markdown Guide](https://www.markdownguide.org).

I saved my file as `notes.md` and then previewed it.

This week was **really** useful.

## Things to try next week

```bash
date
```

| topic      | when   |
| ---------- | ------ |
| Markdown   | week 2 |
| Unix shell | week 3 |

Exercise 2

An example of what your document could look like. 
# Markdown practice

## Course tools

So far in this course, I have used a few tools that are new to me.
All of them run at OSC, so I access them through my browser.

- **OnDemand** - the web portal I use to log in to OSC
- **VS Code** - the editor I write my files in
- **Markdown** - the language I use to write documentation

## Starting a VS Code session at OSC

1. Log in at the OnDemand website.
1. Select `Code Server` in the Interactive Apps menu.
1. Fill out the form and click Launch.
1. Click the "Connect to VS Code" button.

## Useful links

- [OnDemand](https://ondemand.osc.edu) - where I start VS Code sessions
- [My OSC](https://my.osc.edu) - account and project management
- <https://osc.edu>

## A quote

> This experience showed me two things.
> First of all, a project is more than a beautiful result.
> You need to record in detail how you got there.
> And second, starting to work reproducibly early on will save you time later.

This is from the "Reason number 1" section in Markowetz (2015).

## Code

Every project folder should have a `README.md` file in its top level.

```bash
# Print the current date and time
date
```

---

## To do

- Practice Markdown tables
  - Practice links to images

I indented the second item by two spaces,
and it became a nested (indented) sub-item of the first one.

Two things to note:

  • Step 12 (embedding an uploaded image) is not shown here, since the image file itself isn’t something we can include in this solution — but the syntax is ![](image-file-name.png), assuming the image file is in the same folder as your Markdown file.
  • In the numbered list, every item is 1. in the source, but the preview numbers them 1, 2, 3, 4.

Exercise 3

Better file names.

Several other answers are possible — what matters is that your names are machine-readable, human-readable, and sort correctly.

  1. sample2_R1.fastq → sample02_R1.fastq
    Without a leading zero, sample10 sorts before sample2. With 40 samples, two digits are enough.

  2. RNAseq counts FINAL.csv → rnaseq-counts.csv
    The spaces are not machine-readable, and capitals are best avoided too. While there is some nuance here, you should generally also avoid qualifiers like “FINAL” (would the next version be “FINAL2”?). Instead, be more specific and/or use version control (week 5 of this course).

  3. plot1.png → pca_all-samples.png
    The original is machine-readable but not human-readable: it says nothing about what the figure shows.

  4. 2019_3_7_field_notes.txt → field-notes_2019-03-07.txt
    The date needs leading zeros and hyphens to sort correctly, and underscores are better reserved for separating units (here: the date from the description).

Exercise 4

These solutions use the fictional project of Option B — but the same reasoning applies to your own project.

A) The project folder, with all files in place. 
maize-drought/
|-- README.md
|-- data/
|   |-- meta/
|   |   |-- samples.tsv
|   |-- raw/
|   |   |-- ctrl01_R1.fastq.gz
|   |   |-- ctrl01_R2.fastq.gz
|   |   |-- drought10_R1.fastq.gz
|   |   |-- drought10_R2.fastq.gz
|   |-- ref/
|   |   |-- GCF_902167145.1_genomic.fna
|-- doc/
|   |-- diary.md
|-- results/
|   |-- counts/
|   |   |-- counts.csv
|   |-- figures/
|   |   |-- pca_all-samples.png
|-- scripts/
|   |-- 01_align-reads.sh
|   |-- 02_plot-counts.R

Some things to note about where the files go:

  • The sample sheet is a form of data so it belongs in data rather than in doc. In omics projects where the omics data is the main source of data, we often consider such sample information “metadata”, so it can go in data/meta.
  • counts.csv is produced by one of your scripts, which makes it a result, even though the next script uses it as input.
  • The reference genome is data that you downloaded rather than generated, so it goes in data too. But in its own subfolder, since it is not data about your samples.
  • The lab notebook is documentation, so diary.md goes in doc.

And about the two files that had to be renamed:

  • SampleSheet Final.xlsx → samples.tsv
    The spaces and capitals make it hard to work with, “Final” says nothing about the content, and the file should be converted from Excel to a plain-text format.
  • Fig 1 FINAL v3.png → pca_all-samples.png
    Again spaces and capitals, and the name says nothing about what the figure shows. Keeping track of versions in the file name is what version control is for (week 5).

The other names were already fine. Note that the scripts are numbered, which shows the order in which they should be run, and that the sample numbers have a leading zero (ctrl01 rather than ctrl1) so that they will sort correctly.

B) An example README.md file. 
# Maize drought RNA-seq

An RNA-seq experiment to test how drought stress affects gene expression in
maize (_Zea mays_).
Leaf tissue was harvested from 24 plants:
12 well-watered controls and 12 drought-treated plants.

## Folder structure

- `data/raw` - raw FASTQ files as received from the sequencing facility
- `data/meta` - metadata about the samples
- `data/ref` - the maize reference genome
- `scripts` - all scripts, numbered in the order in which they are run
- `results` - output of the scripts: count tables and figures
- `doc` - project documentation, including the lab notebook `diary.md`

## Data

- The raw RNA-seq reads were produced by the CFAES Molecular Biology and
  Genomics Core and downloaded on 2026-05-01.
  Their sample sheet is in `data/meta/samples.tsv`,
  converted from the original Excel file.
- The maize reference genome (assembly `GCF_902167145.1`)
  was downloaded from NCBI on 2026-05-02.

## Contact

Jane Doe - [doe.1234@osu.edu](mailto:doe.1234@osu.edu)
C) An example diary.md entry. 
# Lab notebook

## 2026-05-03

Aligned the reads of all 24 samples to the maize reference genome with
`scripts/01_align-reads.sh`, and made a gene count table.
Two of the control samples had a much lower alignment rate than the rest --
check the FastQC reports for those next.
Back to top

References

Markowetz, Florian. 2015. “Five Selfish Reasons to Work Reproducibly.” Genome Biology 16 (1): 1–4. https://doi.org/10.1186/s13059-015-0850-7.