☰

Incorporar Github readme.md em Latex

tag-icon • tag-icon input markdown git
Incorporar Github readme.md em Latex

Durante minha tese, criei vários repositórios Git que são documentados usando oreadme.md que o GitHub usa como explicação do repositório. Agora gostaria de incluir essas documentações no apêndice da minha tese. Qual é a melhor forma de fazê-lo?

Eu preferiria uma solução que apenas vinculasse os readme.mdarquivos, para que as alterações fossem incluídas automaticamente.

Responder1

A melhor maneira de fazer isso é usar um compilador Markdown-to-LaTeX e um Makefile para construir o projeto. Aqui está um exemplo de resumo de como você pode proceder:

  1. Instale o pandoc

  2. Crie um Makefile ou equivalente (arquivo em lote, script, ...) com o seguinte conteúdo, repetindo a primeira linha para cada leia-me do projeto que você deseja 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. Adicione \include{/path/to/GitHub/project/readme}instruções em seu documento LaTeX quando aplicável.

  4. Use o Makefile para construir seu projeto. Não é estritamente necessário fazer isso após cada alteração no documento LaTeX, somente após alterar/adicionar um leia-me do projeto GitHub.

Alternativamente, você pode seguiresta respostae use pandoc em LaTeX instantaneamente. Considero esta uma solução menos elegante, mas mesmo assim aqui está um rápido resumo de como você usaria isso para realizar o que deseja:

  1. Instale o pandoc
  2. Copie o preâmbulo do documento de exemplo na resposta vinculada

  3. Para incorporar arquivos Markdown, incorpore-os em seu documento assim:

    \begin{markdown}
  \input{/path/to/GitHub/project/readme.md}
\end{markdown}
  4. Cada vez que você compila o documento, ele também deve compilar e incorporar os documentos Markdown.

Responder2

Minha resposta é baseada no que @Big-Blue sugeriu com alguma automação do PowerShell. Acho que você tem uma pasta onde todos os seus repositórios estão, como uma pasta Projetos.

Exemplo de estrutura de pasta:

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

Conteúdo do arquivo 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
}

Clique com o botão direito em Executar com Powershell no arquivo *.ps1 e um PDF será criado ao lado de cada arquivo *.md com o mesmo nome.

Você pode incluir arquivos PDF em seu arquivo *.tex assim:

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

Responder3

Na verdade, eu queria fazer exatamente a mesma coisa, ou seja, incluir o readme.mdarquivo no Apêndice.

Eu encontrei omarkdownpacote para ser muito útil. Na verdade, possui um comando de entrada modificado, para incluir .mdarquivos externos, que você pode importar como estão. Isso é \markdownInput{path/to/readme.md}.

Eu fiz o seguinte:

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

\begin{document}

% your content here

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

\end{document}

Esteja ciente que:

  • O primeiro nível de seccionamento do markdown (um único #) corresponde a \chapter, e assim por diante ( ##corresponde a \section, ...). Portanto, você pode querer ajustar o nível de corte usando a shiftHeadingsopção.
  • Você deve construir seu documento com o shell escape habilitado (isto é pdflatex --shell-escape).

informação relacionada