@jobysalex/mdlinks

.

Markdown Links

Índice

• 1. Preámbulo
• 2. Proceso de desarrollo
• 3. Resumen del proyecto
• 4. Que es `mdLinks(path, options)
• 5. Modo de uso
• 6. Tutoriales y Recursos
• 7. Archivos del proyecto

---

1. Preámbulo

Markdown es un lenguaje de marcado ligero muy popular entre developers. Es usado en muchísimas plataformas que manejan texto plano (GitHub, foros, blogs, ...) y es muy común encontrar varios archivos en ese formato en cualquier tipo de repositorio (empezando por el tradicional README.md).

Estos archivos Markdown normalmente contienen links (vínculos/ligas) que muchas veces están rotos o ya no son válidos y eso perjudica mucho el valor de la información que se quiere compartir.

Entonces esta herramienta, creada con Node.js, lee y analiza archivos en formato Markdown, para verificar los links que contengan y reportar algunas estadísticas.

2. Proceso de desarrollo:

Como punto de partida para la ejecución de este proyecto, se elaboró la lógica y se diseñó un diagrama de flujo para organizar el proceso.

En este proyecto use la herramienta de planificación y organización de GitHub llamada Github Projects.

Utilice para el desarrollo de este proyecto: CommonJS Modules, es decir, require/module.exports

3. Resumen del proyecto

En este proyecto se ha desarrollado un programa que se ejecutará en la terminal o consola. Para utilizar este, se puede con comandos específicos que he diseñado y programado en la misma línea de comandos.

Estos comandos nos permitirán acceder a los enlaces presentes en archivos o directorios, osea lee y analiza archivos en formato Markdown, para obtener el total de enlaces, identificar enlaces únicos y encontrar enlaces rotos.

4. Que es mdLinks(path, options)

Esta es una función llamada mdLinks(path, options) que devuelve una promesa, recibiendo dos parámetros:

path que puede ser la ruta absoluta o relativa a un archivo o directorio. options que puede ser:

**** --validate el módulo debe hacer una petición HTTP para averiguar si el link funciona o no y obtendriamos:

Con validate:false osea si no lo colocamos tendremos:

* `href`: URL encontrada.
* `text`: Texto que aparecía dentro del link (`<a>`).
* `file`: Ruta del archivo donde se encontró el link.

Con validate:true osea si lo colocamos tendremos:

* `href`: URL encontrada.
* `text`: Texto que aparecía dentro del link (`<a>`).
* `file`: Ruta del archivo donde se encontró el link.
* `status`: Código de respuesta HTTP.
* `ok`: Mensaje `fail` en caso de fallo u `ok` en caso de éxito.

**** --stats: entonces si colocamos --stats la salida será un texto con estadísticas básicas sobre los links asi:

`{Total: 3, Unique: 3}`
    * `href`: URL encontrada.
    * `text`: Texto que aparecía dentro del link (`<a>`).
    * `file`: Ruta del archivo donde se encontró el link.

**** --validate --stats: entonces si colocamos las dos al tiempo, te agrega el número de links que están rotos o no funcionan correctamente, donde: Total: seria el número total de links encontrados en el archivo o directorio. Unique: seria el número de links únicos, es decir, aquellos que no se repiten. Broken: seria el número de links que están rotos o no funcionan correctamente. por tanto obtendriamos:

 `{Total: 3, Unique: 3, Broken: 1}`
     * `href`: URL encontrada.
     * `text`: Texto que aparecía dentro del link (`<a>`).
     * `file`: Ruta del archivo donde se encontró el link.
     * `status`: Código de respuesta HTTP.
     * `ok`: Mensaje `fail` en caso de fallo u `ok` en caso de éxito.

5. Modo de uso

Debes ingresar la ruta del archivo o directorio de la sigueinte manera:

1. Si ejecutas: md-links , el módulo hará una petición HTTP para averiguar si los links funcionan o no. Nos debe dar: href, text, file; se mostrarán estadísticas que también requieren los resultados de validación de los links.

2. Si se usa md-links --validate el módulo hará una petición HTTP para averiguar si los links funcionan o no. Nos debe dar: href, text, file, status y mensaje OK o FAIL.

3. Si utilizas el comando md-links --stats, recibirás los links y un texto que proporciona estadísticas básicas sobre los links encontrados en el archivo o directorio especificado. Nos debe dar: href, text, file, Total y Unique.

4. Si ejecutas el comando md-links --validate --stats , se mostrarán: href, text, file, status,
   mensaje OK o FAIL, Total, Unique y Broken

6. Tutoriales y Recursos

• learnyounode
• how-to-npm
• promise-it-wont-hurt
• Acerca de Node.js - Documentación oficial
• Node.js file system - Documentación oficial
• Node.js http.get - Documentación oficial
• Node.js - Wikipedia
• What exactly is Node.js? - freeCodeCamp
• ¿Qué es Node.js y para qué sirve? - drauta.com
• ¿Qué es Nodejs? Javascript en el Servidor - Fazt en YouTube
• ¿Simplemente qué es Node.js? - IBM Developer Works, 2011
• Node.js y npm
• Asíncronía en js
• NPM
• Publicar packpage
• Crear módulos en Node.js
• Leer un archivo
• Leer un directorio
• Path
• Linea de comando CLI

7. Archivos del proyecto

• README.md con descripción del módulo, instrucciones de instalación/uso, documentación del API y ejemplos. Todo lo relevante para que cualquier developer que quiera usar tu librería pueda hacerlo sin inconvenientes.
• index.js: Desde este archivo debes exportar una función (mdLinks).
• cli.js: En este archivo tendre las funciones.
• test-file: Es un directorio con carpetas y archivos de prueba.
• package.json con nombre, versión, descripción, autores, licencia, dependencias, scripts (pretest, test, ...), main, bin
• .editorconfig con configuración para editores de texto. Este archivo no se debe cambiar.
• .eslintrc con configuración para linter. Este archivo contiene una configuración básica para ESLint, si deseas agregar reglas adicionales como Airbnb deberás modificar este archivo.
• .gitignore para ignorar node_modules u otras carpetas que no deban incluirse en control de versiones (git).
• test/md-links.spec.js debe contener los tests unitarios para la función mdLinks(). Tu implementación debe pasar estos tests.

8. Anexos

A. Diagrama de Flujo

Autora: YOHANA ALEXANDRA BECERRA BECERRA