☰

Встроить Github readme.md в Latex

tag-icon • tag-icon input markdown git
Встроить Github readme.md в Latex

В ходе написания диссертации я создал несколько Git-репозиториев, которые документируются с использованиемreadme.md, который GitHub использует в качестве пояснения к репозиторию. Теперь я хотел бы включить эти документы в приложение к моей диссертации. Как лучше всего это сделать?

Я бы предпочел решение, которое просто связывает readme.mdфайлы, чтобы изменения вносились автоматически.

решение1

Лучше всего это сделать с помощью Markdown-to-LaTeX-Compiler и Makefile для сборки проекта. Вот пример краткого изложения того, как можно действовать:

  1. Установить pandoc

  2. Создайте Makefile или эквивалент (пакетный файл, скрипт и т. д.) со следующим содержимым, повторив первую строку для каждого файла readme проекта, который вы хотите включить:

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

  3. Добавьте \include{/path/to/GitHub/project/readme}операторы в документ LaTeX, где это применимо.

  4. Используйте Makefile для сборки вашего проекта. Это не обязательно делать после каждого изменения в документе LaTeX, только после изменения/добавления файла readme проекта GitHub.

В качестве альтернативы вы можете следоватьэтот ответи использовать pandoc в LaTeX на лету. Я считаю это менее элегантным решением, но тем не менее вот краткое изложение того, как вы могли бы использовать это, чтобы достичь желаемого:

  1. Установить pandoc
  2. Скопируйте преамбулу из примера документа в связанном ответе.

  3. Чтобы встроить файлы Markdown, вставьте их в свой документ следующим образом:

    \begin{markdown}
  \input{/path/to/GitHub/project/readme.md}
\end{markdown}
  4. Каждый раз, когда вы компилируете документ, он также должен компилировать и встраивать документы Markdown.

решение2

Мой ответ основан на том, что @Big-Blue предложил с некоторой автоматизацией powershell. Я полагаю, у вас есть папка, где все ваши репозитории находятся, например, папка Projects.

Пример структуры папки:

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

Содержимое файла 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
}

Щелкните правой кнопкой мыши пункт «Запустить с помощью Powershell» на файле *.ps1, и рядом с каждым файлом *.md с тем же именем будет создан PDF-файл.

Вы можете включить PDF-файлы в свой файл *.tex следующим образом:

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

решение3

На самом деле я хотел сделать то же самое, то есть включить readme.mdфайл в Приложение.

Я нашелmarkdownпакет, который будет очень полезен. Действительно, он имеет измененную команду ввода, чтобы включать внешние .mdфайлы, которые вы можете импортировать такими, какие они есть. Это \markdownInput{path/to/readme.md}.

Я сделал следующее:

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

\begin{document}

% your content here

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

\end{document}

Быть в курсе, что:

  • Первый уровень секционирования уценки (одиночный #) соответствует \chapter, и так далее ( ##соответствует \section, ...). Поэтому вы можете захотеть настроить уровень секционирования с помощью опции shiftHeadings.
  • Вам необходимо создать документ с включенным экранированием оболочки (то есть pdflatex --shell-escape).

Связанный контент