During my thesis I have created multiple Git-Repositories which are documented using the readme.md which GitHub uses as repository explanation. Now I would like to include those documentations into the appendix of my thesis. What is the best way to do so?

I would prefer a solution which just links the readme.md files, so that changes get included automatically.

  • doing a full on the fly parsing of full markdown is probably a bit hard but there are several markdown to latex convertors if you don't mind having that conversion step, On the other hand most readmes just have simple headings and some font changes and stuff which you could do in latex macros quite easily, so it all depends.... Commented Feb 13, 2016 at 17:36
  • 1
    Related: tex.stackexchange.com/questions/101717/… Commented Feb 13, 2016 at 18:00

3 Answers 3


This can best be done using a Markdown-to-LaTeX-Compiler and a Makefile to build the project. Here's an example rundown of how you could proceed:

  1. Install pandoc
  2. Create a Makefile or equivalent (Batch file, script, ...) with the following content, repeating the first line for every project readme you wish to include:

    pandoc /path/to/GitHub/project/readme.md -f markdown -t latex -s -o /path/to/GitHub/project/readme.tex
    pdflatex <arguments> file.tex
  3. Add \include{/path/to/GitHub/project/readme} statements in your LaTeX document where applicable.

  4. Use the Makefile to build your project. It's not strictly necessary to do this after each change in the LaTeX document, only after changing/adding a GitHub project readme.

Alternatively, you could follow this answer and use pandoc in LaTeX on-the-fly. I consider this a less elegant solution, but nonetheless here's a quick rundown on how you would use this to accomplish what you want:

  1. Install pandoc
  2. Copy the preamble from the example document in the linked answer
  3. To embed Markdown files, embed them in your document like this:

  4. Every time you compile the document, it should compile and embed the Markdown documents as well.
  • Tried the first version, and it works great. However I needed to include \usepackage{standalone} to be able to import the rendered tex-files.
    – nik
    Commented Feb 13, 2016 at 20:41
  • 2
    @nik, removing the -s option from the pandoc build line allows you to drop the standalone package in LaTeX. But: you might have to manually add some \clearpage around your include statement; some of the LaTeX commands written by pandoc might not compile.
    – Arcturus B
    Commented Feb 16, 2016 at 12:12
  • 1
    @ArcturusB: Thanks, that helped. And I also found --listings option for code-blocks :)
    – nik
    Commented Feb 16, 2016 at 18:35
  • Graphics in subdirectories do not work if you don't change graphicspath. Maybe you could add this to your answer: tex.stackexchange.com/a/139403/123523 Commented Jan 21, 2017 at 23:44

My answer is based on what @Big-Blue suggested with some powershell automation. I guess you have a folder where all your repos are in like a Projects folder.

Example Folder Structure:

  -MardownsToPdfs.ps1 << see script bellow

MardownsToPdfs.ps1 file content:

$currendDir=(Get-Item -Path ".\" -Verbose).FullName

#repeat for every *.md file
childitem ../ -include *.md -recurse | foreach ($_) { 
    $mdPath = $_.FullName
    $pdfPath = $_.FullName.Replace(".md", ".pdf")
    $pdfFileName = $_.Name.Replace(".md", ".pdf")

    cd $_.directory
    pandoc --wrap=preserve -f markdown+hard_line_breaks -s -V geometry:margin=1in -o $pdfPath $mdPath
    cd $currendDir

Right click Run With Powershell on *.ps1 file and it will create a PDF next to each *.md file with the same name.

You can include PDF files in your *.tex file like this:

%In your latex *.tex file you can embed

I actually wanted to do the very same thing, that is, to include the readme.md file in the Appendix.

I found the markdown package to be very useful. Indeed, it has a modified input command, to include external .md files, that you can import as they are. It is \markdownInput{path/to/readme.md}.

I did the following:

% your packages here


% your content here



Be aware that:

  • The first sectioning level of markdown (a single #) corresponds to \chapter, and so on (## corresponds to \section, ...). Therefore you might want to adjust the sectioning level using the shiftHeadings option.
  • You have to build your document with shell escape enabled (that is pdflatex --shell-escape).

You must log in to answer this question.

Not the answer you're looking for? Browse other questions tagged .