Uso de la Wiki de Github.
0. Índice de contenidos.
- 1. Introducción.
- 2. Entorno.
- 3. Editando la primera página.
- 4. Histórico de la Wiki.
- 5. Clonar la Wiki en nuestro repositorio local.
- 6. Referencias.
- 7. Conclusiones.
1. Introducción
En este tutorial vamos a explicar cómo utilizar la Wiki de Github y las posiblidades que nos ofrece para documentar nuestros proyectos.
Recordemos que Github es un hosting web para el sistema de control de versiones Git. Si queréis saber más podéis consultar este tutorial de Jose sobre Github y este otro de Alejandro sobre Git.
2. Entorno.
El tutorial está escrito usando el siguiente entorno:
- Hardware: Portátil MacBook Pro 15′ (2.2 Ghz Intel Core I7, 4GB DDR3).
- Sistema Operativo: Mac OS Snow Leopard 10.6.7
- Git 1.7.5.1.
- Navegador: Mozilla Firefox 4.0.1
3. Editando la primera página.
Vamos a https://github.com/login nos autenticamos con nuestro usuario de Github.
Una vez autenticados, en el menú Switch Context (debemos pulsar sobre él para desplegarlo) nos aparecerán los repositorios a los que pertenecemos.
Seleccionamos el repositorio al que queremos acceder:
Una vez hemos accedido al repositorio deseado, únicamente debemos seleccionar la opción donde pone Wiki. Entre paréntesis nos saldrán el número de páginas que contiene la Wiki concreta de ese repositorio.
El siguiente paso es crear nuestra primera página. Pulsamos el botón New Page y le damos el nombre que queramos:
Ahora ya podemos empezar a editar nuestra nueva página. En el siguiente ejemplo podemos ver cómo se edita una página (en modo Markdown) con diferentes componentes.
Los botones de la parte superior, nos ayudarán a que nos sea más fácil realizar la tarea.
Si no queremos usar los botones, en el modo de edición Markdown, podemos utilizar la siguiente sintaxis (el texto en cursiva es variable y en negrita fijo):
- # Texto : Escribiría un título grande
- ## Texto : Este sería un título mediano
- ### Texto : Título pequeño
- [[Nombre de la página a enlazar]] : Enlace a una página del Wiki
- [Texto de enlace externo](http://www.destinodelenlace.com) : Enlace a un destino externo a la Wiki
-  : Imagen y texto alternativo
- **Texto** : Texto en negrita
- _Texto_ : Texto en cursiva
-
«`xml
<tag>Codigo xml</tag>
«` : Esto escribiría un bloque de código XML -
«`txt
Código en texto plano
«` : Esto escribiría un bloque de código en texto plano - + Texto : Elemento de lista no numerada
- – Texto : Elemento de lista no numerada
- * Texto : Elemento de lista no numerada
- 1. Texto : Elemento de lista numerada
- *** : Separador
- > Texto : Bloque de texto
Aquí podemos ver un ejemplo:
La vista previa nos mostraría lo siguiente:
4. Histórico de la Wiki.
La Wiki de GitHub nos da la opción de consultar el histórico de cambios en la Wiki de nuestro repositorio. Para ello, pulsando en la opción del sub-menu Wiki History podremos ver la lista de las acciones realizadas en las páginas de nuestra Wiki, comparar versiones y recuperar cambios.
5. Clonar la Wiki en nuestro repositorio local.
Como no podía ser de otra manera, GitHub nos permite clonar la Wiki de nuestro repositorio en nuestro repositorio local. Esto nos permitirá trabajar sin conexión con todos los archivos.
Para ello pinchamos en el sub-menu Git Access, copiamos la url que nos aparece (en mi caso https://marlandy@github.com/autentia/mirepositorio.wiki.git) y tecleamos el siguiente comando (como usuario root):
$ sudo git clone https://marlandy@github.com/autentia/mirepositorio.wiki.git
6. Referencias.
- Git y cómo trabajar con un repositorio de código distribuido
- Primeros pasos con Github: subir un proyecto al repositorio
- Making Github More Open: Git-backed Wikis
7. Conclusiones.
Hemos visto lo fácil que es utilizar la Wiki de Github. Simplemente es una alternativa más para centralizar y compartir la documentación (o parte de ella) de nuestros proyectos.
Espero que os haya sido de ayuda.
¡Hasta el próximo tutorial!
Miguel Arlandy.
