Permalink
Fetching contributors…
Cannot retrieve contributors at this time
284 lines (180 sloc) 13 KB

HubPress

¿Qué es HubPress?

editor

HubPress es una herramienta de código abierto, que puedes usar para construir un blog enriquecido basado en AsciiDoc, y además utilizando GitHub Pages!

Creado y mantenido por Anthonny Quérouil (twitter @anthonny_q).

Note
Aunque HubPress parezca tener todas las funcionalidades, está actualmente en Vista Preliminar (o Tech Preview). Como los errores son inevitables, si encuentras algo no está funciona de la manera que crees debería hacerlo, notifica el error y el equipo del proyecto lo revisará tan pronto como sea posible.

La documentación está evolucionando rápidamente en la medida que el proyecto va creciendo. Visita esta web regularmente para obtener más consejos sobre como usar HubPress. Si encuentras algún error en la documentación, por favor notifica el error. Tu ayuda en la mejora de todos los aspectos de HubPress es extremadament apreciada y cualquier Pull Request es siempre bienvenido.

Compatibilidad con Navegadores

HubPress es compatible con Chrome para escritorio, Firefox para escritorio y Chrome para Android.

Chrome Beta para Android será completamente compatible pronto, pero no está completamente soportada por algunos errores en IndexedDB, por eso durante la Vista Preliminar usa únicamente Chrome para Android.

Introducción

Instalación

Hacer fork al repositorio

Haz Click en el icono de Fork Fork para crear una copia de este repositorio con tu cuenta de GitHub.

Usa el dominio github.io

Si nunca has usado el dominio de GitHub Pages, sigue estos pasos para instalar rápidamente HubPress. Solo se necesitan unos pocos pasos para tener Hubpress instalado y listo para usar.

Important
Si actualmente estás usando tu usuario.github.io de GitHub Pages para otro proyecto, o si deseas usar un dominio personalizado, puedes ignorar esta sub-sección y saltar a la siguiente.
  1. Cambia el nombre del repositorio a <usuario>.github.io

  2. Añade la configuración necesaria a hubpress/config.json

    Edit config

    Los siguientes parámetros son obligatorios :

    • username, tu nombre de usuario de GitHub,

    • repositoryName, el nuevo nombre del Fork del repositorio, <usuario>.github.io.

  3. Confirma los cambios, y abre el dominio de GitHub Pages: http://<usuario>.github.io/.

  4. La siguiente pantalla aparecerá si has configurado correctamente HubPress.

    Install complete

Usar un dominio personalizado o si tu dominio de GitHub Page está actualmente en uso

