@danisalermi/md-links v2.0.0
Markdown Links
Encuentra todos los links dentro de un archivo Markdown. Funciona cuando se ingresa una ruta relativa/ absoluta o si se llama un archivo Markdown que se encuentre en la posición relativa en la que está el usuario.
Instalación 🔧
$ npm install danisalermi/md-links
Usage ⚙
const md-links = require("@danisalermi/md-links");
mdLinks("path", {
options (opcionales)
})
.then(res => {
console.log(res);
})
.catch(err => {
console.log(err);
});
Opciones 🔑
Se puede utilizar el paquete con una serie de opciones. Las cuales son:
- Sin opciones: al ejecutar el paquete sin opciones se genera un arreglo con objetos que continen para cada link: href (link de la página), text (texto que acompaña al link) y file (archivo de donde se extrae el link).
- Validate: al ejecutar el paquete con la opción validate: true (para ejecución con require) o -v, -validate (para ejecución por CLI), se genera el arreglo anterior, agregando además, para cada link encontrado el status de cada uno de ellos mediante una llamada http.
- Stats: al ejecutar el paquete con la opción stats: true (para ejecución con require) o -s, -stats (para ejecución por CLI), se genera un objeto con el total de link y con la cantidad de links únicos encontrados dentro del archivo(s).
- Stats y Validate: al ejecutar el paquete con las opcines stats: true, validate: true (para ejecución con require) o -s -v, -stats -validate (para ejecución por CLI), se genera un objeto con el total de link, con la cantidad de links únicos encontrados dentro del archivo(s) y la cantidad de los mismos que tienen una respuesta http no favorable.
Ejemplos ✅:
const mdLinks = require("@danisalermi/md-links");
mdLinks("./some/example.md")
.then(links => {
// => [{ href, text, file }]
})
.catch(console.error);
mdLinks("./some/example.md", { validate: true, stats: false })
.then(links => {
// => [{ href, text, file, status, ok }]
})
.catch(console.error);
mdLinks("./some/example.md", { validate: false, stats: true})
.then(links => {
// => { Total, Unique }
})
.catch(console.error);
mdLinks("./some/example.md", { validate: true stats: true})
.then(links => {
// => { Total, Unique, Broken }
})
.catch(console.error);
mdLinks("./some/dir")
.then(links => {
// => [{ href, text, file }]
})
.catch(console.error);
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.
Dependencias 🔗
El paquete se desarrolló en JavaScript, haciendo uso de las siguientes dependencias fuera de node.js:
- Módulo commander.js. Esta fue utilizada para agregar opciones al paquete de manera que usuario pudiera pasarlas de manera más amigable y tener una guía de lo que hace el programa
Utilizando danisalermi/md-links -help
- Módulo chalk. La misma se utilizò para colocar colores a las respuestas del paquete por consola. Ejemplo:
- Módulo filehound, para poder encontrar todos los archivos con extensiones permitidas para archivos markdown dentro de un directorio.
- Módulo fetch. Para poder hacer las consultas al servidor http de los links encontrados.
Tambièn se hizo uso de las siguientes dependencias dentro de node.js:
- Módulo process con
process.argv[]
. Para obtener lo ingresado por el usuario mediante la terminal. - Módulo path. Para poder normalizar una ruta y obtener posteriormente la ruta absoluta.
- Módulo readline. Para leer cada línea de un archivo dado.
- Módulo fs.createReadStream. Para leer un archivo desde un path ingresado por el usuario.