Markdown Links

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.

2. Resumen del proyecto MD-LINKS

Esta es una libreria ejecutada con node.js, donde se le entrega al programa una ruta y se leen los archivos tipo Markdown, se extraen los links encontrados en cada archivo y si el usuario lo requiere se validan, tambien permite la opcion de mostrar estadisticas basicas sobre los links encontrados.

El programa es ejecutable mediante un CLI, y su programación esta basada en promesas y recursividad.

3. Diagrama de flujo}

4. Documentación técnica de la librería

4.1 JavaScript API

La biblioteca se importa y usa de acuerdo al siguiente ejemplo

const {mdLinks} = require('jsamper-md-links')

mdLinks(path, options)

Argumentos

• path: Ruta absoluta o relativa al archivo o directorio. Si la ruta pasada es relativa, debe resolverse como relativa al directorio desde donde se invoca node - current working directory).
• options: Un objeto con únicamente las siguientes propiedades:
  • validate: Booleano que determina si se desea validar los links encontrados.
  • stats: Booleano que determina si se desea obtener un output con información estadística general.

Valor de retorno

La función debe retornar una promesa (Promise) que resuelva a un arreglo (Array) de objetos (Object), donde cada objeto representa un link y contiene las siguientes propiedades

Con validate:false :

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

Con validate:true :

• 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

4.2 CLI (Command Line Interface - Interfaz de Línea de Comando)

Para ejecutar md-links en la terminal, debe ingresarse de la siguiente manera: md-links <path-to-file> [options]

El programa MD-links recibe una ruta relativa o absoluta como primer parametro y permite las siguientes opciones como entrada.

• Validate
• Stats

Si solo es ingresada la ruta, el resultado sera la ruta, el link y el texto del link.

$ md-links ./some/example.md
./some/example.md http://algo.com/2/3/ Link a algo
./some/example.md https://otra-cosa.net/algun-doc.html algún doc
./some/example.md http://google.com/ Google

Si ingresas la opción --validate o --v, el módulo debe hacer una petición HTTP para averiguar si el link funciona o no. Si el link resulta en una redirección a una URL que responde ok, entonces consideraremos el link como ok.

$ md-links ./some/example.md --validate
./some/example.md http://algo.com/2/3/ ok 200 Link a algo
./some/example.md https://otra-cosa.net/algun-doc.html fail 404 algún doc
./some/example.md http://google.com/ ok 301 Google

Si ingresas la opción --stats o --s, obtendras estadisticas basicas sobre los links.

$ md-links ./some/example.md --stats
Total: 3
Unique: 3

Y si se combinan las opciones --validate & --stats obtendras estadísticas que necesiten de los resultados de la validación.

$ md-links ./some/example.md --stats --validate
Total: 3
Unique: 3
Broken: 1

5. Guia de Uso e Instalación

Para usar el modulo, lo puedes instalar con el siguiente comando desde tu terminal:

npm i jsamper-md-links

Este módulo incluye un ejecutable como una interfaz que se puede importar con require.

const {mdLinks} = require('jsamper-md-links')

los comandos validos de opciones desde la terminal son:

--validate o --v
--stats o --s

Para ver los resultados de ambos comando revisar la documentación tecnica de la libreria.

para ejecutarlo desde el CLI:

md-links <path-to-file> [options]