Embed Github readme.md in Latex

Question

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.

Answer 1

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:

   \begin{markdown}
     \input{/path/to/GitHub/project/readme.md}
   \end{markdown}
   

4. Every time you compile the document, it should compile and embed the Markdown documents as well.

Answer 2

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:

-MyProjects
  -MardownsToPdfs.ps1 << see script bellow
  -ProjectDirA
    -ReadmeA.md
    -ImageA.png
  -ProjectDirB
    -ReadmeB.md
    -ImageB.png

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
\includepdf[pages=-]{MyProjects/ProjectDirA/ReadmeA.pdf}

Answer 3

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:

\documentclass{article}
% your packages here
\usepackage{markdown}

\begin{document}

% your content here

\appendix
\markdownInput{path/to/readme.md}

\end{document}

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).