- 1. Descripción
- 2. Instalación
- 3. Funcionamiento básico
- 4. Documentación técnica
- 5. Criterios de aceptación mínimos del proyecto
La presente librería ejecutable en node.js permite obtener links o enlaces HTTP de archivos de tipo markdown. Como funcionalidades adicionales, permite validar dichos links y calcular algunos datos referentes a los links encontrados.
En general Markdown es un lenguaje de marcado ligero usado en diversas plataformas que manejan texto plano. Normalmente dichos archivos contienen links o vinculos que permiten complementar la información inicial. Sin embargo, dada la naturaleza de los links se requiere verificar su enlace. Lo anterior lleva a que la busqueda y validez manualmente resulte ser una tarea tediosa. Es allí donde esta librería hace tu vida mas sencilla.
Para la instalación de la librería, se ejecuta el siguiente comando:
npm i aredondomartinez-md-links
Este módulo incluye un ejecutable como una interfaz que se puede importar.
const {mdLinks} = require('aredondomartinez-md-links')
El programa se ejecuta mediante una herramienta de línea de comando CLI (Command Line Interface - Interfaz de Línea de Comando), y su programación esta basada en promesas y recursividad.
El módulo se importa en otros scripts de Node.js de la siguiente manera
const {mdLinks} = require('aredondomartinez-md-links')
-
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.
-
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
: Mensajefail
en caso de fallo uok
en caso de éxito.
El ejecutable se escribe de la siguiente manera en la terminal:
md-links <path-to-file> [options]
Por ejemplo:
$ 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
El comportamiento por defecto no valida las URLs, solo a partir de la ruta que reciben como argumento buscan archivos markdown e imprimen los links que van encontrando, junto con la ruta del archivo donde aparece y el texto que hay dentro del link. Sin embargo, existen dos opciones adicionales como se explica a continuación:
La opción --validate
realiza 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, de lo contrario responde fail.
Por ejemplo:
$ 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
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.
Si la opción --stats
es la que se ingresa, el output (salida) será un texto con estadísticas
básicas sobre los links.
$ md-links ./some/example.md --stats
Total: 3
Unique: 3
También podemos combinar --stats
y --validate
para obtener estadísticas que
necesiten de los resultados de la validación.
$ md-links ./some/example.md --stats --validate
Total: 3
Unique: 3
Broken: 1