GitHub y Markdown

30 agosto 2011

Si entro en el repositorio PruebaGit que cree en este artículo, GitHub es tan amable de avisarme de que no encuentra un archivo README.

En primer lugar, ¿qué es un README? Un archivo README contiene información genérica sobre el proyecto, como instalar, como configurar, como usar, licencia, contacto con el autor, bugs, etc... Para más detalles esta el artículo de la wikipedia (en inglés, el artículo en español es bastante malo).

Bien, pues GitHub te recomienda poner un archivo README en la raíz de tu proyecto, y para ello puedes usar varios lenguajes de maquetado. Un lenguaje de maquetado es un archivo de texto plano (normal y corriente) pero que usa una síntaxis especial y específica para poder pasarle una herramienta y convertirlo a HTML. Yo voy a utilizar Markdown.

La gracia viene en que voy a crear un archivo README.markdown y GitHub lo podrá convertir al vuelo en un HTML, de esta manera el que utilice un navegador web para explorar GitHub podrá ver una descripción de mi proyecto en HTML, que siempre queda mejor que en texto plano.

Como ya digo, voy a crear el README del proyecto PruebaGit y voy a incluir los siguientes datos: Descripción del proyecto, como instalar y contacto con el autor, con esos tres apartados creo que ya es suficiente.

Click con el botón derecho en PruebaGit > New... > File > Name: README.markdown. Con esto se abre el archivo en blanco.

A continuación voy a ir describiendo como voy usando el lenguaje Markdown para darle formato al texto:

  1. Título: Prueba Git. Para forzar que sea el primer encabezado, lo subrayo con =
  2. Para definir otro párrafo, basta con dejar una línea en blanco, o solo rellena con espacios o con tabuladores (y supongo que cualquier combinación de ellos).
  3. Instalación: Éste epígrafe es de tipo título 2, así que lo subrayo con -
  4. Los items de instalación son una lista, basta con comenzar cada item con -, * ó +. Con esto he tenido problemas (como se puede ver en el repositorio). La lista tiene que estar separada del párrafo anterior por una línea en blanco, si no, no la estima como válida.
  5. Contacto, de nuevo título 2, así que se subraya con -
  6. Enlaces: Los enlaces funcionan poniendo entre corchetes el título del enlace y a continuación, entre paréntesis, la url del enlace: [AguasNegras](http://www.aguasnegras.es/blog/?p=201).
  7. Los enlaces de mail, igual, título entre corchetes y entre paréntesis la dirección de mail: [agustinventura](http://www.aguasnegras.es/blog/?p=201)

Y eso es todo, los resultados se pueden ver aquí. Como detalle curioso e interesante, podemos decir que GitHub automáticamente te muestra el README en la página principal del repositorio del proyecto (ejemplo).