5

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!

bniebuhr
  • 129
  • 1
  • 10

1 Answers1

11

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
mb21
  • 34,845
  • 8
  • 116
  • 142
  • Thanks, @mb21! It worked! I found such a solution before for Rmarkdown, as in the link you cited, but as I am a beginner using pandoc from command line I could not figure out how to run pandoc using this .tex file... thanks a lot! – bniebuhr Mar 07 '18 at 04:47
  • 1
    The YAML metadata syntax might have changed a bit. According to the docs and what worked for me it would have to be ``` --- header-includes: - | ` ```{=latex} \makeatletter \def\fps@figure{h} \makeatother ```` --- ``` – Jarno Dec 16 '18 at 20:05
  • The YAML metadata syntax might have changed a bit. According to the docs and what worked for me it would have to be --- header-includes: - | ```{=latex} \makeatletter \def\fps@figure{h} \makeatother \`\`\` --- – Jarno Dec 16 '18 at 20:13
  • 1
    @Jarno, that's simply using a [generic raw attribute](http://pandoc.org/MANUAL.html#generic-raw-attribute) inside the metadata field. Usually, it's not necessary. But if you have complicated LaTeX, it prevents pandoc from parsing it... – mb21 Dec 17 '18 at 10:53
  • maybe the issue is then just that is should be `header-includes`, instead of `header-include`? – Jarno Dec 17 '18 at 12:53
  • @Jarno, ah yes... typo... fixed! – mb21 Dec 17 '18 at 21:16
  • I tried the YAML metadata block in my markdown file but it did not work. Part of the text in the document jump to before the figures. (pandoc 2.5, with markdown generated from a Jupyter Notebook) – BND Mar 28 '19 at 17:20
  • However using a .tex file with `\usepackage{float} \let\origfigure\figure \let\endorigfigure\endfigure \renewenvironment{figure}[1][2] { \expandafter\origfigure\expandafter[H] } { \endorigfigure` in it worked. What is the meaning of the YAML header and what can we put in it to structure, format our document. – BND Mar 28 '19 at 17:47