Si deseas tener tu blog en un dominio personalizado, o si ya estás usando tu dominio de GitHub Pages para otro proyecto, necesitas una configuración adicional.

  1. En la configuración del Repositorio, establece la rama por defecto a gh-pages:

    Settings gh-pages
  2. cambia tu repositorio a la rama gh-pages

    Install complete

  3. establece los valores requeridos en `hubpress/config.json

    Edit config

    Los siguientes parámetros son obligatorios :

    • username, tu nombre de usuario de GitHub,

    • repositoryName,el nuevo nombre del Fork del repositorio. Por ejemplo, hubpress.io si no lo has renombrado.

  4. Confirma los cambios, y abre el dominio de Github Pages: http://<username>.github.io/<repositoryName>/.

  5. La siguiente pantalla aparecerá si has configurado correctamente HubPress.

    Install complete

Consola de Administración

La Consola de Administración está disponible en /hubpress

Acceder a la Consola de Administración

Install complete

Introduce tus credenciales de Github para iniciar sesión en la Consola de Administración de HubPress.

Una vez autenticado, se generará un Token para futuras llamadas de Hubpress al API de GitHub.

Éste se sincroniza en todas las sesiones de HubPress, por lo que si abres la nueva consola de administración en tu PC y luego en tu Tablet, el token es válido para todos los dispositivos.

Página de Configuración

Puedes configurar las opciones básicas del Blog (tales como CNAME o paginación) y cuentas de redes sociales que desees conectar a tu blog.

Meta

Esta sección contiene información básica configurada en el archivo /hubpress/config.json.

Los siguientes campos son configurables:

Git CNAME

Permite especificar un nombre de dominio personalizado. Ver Setting Up A Custom Domain para obtener instrucciones sobre cómo configurar un CNAME para tu blog.

Live Preview Render Delay

Controla cuanto tiempo espera el renderizador de la vista previa en actualizar (en milisegundos). Para aquellos que teclean rápido, establece un valor superior a 2000 (dos segundos) para ofrecer a una experiencia de edición más suave ya que la vista previa no se actualizará con tanta frecuencia. Establecer este valor por debajo de 2000 dará lugar a la actualización de la vista previa más rápida, pero puede dar lugar a cierto retraso del cursor al escribir.

Sitio

Título y Descripción

Los campos Title y Description te permiten colocar un nombre a tu blog, y una breve descripción para que tus visitantes puedan hacerse una idea de que esperar en los artículos del blog.

Los campos Logo y Cover Image pueden usarse de las siguientes maneras:

  • Un enlace HTML a un servicio de hosting de imágenes, por ejemplo Gravatar.

  • Un enlace a una imagen almacenada en el directorio /images del repositorio de tu blog.

Note
En /images/README.adoc podrás encontrar otras opciones para incluir imágenes es tus entradas del blog.
Temas

El campo Theme permite seleccionar entre los temas almacenados en el directorio /themes. El nombre debe ser exactamente el mismo que el directorio que contiene el tema.

Google Analytics

El campo Google Analytics toma el Tracking ID de Google Analytics generado para tu sitio.

Nombre Corto Disqus

El campo Disqus shortname toma tu Disqus URL/nombre_corto que usas cuando registras un nuevo sitio para Disqus. Solo el nombre corto es requerido, no el enlace a tu perfil personal.

Redes Sociales

Todos los campos en este grupo requieren las URLs completas a tu página de perfil público. La manera en que estos valores se muestran depende del tema seleccionado.

Gestionando entradas

Cuando entres a HubPress por primera vez, la vista Posts estará vacía. A medida que crees tus entradas en el blog, la página irá creciendo con la lista de entradas a tu izquierda, y una vista previa de la entrada a la derecha.

Creando una entrada

Note
Si nunca has usado AsciiDoc para escribir contenido, la guía para Escritores de AsciiDoctor debe ser tu primera parada en tu viaje. La guía proporciona ejemplos básicos y avanzados que puedes copiar y usar directamente.

El editor de HubPress muestra el código de AsciiDoc a la izquierda, y la vista previa en la derecha.

Título del blog y encabezados

El título del blog siempre debe ser el primer nivel en la entrada en AsciiDoc. Por ejemplo, = Título del Blog establece el nombre de la entrada del blog como Título del Blog.

Una línea = Título del Blog es requerida para guardar satisfactoriamente la entrada.

Si quieres colocar un encabezado de primer nivel debes utilizar == Encabezado de Primer Nivel. Subsecuentes niveles usan los respectivos subniveles de encabezado (===, ====, …​).

Parámetros de HubPress

HubPress te permite modificar las características de cada entrada del blog mediante atributos.

:hp-image: para Imagen de Portada de la Entrada

Si quieres agregar una imagen de portada a tu entrada del blog, debes agregar el atributo hp-image.

  1. :hp-image: Ejemplo:

= Blog Title
:hp-image: a-cover-image.jpg

NOTA: Dado que HubPress define el directorio /images como raíz por defecto de todas las imágenes, solo tienes que indicar el nombre de la imagen. Debido a esto, es posible que consideres crear un directorio /covers en tu repositorio para agrupar las imágenes de las portadas. Nombrar las imágenes de la cubierta de manera consistente facilitará enormemente su inclusión en cada entrada. Si tienes un tema para su blog, esto permite a sus lectores obtener una idea visual de lo que trata la entrada.

Los temas que actualmente soportan imágenes de portadas en las entradas del blog son:

  • Saga

:published_at: para alterar la Fecha de Publicación

Por defecto, la fecha de publicación es la fecha de creación de la entrada en el blog. Puedes definir una fecha de publicación propia añadiendo el atributo published_at.

  1. :published_at: Ejemplo :

= Blog Title
:published_at: 2015-01-31

:hp-tags: Etiquetas

Note
Categorías no están soportadas.

Añadir etiquetas mediante el atributo hp-tags.

  1. :hp-tags: Ejemplo:

= Blog Title
:hp-tags: HubPress, Blog, Open Source,

:hp-alt-title: para indicar un Título Alternativo

Especifique un título alternativo mediante el atributo hp-alt-title.

El título alternativo se utiliza en lugar del nombre de archivo HTML generado por HubPress.

  1. :hp-alt-title: Ejemplo :

= 大千世界
:hp-alt-title: My English Title

Añadiendo Imágenes

Publicando Imágenes en un repositorio GitHub

Puedes usar la consola de comando o un cliente de Git para añadir imágenes a una entrada. Para ello:

  1. Sube la imágen (mediante commit) al directorio /images.

  2. Usa la siguiente expresión de AsciiDoc en tu entrada del blog:

    image::<filename>[]
  3. Revisa http://asciidoctor.org/docs/asciidoc-writers-guide/ para ver más opciones de inserción de imágenes.

Si están integrando imágenes publicadas en otro dominio — instagram, otros repositorios GitHub, o cualquier servicio de imágenes — simplemente indica la URL completa en el lugar de <filename>.

Inserción de imágenes en otros dominios
image::http://<full path to image>[]
Usando incidencias de GitHub para publicar imágenes

Puedes usar una única incidencia para almacenar y publicar las imágenes de una entrada, para ello añade varias imágenes como comentarios, o como alternativa, puedes usar múltiples incidencias para almacenar imágenes de forma separada. Usa lo que mejor se adapte a tu estilo y el de tu organización. En el siguiente vídeo encontrarás ejemplos sobre como usar incidencias de GitHub y servicios de Cloud Hosting, también encontrarás algunos consejos extra sobre el uso del boque image en AsciiDoc.

Insertando Vídeos

HubPress permite insertar vídeo en una entrada mediante una sintaxi simple. No necesitas indicar la URL completa, solamente indica el ID único del video como en el ejemplo.

video::[id_unico_youtube][youtube | vimeo]
Insertando vídeo de YouTube
video::KCylB780zSM[youtube]
Insertando vídeo de Vimeo
video::67480300[vimeo]

Actualizando HubPress

Gracias a que HubPress está en GitHub, puedes actualizar a los últimos cambios haciendo pull del repostiorio master de HubPress.

Para aprender a hacerlo correctamente, puedes ver el siguiente vídeo (hay ciertas consideraciones a tener en cuenta la primera vez que haces pull del upstream).

Solución de problemas

Si algo no está funcionando como esperas, algunos de estos consejos podrían ayudarte.

Restablecimiento de la Base de datos del Blog en Android

A veces, la base de datos local de HubPress se desincronización con tu blog publicado. Esto puede suceder debido a que estás editando tu blog en tu PC, y luego cambias a la tableta.

HubPress trabaja con una base de datos local específica en tu navegador, por lo que si cambias de dispositivo — y en consecuencia cambias de navegador — se pierde la sincronía entre los navegadores.

Para devolver la instancia de HubPress a la del blog publicado, borra la caché del navegador y de datos en Ajustes > Aplicaciones. Tras esto, HubPress reconstruirá la base de datos local, y reflejará el estado del blog en GitHub.

Créditos

Gracias a Jared Morgan por poner en orden el archivo README que se ve aquí, y seguir siendo el "Documentador" para HubPress. Gracias a takkyuuplayer, hinaloe por haber traducido el README a Japonés.