Betten Sie Github readme.md in Latex ein

Question

Während meiner Diplomarbeit habe ich mehrere Git-Repositories erstellt, die mit demreadme.md, das GitHub als Repository-Erklärung verwendet. Nun möchte ich diese Dokumentationen in den Anhang meiner Arbeit aufnehmen. Wie gehe ich dabei am besten vor?

Mir wäre eine Lösung lieber, bei der die readme.mdDateien nur verknüpft werden, so dass Änderungen automatisch übernommen werden.

Answer 1

Dies lässt sich am besten mit einem Markdown-zu-LaTeX-Compiler und einem Makefile zum Erstellen des Projekts erreichen. Hier ist ein Beispiel, wie Sie vorgehen könnten:

1. Installieren Sie Pandoc

2. Erstellen Sie ein Makefile oder eine gleichwertige Datei (Batch-Datei, Skript usw.) mit dem folgenden Inhalt und wiederholen Sie die erste Zeile für jede Projekt-Readme-Datei, die Sie einbinden möchten:

   pandoc /path/to/GitHub/project/readme.md -f markdown -t latex -s -o /path/to/GitHub/project/readme.tex
   pdflatex <arguments> file.tex
   

3. Fügen Sie \include{/path/to/GitHub/project/readme}bei Bedarf Anweisungen in Ihr LaTeX-Dokument ein.

4. Verwenden Sie das Makefile, um Ihr Projekt zu erstellen. Dies ist nicht unbedingt nach jeder Änderung im LaTeX-Dokument erforderlich, sondern nur nach dem Ändern/Hinzufügen einer GitHub-Projekt-Readme.

---

Alternativ können Sie folgendiese Antwortund verwenden Sie pandoc spontan in LaTeX. Ich halte das für eine weniger elegante Lösung, aber hier ist trotzdem ein kurzer Überblick darüber, wie Sie damit das erreichen, was Sie wollen:

1. Installieren Sie Pandoc
2. Kopieren Sie die Präambel aus dem Beispieldokument in der verlinkten Antwort

3. Um Markdown-Dateien einzubetten, betten Sie sie wie folgt in Ihr Dokument ein:

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

4. Jedes Mal, wenn Sie das Dokument kompilieren, sollten auch die Markdown-Dokumente kompiliert und eingebettet werden.

Answer 2

Meine Antwort basiert auf dem, was @Big-Blue mit etwas Powershell-Automatisierung vorgeschlagen hat. Ich vermute, Sie haben einen Ordner, in dem sich alle Ihre Repos befinden, wie ein Projektordner.

Beispiel einer Ordnerstruktur:

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

Inhalt der Datei MardownsToPdfs.ps1:

$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
}

Klicken Sie mit der rechten Maustaste auf „Mit Powershell ausführen“ in der *.ps1-Datei. Daraufhin wird neben jeder *.md-Datei mit demselben Namen eine PDF-Datei erstellt.

Sie können PDF-Dateien wie folgt in Ihre *.tex-Datei einbinden:

%In your latex *.tex file you can embed
\includepdf[pages=-]{MyProjects/ProjectDirA/ReadmeA.pdf}

Answer 3

Eigentlich wollte ich genau das Gleiche machen, also die readme.mdDatei in den Anhang aufnehmen.

ich fand diemarkdownPaket als sehr nützlich. Tatsächlich verfügt es über einen modifizierten Eingabebefehl, um externe .mdDateien einzuschließen, die Sie so importieren können, wie sie sind. Es ist \markdownInput{path/to/readme.md}.

Ich habe Folgendes gemacht:

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

\begin{document}

% your content here

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

\end{document}

Beachten Sie, dass:

• Die erste Unterteilungsebene von Markdown (ein einzelnes #) entspricht \chapter, und so weiter ( ##entspricht \section, ...). Daher möchten Sie möglicherweise die Unterteilungsebene mit der shiftHeadingsOption anpassen.
• Sie müssen Ihr Dokument mit aktiviertem Shell-Escape erstellen (d. h. pdflatex --shell-escape).