☰

在 Latex 中嵌入 Github readme.md

tag-icon • tag-icon input markdown git
在 Latex 中嵌入 Github readme.md

在我的论文中，我创建了多个 Git 存储库，并使用GitHub 用作存储库说明的 readme.md。现在我想把这些文档添加到我的论文附录中。最好的方法是什么？

我更喜欢一种仅链接readme.md文件的解决方案，以便自动包含更改。

答案1

最好使用 Markdown-to-LaTeX 编译器和 Makefile 来构建项目。以下是您可以如何进行的示例概要：

  1. 安装 pandoc

  2. 创建包含以下内容的 Makefile 或等效文件（批处理文件、脚本等），对您希望包含的每个项目自述文件重复第一行：

    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 文档后，不必严格执行此操作，只需在更改/添加 GitHub 项目自述文件后执行此操作即可。

或者，你可以关注这个答案并在 LaTeX 中即时使用 pandoc。我认为这不是一个优雅的解决方案，但尽管如此，这里还是简要介绍一下如何使用它来实现您想要的效果：

  1. 安装 pandoc
  2. 从链接答案中的示例文档中复制序言

  3. 要嵌入 Markdown 文件，请将其嵌入到您的文档中，如下所示：

    \begin{markdown}
  \input{/path/to/GitHub/project/readme.md}
\end{markdown}
  4. 每次编译文档时，它也应该编译并嵌入 Markdown 文档。

答案2

我的回答基于 @Big-Blue 建议的一些 powershell 自动化。我猜你有一个文件夹，里面有你所有的 repos，就像一个 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
}

在 *.ps1 文件上右键单击“使用 Powershell 运行”，它将在每个同名 *.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}

意识到：

  • markdown 的第一个分段级别（单个#）对应于\chapter，依此类推（##对应于\section，...）。因此，您可能需要使用该shiftHeadings选项调整分段级别。
  • 您必须在启用 shell 转义的情况下构建文档（即pdflatex --shell-escape）。

相关内容