R Markdown Bullet Points: Fix Lists That Break on Knit

November 11, 2026 · 10 min read

R Markdown Bullet Points: Why Lists Break When You Knit

R Markdown bullet points start with -, * or + and a space, and they need a blank line above them. When a list looks right in your .Rmd file but knits as one run-on paragraph, that missing blank line is almost always the cause. Nested items must also line up under the parent item's text.

Knit-Safe R Markdown Bullet Points in One Example

When you knit, knitr runs your chunks and writes a plain .md file, then Pandoc converts it to HTML, PDF or Word. Our R Markdown explainer walks through that pipeline. What matters here is that Pandoc's Markdown is stricter than the CommonMark rules most previews and GitHub follow.

This pattern knits the same way in every output format:

Model results for `mtcars`:

- Intercept is 37.3
- Each extra 1,000 lb cuts mpg by 5.3
    - p-value is below 0.001
- R squared is 0.75

Pandoc renders a paragraph, then a three-item bullet list with one nested item under the second bullet. Three habits make it work: a blank line before the list, one marker character per list, and nested lines indented under the parent's text. For the general syntax of ordered, unordered and task lists, see our Markdown lists guide.

Why Are My Bullet Points Not Showing When I Knit?

Pandoc won't start a list directly after a line of paragraph text. Without a blank line, the dashes become ordinary characters and the whole block knits as one paragraph:

Model results:
- Intercept is 37.3
- R squared is 0.75

Pandoc 3.8 turns that into a single paragraph: "Model results: - Intercept is 37.3 - R squared is 0.75". Add an empty line after "Model results:" and you get a real list. A heading directly above a list is fine, because a heading isn't a paragraph.

The same rule bites at the other end. A paragraph typed on the line right after the last item gets glued onto that item as extra text. Leave a blank line after the list too.

Pandoc has an extension for this, lists_without_preceding_blankline, but it's off in Pandoc's default Markdown, and R Markdown doesn't turn it on. You could switch it on with md_extensions: +lists_without_preceding_blankline under your output format. We prefer the blank line, because the file then knits identically on any machine and in any format.

The ambiguity also runs the other way. The R Markdown book's own example is a sentence split across two lines, where the second line starts with - 3 is 2. Pandoc keeps it as text. CommonMark tools, GitHub included, turn that second line into a bullet. Escape it as \- or keep the sentence on one line.

Here's the knit-safe version in a live editor. One caveat: our preview uses CommonMark and GitHub Flavored Markdown, where a list can follow a paragraph line directly. Delete the blank line above a list and the preview still shows a list, even though Pandoc wouldn't.

Knit-safe bullets

Model results:

  • Intercept is 37.3
  • Weight lowers mpg by 5.3 per 1,000 lb
  • R squared is 0.75

Steps in the report:

  1. Load the mtcars data
  2. Fit the regression
  3. Knit to HTML

A paragraph after the list, separated by a blank line.

50 words258 characters15 lines
Markdown

How Far Do You Indent a Nested Bullet in R Markdown?

Pandoc's rule is precise: a nested list must line up with the first character of text after the parent's marker. That means two spaces under - , three spaces under 1. and four under 10. . Indent less and the line becomes a sibling item. Indent too far (six spaces under - ) and Pandoc folds it into the parent item's text.

Ordered parents catch most people out:

1. Fit the model
  - two spaces: Pandoc ends the numbered list
2. Check residuals
   - three spaces: nested under item 2

The two-space line breaks the list into three pieces: a one-item numbered list, a separate bullet, and a second numbered list that restarts at 2. Only the three-space line nests correctly.

You'll often see four-space indentation in examples, including on RStudio's Markdown Basics page. That habit matches older Pandoc, which needed four spaces for list continuation (the manual keeps that behaviour as the opt-in four_space_rule extension). Four spaces still nests correctly under - and 1. , so it's a safe habit. In our tests a tab nested correctly too. For paragraphs and code blocks inside list items, see our guide to indenting lists and code.

Generating Bullet Points in R Markdown from Code

Chunk output normally lands in a verbatim code block. The chunk option results = 'asis' tells knitr to write cat() output as raw Markdown, which is how you build bullet points in R Markdown from data:

Variables in the data:

```{r, echo=FALSE, results='asis'}
cat(paste0("- `", names(mtcars)[1:3], "`"), sep = "\n")
```

