@etorre/md-links NPM

Markdown Links

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.

Dentro de una comunidad de código abierto, nos han propuesto crear una herramienta usando Node.js, que lea y analice archivos en formato Markdown, para verificar los links que contengan y reportar algunas estadísticas.

Diagrama de Flujo del proyecto

Guía de uso e instalación

API mdLinks(path, options)

Instalación

Para instalar la libreria vía npm ejecutar la siguiente linea a través de la terminal:
npm i @etorre/md-links

Uso

Argumentos

path: Ruta absoluta o relativa al archivo o directorio.
options: Un objeto con las siguientes propiedades:
- validate: Booleano que determina si se desea validar los links encontrados.

Valor de retorno

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

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

Ejemplo

Deberás importar la librería en tu archivo .js:

const mdLinks = require('@etorre/md-links');

Retorno por defecto:

mdLinks.mdLinks('./src', {validate : false})
  .then(links => console.log(links));
    // => [{ href, text, file }]

validate_false

Retorno al verificar cada link:

En éste caso, se adicionan dos propiedades a cada objeto:

status: el status(número) de la respuesta recibida a la petición HTTP a dicha URL.
ok: OK o FAIL según la respuesta de HTTP al averiguar si el link funciona o no.

mdLinks.mdLinks('./src', { validate: true })
  .then(links => console.log(links));
    // => [{ href, text, file, status, ok }]

validate_true

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

Para ejecutar la aplicación debe hacerlo de la siguiente manera a través de la terminal:

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

Por ejemplo:

onlypath

El comportamiento por defecto no debe validar si las URLs responden ok o no, solo debe identificar el archivo markdown (a partir de la ruta que recibe como argumento), analizar el archivo Markdown e imprimir los links que vaya encontrando, junto con la ruta del archivo donde aparece y el texto que hay dentro del link (truncado a 50 caracteres).

Options

`--validate`

Si pasamos la opción --validate, 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.

option_validate

Vemos que el output en este caso incluye la palabra OK o FAIL después de la URL, así como el status de la respuesta recibida a la petición HTTP a dicha URL.