Creación y Gestión de Wikis en GitHub

Uso de Wikis

En las clases hemos visto como utilizar el archivo README.md para mostrar la documentación del proyecto, con el tiempo esta práctica ha ganado cada vez más adopción por su sencillez, pero eso no es la única manera de crear documentación.

Para ello existe dentro de Github la opción de crear una Wiki en donde puedes generar un nivel más estructurado de documentación. Puedes ver la sección de Wiki en tus proyectos en la sección superior del portal de Github.

Si seleccionas esta opción entonces podrás ver un botón que te invita a crear tu primera página, hazlo presiónalo.

El formulario te da la opción de crear una nueva página a la que llama Home lo que es una gran opción, puedes usar esta página para mostrar la documentación inicial, pero también la puedes usar como un índice para poder llevar a tu lector a diferentes secciones y eso es lo que vamos a hacer. Escribe lo siguiente en tu formulario.

# ¡Bienvenido a la wiki!

Aquí podrás encontrar todas las secciones para poder implementar tu proyecto de manera rápida y simple.

## Índice de navegación

[Explicación del proyecto](/proyecto.md)

Si presionas el botón de guardar los cambios, el resultado de esta primera edición es igual al de esta imagen.

Repite la misma operación, ahora con una nueva página llamada Proyecto, en su descripción puedes agregar cualquier contenido, en la imagen que sigue puedes ver un ejemplo de como debe lucir tu nueva página.

Si guardas los cambios, entonces el resultado de la estructura de tu wiki lucirá de la siguiente manera.

Comienza a crear algunas páginas, no te diré cuantas ni con qué nombres para que te diviertas, lo que sí haré es mostrarte como luce mi wiki al final.

Ahora vuelve a tu página Home en donde agregaste un poco de texto y además un enlace, en la esquina superior derecha hay un botón con el que puedes editarla. En el código markdown de aquí abajo podrás ver una manera fácil en la que puedes navegar entre secciones.

# ¡Bienvenido a la wiki!

Aquí podrás encontrar todas las secciones para poder implementar tu proyecto de manera rápida y simple.

## Índice de navegación

[Explicación del proyecto](./Proyecto)

[Arquitectura](./Arquitectura)

[Documentación](./Documentación)

Con este índice es fácil que tus usuarios puedan navegar entre las secciones de una manera cómoda, lo que estaría fenomenal es que ahora les facilites a tus usuarios volver a la sección principal en cada una de tus secciones para que la navegación se vuelva cíclica y así les sea muy fácil moverse entre todas las secciones. ¿Cómo harías eso?

Volvamos a la pantalla principal de la wiki y observa que debajo del menú de páginas está una sección que te permite crear una barra lateral personalizada, selecciona esta opción.

Al hacerlo notarás un formulario idéntico a los anteriores, solo que con un título diferente en donde podrás personalizar todos los detalles de la barra lateral, intenta copiar y pegar aquí el mismo markdown que acabamos de usar en la página Home. ¡Oh! Cierto, no cambies el título, la palabra _Sidebar es lo que permite que Github sepa que estamos hablando de una barra lateral y no de otra sección más.

Guarda tus cambios y disfruta de tu nueva barra de navegación.

Una característica superinteresante es que puedes clonar esta wiki dentro de tu entorno local sin mayor problema, observa que hacer esto significa que solo vas a clonar todos estos documentos y no vas a hacer lo mismo con el repositorio lo que se me hace superinteresante porque puede ser que el portal de Github sea fantástico, pero no tanto como para pasar ahí horas leyendo documentos por lo que de esta manera puedes hacerlo desde tu lector de documentos Markdown favorito.

¡Invierte tiempo en tus wikis! Visita las de otros proyectos y toma muchas ideas de ahí, practica mucho con tu documentación aprendiendo a usar el lenguaje Markdown y cuando tengas una wiki fantástica no olvides compartirla con todos nosotros.