How to force image to text when converting markdown to pdf using pandoc

Question

I made a GitHub wiki - a manual to a software package - and I want to transform it into a beautiful pdf manual. However, I have some trouble with figures - many of them are put in one of the following pages, much after the place in the text where it should be, what turns the document very difficult to read.

To do so, I followed basically what was suggested here. Basically the idea is to:

1. Clone the GitHub wiki;

2. Convert the markdown files to a single pdf using pandoc:

   pandoc -s FirstSection.md FirstSection.md FirstSection.md -o manual.pdf

What happens is that I have a sequence of short sentences, each one followed by a figure (take a look here for example). When I open the resulting pdf, each figure is not right after the sentence that precedes it in the wiki, but rather I have a sequence of many sentences and a sequence figures in a row, but it makes the document really hard to follow.

Is there a way of forcing the images to be right after a piece of text where they are placed, and avoid having the text that comes after it before the image?

I have found some solutions for Rmarkdown, but they did not work for me.

Thanks in advance!

Answer 1

Pandoc uses LaTeX for PDF creation by default.

Using an external file

Put the following in e.g. header.tex:

\makeatletter
\def\fps@figure{h}
\makeatother

Or alternatively, the following:

\usepackage{float}
\let\origfigure\figure
\let\endorigfigure\endfigure
\renewenvironment{figure}[1][2] {
    \expandafter\origfigure\expandafter[H]
} {
    \endorigfigure
}

Then use:

pandoc input.md --include-in-header header.tex -o output.pdf

Using only a markdown file

Or instead of using a header.tex, you can also embed it in your markdown file's YAML metadata block:

---
header-includes: |
  \makeatletter
  \def\fps@figure{h}
  \makeatother
---

# my markdown header