Md Format

Markdown Formatting

Overview

All three document types — .md, .rmd, and .qmd — are processed by pandoc before final rendering. Pandoc applies strict rules about blank lines that determine whether content renders as a list or collapses into inline text. The same rules apply regardless of whether the output is a Hugo blog post, a Quarto HTML document, or a plain markdown file.

Golden rule: pandoc needs a blank line before the first list item to recognise it as a list.

Rule 1: Blank line before list items

A bullet list must be preceded by a blank line. Without it, pandoc treats the - or * markers as part of the preceding paragraph and collapses all items into a single horizontal line.

Trigger contexts

This failure is most likely to occur after:

Correct vs incorrect

Wrong — no blank line, items collapse horizontally:

**Monocle3 (R)** 🧭
- Handles branching trajectories well
- Integrates with Seurat via SeuratWrappers
- Best for: General-purpose trajectory analysis in R

Renders as:

Monocle3 (R) 🧭 - Handles branching trajectories well - Integrates with Seurat via SeuratWrappers - Best for: General-purpose trajectory analysis in R

Correct — blank line inserted, items render vertically:

**Monocle3 (R)** 🧭

- Handles branching trajectories well
- Integrates with Seurat via SeuratWrappers
- Best for: General-purpose trajectory analysis in R

More examples

Wrong:

If you don't know where to start:
- RNA velocity can suggest directionality
- Multiple root selections can test robustness

Correct:

If you don't know where to start:

- RNA velocity can suggest directionality
- Multiple root selections can test robustness

Wrong:

*Solutions:*
- Adjust `learn_graph()` parameters
- Check cell density in putative branch regions

Correct:

*Solutions:*

- Adjust `learn_graph()` parameters
- Check cell density in putative branch regions

Applies to all three file types

The blank line requirement is a pandoc rule, not a Hugo or Quarto rule. It applies everywhere pandoc is in the rendering chain.

Rule 2: Avoid em dashes

Use em dashes (—) sparingly. They are easy to overuse and usually have a cleaner alternative.

In bullet points: bold + colon, not em dash

When a bullet point has a title and a description, bold the title and follow it with a colon.

Wrong:

- RNA velocity — uses splicing ratios to infer transcriptional direction
- Monocle3 — handles branching trajectories well

Correct:

- **RNA velocity:** uses splicing ratios to infer transcriptional direction
- **Monocle3:** handles branching trajectories well

In prose: rewrite rather than reach for an em dash

Em dashes in prose often signal a sentence that should be restructured. Prefer commas, parentheses, colons, or splitting into two sentences.

Wrong:

The model converged quickly — likely because the learning rate was well-tuned.
This step is critical — without it, downstream clustering will fail.

Correct:

The model converged quickly, likely because the learning rate was well-tuned.
This step is critical: without it, downstream clustering will fail.

Only use an em dash when no other punctuation fits and the interruption is intentional.

Verification before rendering

Before rendering any document, grep for list items that immediately follow non-blank lines:

# Flag lines where a list item (-) is preceded by a non-blank line
grep -n "^[-\*] " file.rmd | cut -d: -f1 | while read n; do
  prev=$((n - 1))
  prevline=$(sed -n "${prev}p" file.rmd)
  if [ -n "$prevline" ] && [[ "$prevline" != "---" ]]; then
    echo "Line $n may be missing a blank line above it: $prevline"
  fi
done

Or use a quick visual scan with context:

grep -n -B1 "^[-\*] " file.rmd

Any result where the -B1 line is non-blank (and not another list item) is a candidate for a missing blank line.

Common Mistakes