☰

Incrustar Github readme.md en Latex

tag-icon • tag-icon input markdown git
Incrustar Github readme.md en Latex

Durante mi tesis, he creado varios repositorios Git que están documentados utilizando elreadme.md que GitHub usa como explicación del repositorio. Ahora me gustaría incluir esa documentación en el apéndice de mi tesis. ¿Cual es la mejor manera de hacerlo?

Preferiría una solución que simplemente vincule los readme.mdarchivos, de modo que los cambios se incluyan automáticamente.

Respuesta1

Esto se puede hacer mejor usando un compilador Markdown-to-LaTeX y un Makefile para construir el proyecto. A continuación se muestra un resumen de ejemplo de cómo podría proceder:

  1. Instalar pandoc

  2. Cree un Makefile o equivalente (archivo Batch, script, ...) con el siguiente contenido, repitiendo la primera línea para cada archivo Léame del proyecto que desee incluir:

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

  3. Agregue \include{/path/to/GitHub/project/readme}declaraciones en su documento LaTeX cuando corresponda.

  4. Utilice el Makefile para construir su proyecto. No es estrictamente necesario hacer esto después de cada cambio en el documento LaTeX, solo después de cambiar/agregar un archivo Léame del proyecto GitHub.

Alternativamente, puedes seguiresta respuestay use pandoc en LaTeX sobre la marcha. Considero que esta es una solución menos elegante, pero aun así aquí hay un resumen rápido de cómo usarías esto para lograr lo que deseas:

  1. Instalar pandoc
  2. Copie el preámbulo del documento de ejemplo en la respuesta vinculada

  3. Para incrustar archivos Markdown, incrústelos en su documento de esta manera:

    \begin{markdown}
  \input{/path/to/GitHub/project/readme.md}
\end{markdown}
  4. Cada vez que compila el documento, también debe compilar e incrustar los documentos de Markdown.

Respuesta2

Mi respuesta se basa en lo que @Big-Blue sugirió con cierta automatización de PowerShell. Supongo que tienes una carpeta donde están todos tus repositorios, como una carpeta de Proyectos.

Ejemplo de estructura de carpetas:

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

Contenido del archivo 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
}

Haga clic derecho en Ejecutar con Powershell en el archivo *.ps1 y se creará un PDF junto a cada archivo *.md con el mismo nombre.

Puede incluir archivos PDF en su archivo *.tex de esta manera:

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

Respuesta3

De hecho, quería hacer exactamente lo mismo, es decir, incluir el readme.mdarchivo en el Apéndice.

Encontré elmarkdownpaquete para ser muy útil. De hecho, tiene un comando de entrada modificado, para incluir .mdarchivos externos, que puedes importar tal como están. Es \markdownInput{path/to/readme.md}.

Hice lo siguiente:

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

\begin{document}

% your content here

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

\end{document}

Sé consciente de:

  • El primer nivel de sección de rebajas (un solo #) corresponde a \chapter, y así sucesivamente ( ##corresponde a \section,...). Por lo tanto, es posible que desees ajustar el nivel de sección usando la shiftHeadingsopción.
  • Debe crear su documento con el escape de shell habilitado (es decir pdflatex --shell-escape).

información relacionada