Como generar una Tabla de Contenidos (TOC) en proyectos de Github/Bitbucket

Author Top
enzo

Hoy en día usar sistemas de control de versiones como Github o Bickbucket para nuestros proyectos es bastante popular debido a la flexibilidad.

Cuando estamos iniciando nuestros proyectos ambos sistemas recomiendan crear un archivo README.md para brindar una introducción a nuestros proyectos, pero podría llegar a convertirse en documentación del mismo.

De entrada la extensión MD no nos resulta familiar y es normal, MD significa MarkDown y es una serie de reglas de marcado que permite generar un HTML sin saber HTML indicando cosas como negrita, subtitulo y demás etiquetas especiales en un forma similar a la que hace http://wikipedia.org.

Si deseas conocer un poco mas de este MarkDown puede revisar la version de Github aquí https://help.github.com/articles/github-flavored-markdown y la version de BitBucket en https://bitbucket.org/tutorials/markdowndemo.

Cuando ya tenemos dominado el MarkDown indicando secciones dentro de nuestros documento, la evolución natural es hacer una Tabla de Contenido para hacer mas fácil  la navegación de nuestros archivos de Readme haciendo nuestros proyectos mas profesionales, pero esta tarea puede ser algo engorroso por suerte vamos a ver a continuación una herramienta que realiza este trabajo por nosotros.

1. Instalar DocToc

Asumiendo que tenemos instalado NodeJs instalando en nuestro sistema y por consiguiente el comando npm esta disponible ejecutamos el siguiente comando para instalar el proyecto DocToc.

$ npm install -g doctoc

2. Generando Toc

Una vez instalado solo debemos indicar sobre que archivos vamos a generar la Table de Contenidos o TOC por sus siglas en ingles. Si nuestro proyecto esta en gihub solo debemos ejecutar el siguiente comando

$ doctoc README.md

Si nuestro proyecto esta en Bitbucket solo debemos ejecutar el comando con una pequeña variante como se muestra a continuación.

$ doctoc README.md --bitbucket

Puedes ver un TOC generado por este comando en el proyecto https://github.com/enzolutions/community-bookstore/

Espero que haya sido de su agrado.