7

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.... – David Carlisle Feb 13 '16 at 17:36
  • 1
8

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.
  • 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 Feb 13 '16 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 Feb 16 '16 at 12:12
  • 1
    @ArcturusB: Thanks, that helped. And I also found --listings option for code-blocks :) – nik Feb 16 '16 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 – CodingYourLife Jan 21 '17 at 23:44
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}

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.