pandoc comments and notes for lecturer/ reader

When converting e.g. a Markdown file to a pdf file with pandoc for a lecture then everything except comments like

<!---
comment
-->

will be present in the output pdf file.

But is there an more elegant way of adding notes in the source Markdown file instead of using such comments? Maybe generate two output files:

  • one pdf file with the slides for the audience with less content and
  • one pdf file with annotations and notes for the lecturer/ reader with more content

Is there already a mechanism, tag, command etc. for that? Or are such comments the way to go?

Currently I am using the following setup on KUBUNTU 20 but I do not need to stick with it. All I need is a slides pdf in the end and a notes pdf file (or the slides with additional text):

dependencies:

  • Pandoc
  • XeTeX (with sudo apt install texlive-xetex)
  • latexmk (with sudo apt install latexmk)
  • mtheme globally installed with make install

project structure:

  • file slides.md written in Markdown with the presentation content, e.g.
---
author: Author
title: Presentation Title
date: \today
---

# first chapter

## sub title

<!---
a comment for `point 1` with additional information to
say but not to display for the listeners.
-->
- point 1

<!---
a comment for `point 2` with additional information to
say but not to display for the listeners.
-->
- point 2
  • a makefile with something like that:
default:
    @pandoc -t beamer -H settings.tex \
        --pdf-engine=xelatex --highlight-style=espresso \
        -V lang=en -V theme:metropolis \
        -o dist/output.pdf slides.md
  • and the settings.tex with:
%% Metro Settings
\metroset{numbering=fraction,
            progressbar=frametitle,
            background=dark,
            block=fill}

You can make use of beamer's note mechanism. If you add your notes using the macro \note{...}

---
author: Author
title: Presentation Title
date: \today
---

# first chapter

## sub title

\note{a comment for `point 1` with additional information to
say but not to display for the listeners}
- point 1


<!---
a comment for `point 2` with additional information to
say but not to display for the listeners.
-->
- point 2

then you can switch on/off the display of the notes in your settings.tex file:

%% Metro Settings
\metroset{numbering=fraction,
            progressbar=frametitle,
            background=dark,
            block=fill}


\setbeameroption{show notes on second screen}

enter image description here

If you were to intercept the intermediate .tex file and then manually run latexmk, you could even produce the two pdf files in a single go. Stick

\ifnotes
  \setbeameroption{show notes on second screen}
\fi

into your settings.tex file and then run

latexmk -pdf -interaction=nonstopmode -synctex=1 -jobname=filename -pretex="\newif\ifnotes \notesfalse" -usepretex filename 
latexmk -pdf -interaction=nonstopmode -synctex=1 -jobname=filename_notes -pretex="\newif\ifnotes \notestrue" -usepretex filename

(replace filename with the name of your file)