Tight Markdown Lists with Images

how-to
R Markdown
quarto
Author

Nathan Craig

Published

November 16, 2023

Modified

March 21, 2024

Abstract

This post looks at the outcome of various ways of formatting bulleted lists with inline images. These are issues one might consider when putting screen shots into documentation that is organized as a series of steps in an unordered or ordered markdown list.

Introductions

I use unordered (or bulleted) lists frequently, particularly in documentation or creating labs. Recently, I’ve been using Quarto to draft labs for a GIS class I’ll be teaching next semester There’s lots of bulleted lists and screen shots. I find getting screen shots in bulleted lists the way I want them is tricky. Lists can have “tight” or “loose” spacing. I like tight lists and prefer the images indented. This post explores list formatting. What works best is to have the screen shot as a sub-list item (Section 2.4). Provided one just uses RStudio’s source editor, it is even possible to get captions and figure numbers (Figure 2) to work in a tight list.

Markdown Lists

For all examples that follow, source is on the left output is on the right.

Tight list with no images

-   List item 1
-   List item 2
-   List item 3
    -   Sub-list item
    -   Another sub-list item
-   List item 4
  • List item 1
  • List item 2
  • List item 3
    • Sub-list item
    • Another sub-list item
  • List item 4

There is space after the sub-list. I don’t presently understand why but I can live with it.

Image inline no spaces

-   List item 1
-   List item 2
![](dog.png)
-   List item 3
    -   Sub-list item
    -   Another sub-list item
-   List item 4
  • List item 1
  • List item 2
  • List item 3
    • Sub-list item
    • Another sub-list item
  • List item 4

This gets interpreted and rendered as though it were written as

-   List item 1
-   List item 2 ![](dog.png)
-   List item 3
    -   Sub-list item
    -   Another sub-list item
-   List item 4

Image inline with four spaces

From SO, I got the idea of indenting the image four spaces. However, to do that one must put a space between the last list item and the image. Just as above, without the blank line it gets rendered as though it were written like the last example. Note that the sub-list is tight. This is because there are no extra lines between list items in this two item sub-list.

-   List item 1
-   List item 2
    ![](dog.png)
-   List item 3
    -   Sub-list item
    -   Another sub-list item
-   List item 4
  • List item 1
  • List item 2
  • List item 3
    • Sub-list item
    • Another sub-list item
  • List item 4

With at least one blank line the image is rendered in the list. However, the list is “loose” which I don’t care for.

-   List item 1
-   List item 2

    ![](dog.png)

-   List item 3
    -   Sub-list item
    -   Another sub-list item
-   List item 4

  • List item 1

  • List item 2

  • List item 3

    • Sub-list item
    • Another sub-list item

  • List item 4

Regardless of implementation, if you want “tight” lists, the only way to always get that is to never include any blank lines anywhere in your list items.

— @Waylan’s answer on SO

So it seems…

Image in a sub-list no caption or figure annotations

For now, my solution is to put the images into a sub-list item. I’m not enamored with having a bullet next to the image, but it might be a benefit if there was more than one screenshot needed.

-   List item 1
-   List item 2
    -   ![](dog.png)
-   List item 3
    -   Sub-list item
    -   Another sub-list item
-   List item 4
  • List item 1
  • List item 2
  • List item 3
    • Sub-list item
    • Another sub-list item
  • List item 4

Image in list with caption

I find that if I add a caption in source mode and render it the output works. If I toggle between source and visual mode, then RStudio reformats the line such that it renders a loose list. If I just put the image in with no figure label or caption it works fine toggling the view.

-   List item 1
-   List item 2
    -   ![Caption](dog.png)
-   List item 3
    -   Sub-list item
    -   Another sub-list item
-   List item 4
  • List item 1
  • List item 2

    • Caption
  • List item 3
    • Sub-list item
    • Another sub-list item
  • List item 4

It would be nicer to have the images aligned left, which is possible.

-   List item 1
-   List item 2
    -   ![Caption](dog.png){fig-align="left"}
-   List item 3
    -   Sub-list item
    -   Another sub-list item
-   List item 4
  • List item 1
  • List item 2

    • Caption
  • List item 3
    • Sub-list item
    • Another sub-list item
  • List item 4

We still have space where the sub-list starts which isn’t ideal, but workable.We still have space where the sub-list starts which isn’t ideal, but workable.

Note that after toggling to the visual editor it becomes this

-   List item 1
-   List item 2
    -   

        ![Caption](dog.png){fig-align="left"}
-   List item 3
    -   Sub-list item
    -   Another sub-list item
-   List item 4

Image in list with caption and figure number (Figure 2).

Figure 2 renders properly as long as I do not toggle to visual mode. If the file is toggled, then it breaks back to a loose list. I’m not sure why but think it is because of an additional linebreak.

-   List item 1
-   List item 2
    -   ![Caption](dog.png){#fig-dog}
-   List item 3
    -   Sub-list item
    -   Another sub-list item
-   List item 4
  • List item 1
  • List item 2
    • Figure 1: Caption
  • List item 3
    • Sub-list item
    • Another sub-list item
  • List item 4

Just as was the case with the caption, the image is centered and we can use the align argument to bring it left.

-   List item 1
-   List item 2
    -   ![Caption](dog.png){#fig-dog fig-align="left"}
-   List item 3
    -   Sub-list item
    -   Another sub-list item
-   List item 4
  • List item 1
  • List item 2
    • Figure 2: Caption
  • List item 3
    • Sub-list item
    • Another sub-list item
  • List item 4

After toggling to the visual editor it becomes this

-   List item 1
-   List item 2
    -   

        ![Caption](dog.png){#fig-dog fig-align="left"}
-   List item 3
    -   Sub-list item
    -   Another sub-list item
-   List item 4

Useul Resources

Citation

BibTeX citation:
@online{craig2023,
  author = {Craig, Nathan},
  title = {Tight {Markdown} {Lists} with {Images}},
  date = {2023-11-16},
  url = {https://ncraig.netlify.app/posts/2023-11-16-tight-markdown-lists-w-images/index.html},
  langid = {en},
  abstract = {This post looks at the outcome of various ways of
    formatting bulleted lists with inline images. These are issues one
    might consider when putting screen shots into documentation that is
    organized as a series of steps in an unordered or ordered markdown
    list.}
}
For attribution, please cite this work as:
Craig, Nathan. 2023. “Tight Markdown Lists with Images.” November 16, 2023. https://ncraig.netlify.app/posts/2023-11-16-tight-markdown-lists-w-images/index.html.