¿Cómo puedo sincronizar la documentación con Github Pages?

Tengo un proyecto junto con varias personas y tenemos un README.mdarchivo con un montón de GitHub Flavored Markdown que se representa en nuestra página de GitHub. También configuramos una rama de Páginas de GitHub que está alojada en el subdominio de nuestra Organización GitHub, y usamos el Generador de páginas automático simplemente cargando nuestro README.mdarchivo cuando creamos nuestra página. Sin embargo, noto que cuando actualizo nuestro README.mdarchivo, no actualiza la página del proyecto. En su lugar, debemos ir a la pestaña de configuración de GitHub y recrear la página del proyecto, recargando el README.mdarchivo cuando lo hagamos.

Además, después de leer sobre el trabajo de vinculación relativa entre archivos de documentación en las páginas del directorio del proyecto de GitHub. Me gusta mucho la rebaja, ya que ahorra mucho tiempo de tener que escribir todo el HTML a mano para nuestra documentación. Sin embargo, lo que me gustaría es poder tener un README.mdarchivo que pueda incluir enlaces relativos a otros archivos de documentación ubicados en docs/*.md. Esperaba que hubiera una solución fácil para que mis otros archivos de documentación también pudieran incluirse en mi rama gh-pages y estar alojados en mi subdominio de GitHub Pages y ser renderizados y / o temáticos.

En otras palabras, mis preguntas son:

• ¿Hay alguna manera de que mi archivo README.md se actualice automáticamente en mi subdominio de página de Github?
  • [EDITAR]: No parece ser la respuesta si se usa el Generador de páginas automático. Debe ir a la página de configuración del repositorio y volver a cargarlo cada vez que haya un cambio para poder actualizarlo.
     
• ¿Hay alguna manera de que mis enlaces relativos a mi documentación en mi archivo README.md funcionen en mis páginas de Github, tal vez sincronizándome de alguna manera /docs/*.mdcon mis páginas de Github y de alguna manera renderizándolas y / o temándolas?
  • [EDITAR]: Por lo que he aprendido desde que escribí esta pregunta, parece que esto solo es posible en las páginas de GitHub mediante el uso de un generador de sitios estáticos como la gema rubí Jekyll y probablemente algunos usos de los webhooks compatibles con GitHub que se mencionan en los comentarios a continuación. Actualmente estoy tratando de encontrar una solución óptima.
     
• Mejor aún, ¿hay alguna forma aún más fácil de hacer esto y quizás tener solo una copia de mi README.md y documentación que se usa tanto en gh-pages como en mi rama principal y hace que todo sea más fácil?
  • [EDITAR]: Parece que este es casi definitivamente un no. Estaba pensando en la posibilidad de algo integrado en GitHub para permitir esto. Parece que en el futuro se podría incorporar un mejor soporte para este tipo de cosas en las páginas de GitHub, o al menos espero que así sea.
     

Voy a publicar una solución que configuré que aprovecha el hecho de que las páginas de GitHub usan Jekyll ya usando el generador automático de páginas.

1. git checkout gh-pages
2. mkdir _layouts
3. mv index.html _layouts
4. git checkout master -- README.md
5. mv README.md index.md
6. Anteponer el siguiente texto a index.md

---
layout: index
---

También debe abrir el index.htmlarchivo y realizar los siguientes cambios:

1. Elimine el HTML renderizado de la rebaja en su README.mdarchivo. Suele ser entre etiquetas <section>o <article>. Reemplaza este HTML con el texto {{ content }}que nos permitirá usar este archivo como jekyll. El archivo al que aplicamos el diseño se colocará donde está la etiqueta de contenido.

2. Busque el CSS para el tema de la página de su proyecto. para mí esta fue una línea como la siguiente:

   <link rel='stylesheet' href='stylesheets/stylesheet.css' />

   Esto debe cambiarse a

   <link rel='stylesheet' href='{{ site.path }}/stylesheets/stylesheet.css' />

3. Cualquier otro activo almacenado en su sitio que se utilizará en este diseño también deberá tener el prefijo {{ site.path }}.

Al hacer esto, Jekyll renderizará el archivo de rebajas como el contenido del index.htmldiseño en el _layoutsdirectorio. Para automatizar este proceso no solo para el archivo README.md, sino también para otros documentos que pueda tener en su rama maestra, he seguido los siguientes pasos:

Creó el archivo llamado que post-commitcontiene lo siguiente:

#!/bin/bash
###
### The following block runs after commit to "master" branch
###
if [ `git rev-parse --abbrev-ref HEAD` == "master" ]; then

    # Layout prefix is prepended to each markdown file synced
    ###################################################################
    LAYOUT_PREFIX='---\r\nlayout: index\r\n---\r\n\r\n'

    # Switch to gh-pages branch to sync it with master
    ###################################################################
    git checkout gh-pages

    # Sync the README.md in master to index.md adding jekyll header
    ###################################################################
    git checkout master -- README.md
    echo -e $LAYOUT_PREFIX > index.md
    cat README.md >> index.md
    rm README.md
    git add index.md
    git commit -a -m "Sync README.md in master branch to index.md in gh-pages"

    # Sync the markdown files in the docs/* directory
    ###################################################################
    git checkout master -- docs
    FILES=docs/*
    for file in $FILES
    do
        echo -e $LAYOUT_PREFIX | cat - "$file" > temp && mv temp "$file"
    done

    git add docs
    git commit -a -m "Sync docs from master branch to docs gh-pages directory"

    # Uncomment the following push if you want to auto push to
    # the gh-pages branch whenever you commit to master locally.
    # This is a little extreme. Use with care!
    ###################################################################
    # git push origin gh-pages

    # Finally, switch back to the master branch and exit block
    git checkout master
fi

EDITAR: Actualicé el script anterior tanto para el README.mdarchivo como para la rebaja docs/*para que ambos usen el mismo archivo de diseño. Esta es una configuración mucho mejor que la que tenía antes. Este script va en su .git/hooks/directorio. bash debe estar en tu camino.

Cree el archivo _config.ymlcon lo siguiente

markdown: redcarpet
path: http://username.github.io/reponame

El script anterior también sincroniza los archivos de rebajas que se encuentran en el docs/*directorio de la mastersucursal, para que también puedan verse en el sitio de Páginas de GitHub. La vinculación relativa a estos documentos funciona si incluye la siguiente función jQuery para quitar la .mdextensión de los anclajes en la gh-pagesrama. Puede agregar el siguiente script index.htmlen el _layoutsdirectorio:

$(document).on('ready', function () {
    $('a').each(function (i, e) {
        var href = e.href;
        if (href.search('.md') > 0)
            $(this).attr('href', href.split('.md')[0]);
    });
});

EDITAR: Cambié el código anterior en mi repositorio, esta fue una forma rápida y sucia de hacer esto, pero no funcionará bien en todos los casos si sabes a qué me refiero ... Por ejemplo, el archivo de rebajas company.mdata.mdno se procesaría correctamente. Para solucionar esto, actualicé esto al siguiente script que verifica más cuidadosamente el href y elimina la extensión si se encuentra. También hice que el script sea más genérico, lo que permite que se use para eliminar otras extensiones cambiando la extvariable. Aquí está el código:

$(function () {
    $('a').each(function () {
        var ext = '.md';
        var href = $(this).attr('href');
        var position = href.length - ext.length;
        if (href.substring(position) === ext)
            $(this).attr('href', href.substring(0, position));
    });
});

Configuré un repositorio de ejemplo en CoryG89 / docsync , que tiene una página de proyecto aquí , si desea ver cómo funciona todo esto en conjunto.

Mi solución al problema de sincronizar un README con una página de Github se desvía ligeramente de lo anterior. En lugar de usar un motor de Markdown de JavaScript separado, se puede usar la API de Github para devolver un archivo de Markdown representado como HTML.

1. Obtener el README.mdde https://api.github.com/repos/<owner>/<repo>/contents/README.md.
2. Decodifica la respuesta Base64: window.atob( JSON.parse( blob ).content );

3. Deja la decodificados READMEa https://api.github.com/markdownun cuerpo JSON

    {
      "text": "<README>",
      "mode": "markdown",
      "context": "<owner>/<repo>"
    }
   

4. Inserte el HTML renderizado en un elemento DOM, como lo hizo Brad Rhodes .

Dos advertencias para este enfoque:

1. La realización de dos solicitudes en serie ralentiza la carga de la página.
2. Puede encontrar límites de frecuencia al acceder a la API de Github.

Para una página de poco tráfico donde el tiempo de carga no es crítico (~ 1-2 segundos), entonces el método anterior funciona lo suficientemente bien.

Puede utilizar DocumentUp para representar su archivo README.md.

Tengo un par de ideas para compartir un solo archivo Léame entre su sitio de documentación y el repositorio principal de github:

1. Puede usar solo una rama de gh-pages que contenga tanto su código como un sitio de documentación de jekyll. Su repositorio podría estar un poco desordenado y deberá colocar un encabezado YAML en la parte superior del archivo Léame. Es casi apoya vinculación relativa. El problema es que si desea que jekyll represente su rebaja, le dará una extensión .html. Sin embargo, quizás haya una forma de configurar esto. Aquí hay un ejemplo que preparé para ver si funciona.

2. Puede usar llamadas AJAX en su sitio de documentación para leer el archivo Léame de su rama principal y luego renderizarlo con un renderizador de Javascript Markdown . Esto tardará un poco más en cargarse y no admitirá enlaces relativos sin que escriba un Javascript inteligente. También es más trabajo implementar que la idea 1.

Otra ruta a considerar es configurar un enlace previo a la confirmación que construya las páginas relevantes. Hago esto en uno de mis repositorios . Sin gh-pagesembargo, probablemente tendrá que deshacerse del generador de páginas automático y simplemente pasar a la rama usted mismo, además de hacer algo elegante para convertir sus documentos en HTML o un sitio Jekyll como sugiere Nathan .

En ese repositorio presiono así para mantenerme gh-pagesidéntico master. También hay muchas otras formas de hacerlo. Sin embargo, esto podría no ser ideal para su situación (es posible que no desee que sean idénticos).

De todos modos, la razón por la que había ofrecido una recompensa por esta pregunta era porque esperaba que alguien tuviera un mejor flujo de trabajo. Este método es un poco complicado e inflexible y requiere que todos mantengan sus ganchos sincronizados.

Otro método que he logrado que funcione con bastante éxito es usar Ajax para recuperar los documentos usando la API de Github y un motor de rebajas de Javascript para representar el HTML (como también lo sugirió Nathan).

1. Use la API de Github y JSONP para obtener el documento de Github
2. Decodifica el contenido base64 en la respuesta de la API de Github
3. Renderice la rebaja utilizando un motor de rebajas de JavaScript
4. Mostrar el html renderizado

Nathan expresó cierta preocupación por el rendimiento, pero en mi experiencia, se carga aparentemente al instante, así que no creo que sea un problema.

La ventaja es que es fácil de configurar y siempre actualizará sus documentos, incluso si solo edita la rebaja directamente en un navegador en github.

Configuré un ejemplo en las páginas de Github en http://bradrhodes.github.io/GithubDocSync/ para mostrar que funciona.

Otra posibilidad para el método descrito por Nathan y Brand Rhodes es utilizar una gran herramienta: FlatDoc creado por Rico Sta. Cruz.

FlatDoc cargará mediante ajax la documentación (README.md o cualquier otro archivo de rebajas), la analizará y mostrará con todas las ventajas e incluso un menú de barra lateral para la navegación.

Tiene incorporado en su api un método auxiliar para cargar archivos desde el repositorio maestro de GitHub (pero también se puede cargar en cualquier otro lugar de la web).

Instrucciones

Empiece por copiar la siguiente plantilla html en su index.html en su rama gh-pages. Continua con:

• Reemplazo de "USUARIO" con su nombre de usuario de GitHub
• Reemplazo de "REPO" con el nombre de su repositorio de GitHub
• Reemplazo de "Su proyecto" con el nombre de su proyecto

en el archivo. Pruébelo localmente en su navegador. Luego confirme y empuje los cambios. Ahora su página de github siempre se actualizará con su archivo README.md en su rama maestra.

Si el tema predeterminado no le satisface, puede cambiarle el estilo con su propio CSS.

También quiero editar documentos en master y publicar en gh-pages; me gusta mantener los documentos actualizados con el código fuente y esa parece la mejor manera. Este es un trabajo en progreso para mí, pero tomé el script de Cory como punto de partida y lo expandí un poco para que funcione de _layoutsinmediato, siempre que haya una rama gh-pages con (es decir, un sitio jekyll). Convierte las vallas de estilo backtick (para bloques de código) que funcionan bien en la exploración de fuentes de github, pero no en las páginas de gh. Utilizo una index.mdcon una inclusión para el proyecto README.mdpara poder agregar un encabezado y algunas otras decoraciones. Esta versión también maneja la documentación en cualquier directorio anidado llamado "docs" que encuentro útil en un proyecto con múltiples módulos (no submódulos git, solo subdirectorios):

.git/hooks/post-commit

#!/bin/bash
###
### The following block runs after commit to "master" branch
###
if [ `git rev-parse --abbrev-ref HEAD` == "master" ]; then

    # function to convert a plain .md file to one that renders nicely in gh-pages
    function convert {
        # sed - convert links with *.md to *.html (assumed relative links in local pages)
        # awk - convert backtick fencing to highlights (script from bottom of file)
        sed -e 's/(\(.*\)\.md)/(\1.html)/g' "$1" | awk -f <(sed -e '0,/^#!.*awk/d' $0) > _temp && mv _temp "$1"
    } 

    if ! git show-ref --verify --quiet refs/heads/gh-pages; then
        echo "No gh-pages, so not syncing"
        exit 0
    fi

    # Switch to gh-pages branch to sync it with master
    ###################################################################
    git checkout gh-pages

    mkdir -p _includes

    # Sync the README.md in master to index.md adding jekyll header
    ###################################################################
    git checkout master -- README.md
    if [ -f README.md ]; then
        cp README.md _includes/
        convert _includes/README.md
        git add README.md
        git add _includes/README.md
    fi

    # Generate index if there isn't one already
    ###################################################################
    if [ ! -f index.md ]; then
        echo -e '---\ntitle: Docs\nlayout: default\n---\n\n{% include README.md %}' > index.md
        git add index.md
    fi

    # Generate a header if there isn't one already
    ###################################################################
    if [ ! -f _includes/header.txt ]; then
        echo -e '---\ntitle: Docs\nlayout: default\nhome: \n---\n\n' > _includes/header.txt
        git add _includes/header.txt
    fi

    # Sync the markdown files in all docs/* directories
    ###################################################################
    for file in `git ls-tree -r --name-only master | grep 'docs/.*\.md'`
    do
        git checkout master -- "$file"
        dir=`echo ${file%/*} | sed -e "s,[^/]*,..,g"`
        cat _includes/header.txt | sed -e "s,^home: .*$,home: ${dir}/," > _temp
        cat "$file" >> _temp && mv _temp "$file"
        convert "$file"
        git add "$file"
    done

    git commit -a -m "Sync docs from master branch to docs gh-pages directory"

    # Uncomment the following push if you want to auto push to
    # the gh-pages branch whenever you commit to master locally.
    # This is a little extreme. Use with care!
    ###################################################################
    # git push origin gh-pages

    # Finally, switch back to the master branch and exit block
    git checkout master
fi

exit $?

#!/usr/bin/awk
{
   # Replace backtick fencing (renders well when browsing github) with jekyll directives
   if (/```/) {
      IN = IN?0:1 # Are we already in a fenced section? Toggle.
      if (IN) { # If we are starting a fenced section
         if (/```\s*$/) {
           $0 = $0"text" # empty language is OK for backticks but not for jekyll
         }
         gsub(/```/, "{% highlight ")
         print $0" %}"
      } else { # ending a fenced section
        print "{% endhighlight %}" 
      }
    } else { # not a fencing line
      if (IN) { # but in a fenced section, so add indent to make sure code is rendered with <pre>
        print "    "$0
      } else {
        print
      }
    }
}

Otra variación del original es que establece una variable page.homeen todas las páginas. Esto se puede usar para ubicar la ruta relativa del directorio raíz, por lo que se puede usar para ubicar recursos estáticos como css. En _layouts/.default.htmltengo:

<link rel="stylesheet" href="{{ page.home }}css/main.css">

De esa manera puedo editar el CSS, construir el sitio jekyll localmente y ver el resultado en un navegador sin tener que esperar a que github lo construya en el servidor.

Recientemente hice un paquete gh-pages-generator para resolver este problema: genera un sitio de varias páginas utilizando varios archivos MD y un archivo de configuración.

Actualiza correctamente todos los enlaces entre las páginas. Es relativamente fácil convertirlo en parte de CI para confirmar los cambios en la rama gh-pages.

Lo estoy usando aquí y aquí .

No es difícil , dos copias y pegas en la terminal y ya está todo listo.

Jekyllle permite importar su archivo de rebajas y luego se encargará de convertirlos a HTML. El truco consiste en importarlo README.mda su index.mdarchivo con {% include_relative README.md %}. Así es como podemos hacer eso:

Vale la pena ver cómo configurar un Jekyllsitio super barebones en github (¡son solo dos archivos! )

La puesta en marcha

Puede copiar los dos archivos y hacer que su página vaya con su archivo Léame actual simplemente ejecutando esta configuración única ( copie todo el bloque de código y pase a la terminal ):

# Copy our two files to the gh-pages branch
git checkout -b gh-pages &&
wget https://raw.githubusercontent.com/lazamar/barebones-jekyll-project-readme/master/_config.yml &&
wget https://raw.githubusercontent.com/lazamar/barebones-jekyll-project-readme/master/index.md &&
#
# Commit and publish our page on github
git add -A && git commit -m "Create project github page" &&
git push --set-upstream origin gh-pages |
#
git checkout master # go back to master branch

Automatizando

Luego, solo necesitamos automatizar la tarea de copiar todos los cambios desde masterla gh-pagesrama antes de cada inserción. Podemos hacerlo ejecutando este script ( puede copiarlo y pegarlo en la terminal )

$(cat > .git/hooks/pre-push << EOF
#!/bin/sh
we_are_in_gh_pages="\$(git branch | grep -G "* gh-pages")"

if [ ! "\$we_are_in_gh_pages" ];
  then
    git checkout gh-pages &&
    git rebase master &&
    git push -f &&
    git checkout master # go back to master branch
fi
EOF
) && chmod 775 .git/hooks/pre-push

Creará un gancho de inserción que copiará todos los cambios de la masterrama gh-pagescada vez que ejecute git push.

Eso es. Hecho.