pdf - plantilla - readme best practices

Exportación sin esfuerzo desde la wiki de github(?)

Question

Estoy recopilando bastante material en una wiki de GitHub. Realmente me gusta usar el wiki para cooperar con otras personas y en mi humilde opinión, la plataforma es realmente agradable, ¡me gusta!

Por lo tanto, me gustaría seguir usando la wiki de GH para recopilar cosas, editar, guardar, etc. pero también me gustaría exportar el contenido para crear un archivo pdf que podamos llamar "un manual". Me gustaría generar una versión actualizada del manual automáticamente cada vez que quiero ejecutar solo un par de secuencias de comandos, no puedo poner demasiado esfuerzo en esto.

Supongo que es posible exportar el contenido de alguna manera y el uso de pandoc ( http://johnmacfarlane.net/pandoc/ ) para crear el pdf quizás agregue un índice y un archivo de estilo.

Otra idea interesante podría ser publicar un sitio web una vez al mes descargando contenido directamente desde la wiki.

Supongo que otras personas ya hicieron algo como esto, pero no encontré nada. ¿Alguna idea?

Answer 1

¡También puedes probar html_links_to_pdf !

Es un script de Python 3 creado para convertir un Wiki de GitHub en formato pdf, utilizando el mismo estilo que usa GitHub, pero ligeramente más limpio.

Answer 2

Encontré muchas de las soluciones difíciles de reproducir / obtener la versión correcta / entender / arreglar / etc ... Entonces, en su lugar, presentaré una solución de acoplador de patchwork para convertir sin esfuerzo en Windows (usando git bash) / MacOS / Linux en 5 comandos "fáciles"

git clone {project_url}.wiki .

# Convert *.md to *.md.html using the actual github pipeline
docker run --rm -e DOCKER_USER_ID=`id -u` -e DOCKER_GROUP_ID=`id -u` /
            v "`pwd`:/src" -v "`pwd`:/out" andyneff/github-markdown-preview

# Fix hyperlinks, since wkhtmltopdf is stricter than github servers
docker run --rm -v `pwd`:/src -w /src perl /
    perl -p -i -e ''s|(<a href=")([^/"#]+?)(#[^"]*)?(">.*?</a>)|/1/L/2/E.md.html/L/3/E/4|g''/
                  *.html

# Lowercase all filename so that hyperlink match
docker run --rm -v `pwd`:/src -w /src python /
    python -c ''import sys;import os; [os.rename(f, f.lower()) for f in sys.argv[1:]]'' /
               *.md.html

#Convert html to pdf using QT webkit
docker run -it --rm -e DOCKER_USER_ID=`id -u` -e DOCKER_GROUP_ID=`id -u`/
           -v `pwd`:/work -w /work andyneff/wkhtmltopdf /
           wkhtmltopdf --encoding utf-8 --minimum-font-size 14 /
           --footer-left "[date]" --footer-right "[page] / [topage]" /
           --footer-font-size 10 /
           toc /
           *.html document.pdf

El perl es la parte principal que puede fallar sin una mejor solución. Pandoc tiene una solución de filtro realmente buena, pero no está utilizando la tubería de Github.

Errores :

• Se mostrarán bloques de código extra anchos con una barra de desplazamiento, y se cortarán esencialmente en el pdf. Sería mejor hacer que el bloque de código no se desborde, pero puede agregar --user-style-sheet user.css al comando wkhtmltopdf (antes de toc / cover ) y agregarlo a su user.css

  .markdown-body .highlight pre,
  .markdown-body pre{
    overflow:visible !important;
  }

• Algunos enlaces en el pdf final están desactivados por +1 página, otros no. No estoy seguro de cuál es el patrón. Pero los anclajes con identificadores (#) no parecen tener este problema

Answer 3

Estoy agregando a esta respuesta, en caso de que ayude a nuevos lectores :) esto es lo que hice:

Instalé GitHub Desktop: https://desktop.github.com/

Luego, en la página wiki de mi repositorio, hice clic en "Clonar en el escritorio"

Esto guardó el wiki localmente como un archivo .md (después de seguir los pasos en la pantalla)

Luego utilicé http://www.markdowntopdf.com/ para convertirlo a pdf (Nota: Cambié el nombre de los archivos para eliminar los caracteres que no funcionarían en un nombre de archivo pdf antes de subirlos al sitio web)

El resultado final fue realmente agradable.

Answer 4

Lo he logrado precisamente al crear la documentación portátil para Barcode Writer en Pure PostScript :

GitHub Wiki + Makefile + pandoc → PDF

El proceso se describe en esta publicación de blog .

Answer 5

Pero ... la wiki de Github de un repositorio de GitHub es un repositorio git en sí mismo ( presentado en agosto de 2010 ).

Puede clonarlo, presionarlo o extraerlo de él.

Cada wiki es un repositorio de Git, por lo que puedes empujarlos y tirar de ellos como cualquier otra cosa.
Cada wiki respeta los mismos permisos que el repositorio de origen.
Simplemente agregue " .wiki " a cualquier nombre de repositorio en la URL y .wiki para .wiki .

Eso hace que la parte de "exportación" de tu pregunta sea realmente trivial.

A partir de ahí, encontrará toneladas de secuencias de comandos para convertir páginas de descuentos en pdf:

• una tarea de graddle
• un archivo MAKE
• una secuencia de comandos python
• ...