Writing in Markdown

Your Week 4 briefing and your final report are Markdown files (.md). Markdown is plain text with a few symbols for formatting. GitHub displays it formatted, with your figures in place, and that is exactly what your reviewers and markers read.

Write it in any text editor (Notepad, Positron, VS Code). GitHub Desktop commits it like any other file. Open the file on github.com to see how it looks.

The ten things you need

You type You get
# Title A top-level heading (use once, for the title)
## Section A section heading
**bold** bold
*italic* italic
A blank line A new paragraph. A single line break does nothing.
- item A bulleted list
1. item A numbered list
[DUKES 2025](https://www.gov.uk/…) A link
`code` code, for file and function names
![Bioenergy rose tenfold.](figures/figure-trend.png) The image figures/figure-trend.png, with alt text

Folders and paths

Your repo is a folder on your computer, and folders can hold other folders. Your briefing sits in the repo’s top folder; your figures sit in a folder inside it called figures:

geol-skills-biomass-you/
├── briefing.md
├── data/
│   └── uk_electricity.csv
└── figures/
    ├── figure-trend.R
    └── figure-trend.png

A path says how to reach a file. There are two kinds:

  • An absolute path starts from the top of the drive: C:\Users\you\Documents\GitHub\geol-skills-biomass-you\figures\figure-trend.png. It works only on your computer.
  • A relative path starts from the folder you are in. From briefing.md, the figure is figures/figure-trend.png: go into figures, then take figure-trend.png. It works wherever the repo is copied: on github.com, on your reviewer’s computer, on your marker’s.

Always use relative paths, with forward slashes (/). Capitals count: Figures/Trend.png is a different file. Avoid spaces in file and folder names; use - instead.

To make a folder on github.com, type its name and a / in the file name box, as in figures/figure-trend.R. On your own computer, make it in File Explorer (Finder on a Mac), inside the repo folder.

Figures

Each figure is a PNG in figures/, made by an R script beside it with the same name: figures/figure-trend.R makes figures/figure-trend.png. The script holds everything needed to draw that one figure, from read.csv("data/uk_electricity.csv") to ggsave("figures/figure-trend.png", width = 6, height = 4, dpi = 150). Both paths are relative to the repo’s top folder, which is where R starts when you open the repo in Positron. In WebR, ggsave() saves only into the browser, so save the image by right-clicking the plot → Save image as…

![Line chart of UK bioenergy generation, 2000–2024, rising from
4 TWh to 40 TWh.](figures/figure-trend.png)

*Figure 1: Bioenergy generation grew almost tenfold in 25 years.
Source: DUKES 2025, Table 5.6B.*
  • The text in […] is alt text: what the figure shows, for anyone who can’t see it. Describe the content, not “a graph”.
  • The caption goes on the next paragraph, in italics, and says what to take from the figure.
  • The path in (…) must match exactly, including capitals and the figures/ folder.

Common problems

  • The image shows as a broken link. The file name or folder in (…) doesn’t match the PNG in your repo, or the PNG isn’t committed.
  • Two paragraphs ran together. Put a blank line between them.
  • A list didn’t appear. Put a blank line before the first -.
  • Stray * or _ characters. An unmatched * starts italics. Write \* for a literal asterisk.

Word count

GitHub doesn’t count words. Paste your text into any word counter; the Markdown symbols barely change the total.