tag - git push
¿Cómo puedo sincronizar la documentación con Github Pages? (10)
Mi solución al problema de sincronizar un README con una página de Github se desvía un poco de lo anterior. En lugar de utilizar un motor de reducción de JavaScript por separado, uno puede usar la API de Github para devolver un archivo de Markdown renderizado como HTML.
-
README.mdelREADME.mddehttps://api.github.com/repos/<owner>/<repo>/contents/README.md. - Decode la respuesta Base64:
window.atob( JSON.parse( blob ).content ); Publique el archivo
READMEdescodificado enhttps://api.github.com/markdownen un cuerpo JSON{ "text": "<README>", "mode": "markdown", "context": "<owner>/<repo>" }Inserte el HTML renderizado en un elemento DOM, como lo hizo Brad Rhodes .
Dos advertencias para este enfoque:
- Realizar dos solicitudes en serie ralentiza la carga de la página.
- Puede encontrar límites de velocidad 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-2seg), entonces el método anterior funciona bastante bien.
Tengo un proyecto junto con varias personas y tenemos un archivo README.md con un montón de Markdown con sabor de GitHub que se procesa en nuestra página de GitHub. También creamos una sucursal de GitHub Pages alojada en el subdominio de nuestra organización GitHub, y usamos el generador automático de páginas simplemente cargando en nuestro archivo README.md cuando creamos nuestra página. Sin embargo, README.md que cuando actualizo nuestro archivo README.md , no actualiza la página del proyecto. En cambio, debemos ir a la pestaña de configuración de GitHub y volver a crear la página del proyecto, README.md cargar el archivo README.md cuando lo hagamos.
Además, después de leer sobre el enlace relativo trabajando entre archivos de documentación en las páginas del directorio del proyecto GitHub. Me gusta mucho el descuento ya que ahorra muchísimo tiempo en tener que escribir todo el HTML a mano para nuestra documentación. Sin embargo, lo que me gustaría es poder tener un archivo README.md 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 se incluyeran en mi rama gh-pages y se alojaran en mi subdominio GitHub Pages y se procesaran y / o temáticas.
En otras palabras, mis preguntas son:
- ¿Hay alguna manera de hacer que mi archivo README.md se actualice automáticamente en mi subdominio Página de Github?
- [EDIT]: No parece ser la respuesta si se usa el generador automático de páginas. Debe ir a la página de configuración del repositorio y volver a cargarlo cada vez que haya un cambio para actualizarlo.
- [EDIT]: No parece ser la respuesta si se usa el generador automático de páginas. Debe ir a la página de configuración del repositorio y volver a cargarlo cada vez que haya un cambio para actualizarlo.
- ¿Hay alguna manera en que pueda hacer que mis enlaces relativos a mi documentación en mi archivo README.md funcionen en mis páginas de Github, quizás de alguna manera sincronice mi
/docs/*.mdcon mis páginas de Github y de alguna manera las represente y las reproduzca?- [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 webhook apoyados por GitHub que se mencionan en los comentarios a continuación. Intento tratar de encontrar una solución óptima.
- [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 webhook apoyados por GitHub que se mencionan en los comentarios a continuación. Intento tratar de encontrar una solución óptima.
- Mejor aún, ¿hay una manera aún más fácil de hacerlo y tal vez tener solo una copia de mi archivo README.md y la documentación que se usa tanto en gh-pages como en mi rama principal y que todo sea más fácil?
- [EDIT]: parece que este es casi definitivamente un no. Estaba pensando en la posibilidad de algo incorporado en GitHub para permitir esto. Parece que se podría incorporar mejor soporte para este tipo de cosas en las páginas de GitHub en el futuro, o al menos espero que así sea.
- [EDIT]: parece que este es casi definitivamente un no. Estaba pensando en la posibilidad de algo incorporado en GitHub para permitir esto. Parece que se podría incorporar mejor soporte para este tipo de cosas en las páginas de GitHub en el futuro, o al menos espero que así sea.
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á ajax la documentación (README.md o cualquier otro archivo de rebajas), lo analizará y mostrará con todos los objetos e incluso un menú de la barra lateral para la navegación.
Tiene incorporado en su api un método de ayuda para cargar archivos desde GitHub Repo Master (pero también puede cargar en cualquier otro lugar desde la web).
Instrucciones
Comience copiando la siguiente plantilla html en su index.html en su rama gh-pages. Continua con:
- Reemplazar "USUARIO" con su nombre de usuario de GitHub
- Reemplazar "REPO" con su nombre de repositorio de GitHub
- Reemplazar "Tu proyecto" con tu nombre de proyecto
en el archivo. Pruébelo localmente en su navegador. Luego comprometa y presione los cambios. Ahora su página github siempre se actualizará con su archivo README.md en su rama principal.
Si el tema predeterminado no es satisfactorio para usted, puede volver a diseñarlo con su propio css.
Otra ruta a considerar es configurar un gancho precompromiso que construye las páginas relevantes. Lo hago en uno de mis repositorios . Sin embargo, probablemente tendrías que abandonar el generador automático de páginas y simplemente presionar a la rama gh-pages , así como hacer algo elegante para convertir tus documentos en HTML o en un sitio Jekyll como sugiere Nathan .
En ese repositorio , presiono de esta manera para mantener gh-pages idéntico al 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 ofrecí una recompensa por esta pregunta fue porque esperaba que alguien tuviera un mejor flujo de trabajo. Este método es complicado e inflexible y requiere que todos mantengan sus ganchos sincronizados.
Otro método con el que he trabajado con bastante éxito es el uso de Ajax para buscar los documentos que usan la API de Github y un motor de reducción de JavaScript para procesar el HTML (como también lo sugirió Nathan).
- Utilice la API de Github y JSONP para buscar el documento de Github
- Decodifica el contenido de base64 en la respuesta de la API de Github
- Renderice el descuento usando un motor de reducción de JavaScript
- Mostrar el html renderizado
Nathan expresó cierta preocupación por el rendimiento, pero en mi experiencia, parece ser instantáneo, así que no creo que sea realmente un problema.
La ventaja es que es fácil de configurar y siempre actualizará sus documentos, incluso si solo edita el marcado 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.
Puede usar DocumentUp para representar su archivo README.md.
Recientemente, he creado 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 realizar cambios en la rama gh-pages.
También quiero editar documentos en master y publicarlos en gh-pages. Me gusta mantener los documentos actualizados con el código fuente y me parece la mejor manera. Este es un trabajo en progreso para mí, pero tomé el guión de Cory como punto de partida y lo amplié un poco para que salga bien, siempre que haya una rama de gh-pages con _layouts (es decir, un sitio de jekyll). Convierte una valla de estilo backtick (para bloques de código) que funciona muy bien en la búsqueda de fuentes github, pero no en las gh-páginas. Utilizo un index.md con una inclusión para el proyecto README.md para poder agregar un encabezado y algunas otras decoraciones. Esta versión también maneja la documentación en cualquier directorio anidado llamado "documentos" que me parece útil en un proyecto con múltiples módulos (no submódulos de 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 página variable.casa en todas las páginas. Esto se puede usar para ubicar la ruta relativa del diractor de raíz, por lo que se puede usar para localizar recursos estáticos como css. En _layouts/.default.html tengo:
<link rel="stylesheet" href="{{ page.home }}css/main.css">
De esa forma puedo editar el CSS, construir el sitio de jekyll localmente y ver el resultado en un navegador sin tener que esperar a que Github lo construya en el servidor.
Tengo un par de ideas para compartir un solo archivo Léame entre su sitio de documentación y el repositorio principal de github:
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 compatible con la vinculación relativa. El problema es que si quieres que jekyll muestre tu rebaja, le dará una extensión .html. Tal vez hay una manera de configurar esto sin embargo. Aquí hay un ejemplo que lancé para ver si funciona.
Puede usar las llamadas AJAX en su sitio de documentación para leer el archivo léame de su rama principal y luego renderizarlo con un renderizador JavaScript Markdown . Esto llevará un poco más de tiempo para cargarse y no admitirá enlaces relativos sin que usted escriba algún código JavaScript inteligente. También es más trabajo de implementar que la idea 1.
Voy a publicar una solución que configuro que aprovecha el hecho de que GitHub Pages usa Jekyll que ya usa el generador automático de páginas.
-
git checkout gh-pages -
mkdir _layouts -
mv index.html _layouts -
git checkout master -- README.md -
mv README.md index.md - Anteponga el siguiente texto a
index.md
---
layout: index
---
También necesita abrir el archivo index.html y realizar los siguientes cambios:
Elimine el HTML renderizado de la
README.mden su archivoREADME.md. Esto es usualmente entre las etiquetas<section>o<article>. Reemplace este HTML con el texto{{ content }}esto nos permitirá usar este archivo como un jekyll. El archivo al que aplicamos el diseño se colocará donde está la etiqueta de contenido.Ubique el CSS para el tema de su página de proyecto. para mí esta fue una línea como la siguiente:
<link rel=''stylesheet'' href=''stylesheets/stylesheet.css'' />Esto necesita ser cambiado a
<link rel=''stylesheet'' href=''{{ site.path }}/stylesheets/stylesheet.css'' />- Cualquier otro activo almacenado en su sitio que se utilizará en este diseño también deberá ir precedido de
{{ site.path }}.
Al hacer esto, Jekyll renderizará el archivo de reducción como el contenido del diseño index.html en el directorio _layouts . Para automatizar este proceso no solo para el archivo README.md, sino también para otros documentos que pueda tener en su rama principal, he seguido los siguientes pasos:
Creado el archivo llamado post-commit contiene 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 archivo README.md como para el README.md en docs/* para que ambos utilicen el mismo archivo de diseño. Esta es una configuración mucho mejor que la que tenía antes. Esta secuencia de comandos va en su .git/hooks/ . Bash debe estar en tu camino.
Crea el archivo _config.yml con lo siguiente
markdown: redcarpet
path: http://username.github.io/reponame
La secuencia de comandos anterior también sincroniza los archivos de marcación encontrados en el directorio docs/* de la rama master , para que también se puedan ver en el sitio de Páginas GitHub. La vinculación relativa a estos documentos funciona si incluye la siguiente función jQuery para quitar la extensión .md de los anclajes en la rama gh-pages . Puede agregar la siguiente secuencia de comandos a index.html en el directorio _layouts :
$(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 manera rápida y sucia de hacerlo, pero no funcionará en todos los casos si sabes a qué me refiero ... Por ejemplo, el archivo de rebajas company.mdata.md no se procesaría correctamente. Para solucionar esto, actualicé esto al siguiente script que revisa con más cuidado el href y elimina la extensión si se encuentra. También hice el script más genérico, lo que permite que se use para eliminar otras extensiones cambiando la variable ext . 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.
No es difícil , dos copias y pega en la terminal y ya está todo listo.
Jekyll permite importar su archivo de descuento, y luego se encargará de convertirlos en HTML. El truco es importar su README.md en su archivo index.md con {% include_relative README.md %} . Aquí es cómo podemos hacer eso:
Vale la pena ver cómo configurar un sitio Jekyll super barebones en github (¡son solo dos archivos! )
La puesta en marcha
Puede copiar los dos archivos y hacer que su página funcione con su archivo léame actual simplemente ejecutando esta configuración única ( copie todo el bloque de código y pase al 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
Entonces solo necesitamos automatizar la tarea de copiar todos los cambios de la rama master a gh-pages antes de cada inserción. Podemos hacerlo ejecutando este script ( puede copiarlo y pegarlo en el 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 desde la rama master a gh-pages cada vez que ejecute git push .
Eso es. Hecho.