That knits as a three-item list: mpg, cyl and disp. The sep = "\n" matters. Without it, cat() joins the items with spaces and you get one bullet reading "mpg - cyl - disp".

The blank-line rule applies to generated text as well. This chunk writes a label and two items with only single newlines between them, so Pandoc sees one paragraph:

cat("Summary of mpg:\n")
cat("- mean", round(mean(mtcars$mpg), 1), "\n")
cat("- max", max(mtcars$mpg), "\n")

Change the first line to cat("Summary of mpg:\n\n") and the list appears. The R Markdown Cookbook suggests adding empty lines with cat('\n') to remove exactly this kind of ambiguity. If your values live in a spreadsheet column instead, the Markdown list generator turns pasted lines into a bulleted list you can drop into the .Rmd.

How Knitted Bullets Look in HTML, PDF and Word

The same .Rmd list gets different bullet glyphs in each format, and each format changes them in a different place.

OutputDefault bullets, levels 1 to 3Where to change them
html_documentBrowser defaults: disc, circle, squareCSS list-style-type
pdf_documentBullet, bold en dash, asterisk (LaTeX itemize)\labelitemi to \labelitemiv in the preamble
word_documentBullet, letter o, small square (Pandoc's own list definitions)In Word, after knitting

For HTML, a css chunk with echo=FALSE puts the rules straight into the page:

```{css, echo=FALSE}
ul { list-style-type: square; }
ul ul { list-style-type: circle; }
```

Our bullet point HTML guide lists more marker styles and ways to draw custom bullets.

Spacing is a separate issue. A blank line between items makes Pandoc treat the list as loose and wrap each item in a paragraph, so every format shows bigger gaps. Remove those blank lines to get a tight list.

How Do I Change the Bullet Style in an R Markdown PDF?

PDF bullets come from LaTeX's itemize environment, which uses \labelitemi for the first level through \labelitemiv for the fourth. The LaTeX2e reference documents the defaults and shows \renewcommand as the way to change them. Put the commands in a preamble file:

\renewcommand{\labelitemi}{$\diamond$}
\renewcommand{\labelitemii}{\textendash}

Then load it from the YAML header:

output:
  pdf_document:
    includes:
      in_header: preamble.tex

You can paste the same two lines under header-includes: instead. The Cookbook points out that header-includes is unconditional and also lands in non-LaTeX output, while includes applies only to the PDF. We prefer the separate preamble.tex for any report you also knit to HTML or Word. We tested these commands with Pandoc 3.8 and pdflatex, and they produced diamond and dash bullets. If the knit stops with a LaTeX error instead, our guide to knitting R Markdown to PDF covers the fixes.

Word Output: What reference_docx Can and Can't Change

The reference_docx option under word_document points Pandoc at a template whose styles Pandoc copies into your output. Tight lists use the Compact paragraph style, so editing Compact in the template changes the font, size and spacing of your list text. Loose lists don't use Compact, which is why they look more spread out.

The bullet glyph is the limitation. Pandoc writes its own list numbering definitions, and none of the styles the Pandoc manual says it uses is a list style. In our Pandoc 3.8 test, the levels came out as a Symbol bullet, a Courier New "o" and a Wingdings square. To change them, knit first, then select the list in Word and use Define New Bullet from the Bullets menu.

Incremental Bullet Points in ioslides, Slidy, Beamer and xaringan

Slides add one more question: should bullets appear all at once or one at a time? For ioslides, Slidy and Beamer, set the option on the output format:

output:
  ioslides_presentation:
    incremental: true

To reveal only some lists one item at a time, leave the option off. The R Markdown book suggests putting those lists in a blockquote instead:

> - Eat eggs
> - Drink coffee

Pandoc also supports ::: incremental and ::: nonincremental fenced divs around a list, and calls them the recommended per-list method. We confirmed they work with Pandoc's Beamer and Slidy writers. xaringan works differently: put -- on its own line between bullets and each piece appears when you advance the slide.

Most broken R Markdown bullet points come down to two Pandoc rules: a blank line before and after the list, and nested items lined up under the parent's text. Get those right and the per-format tweaks (CSS, a LaTeX preamble, a Word template or incremental slides) are short. To draft and check list text before pasting it into an .Rmd, open the editor, keeping in mind that its preview is more forgiving than Pandoc.