linaleon-md-links v1.0.1
Markdown Links
Índice
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
En este proyecto encontraras Md-Links es una librería en JavaScript que maneja una interfaz de línea de comandos (CLI) y que tiene como fin extraer y validar los links que se encuentran dentro de archivos MarkDown (.md). En la cual se puede obtener datos basicos con respecto a los links encontrados como la cantitan total delinks, el total de links unicos y el total de links rotos dentro de los archivos.
3. Diagramas de Flujo
Diagrama de flujo API
Diagrama de flujo CLI
4. Implementación de la librería
Instalación
npm i linaleon-md-links
Importe la librería con require()
const {mdLinks} = require('linaleon-md-links');
5. Consideraciones generales
El proyecto consta de DOS partes
1) API
mdLinks(path, options)
Argumentos
path
: Ruta absoluta o relativa al archivo o directorio.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
Con validate:false
se retorna:
href
: URL encontrada.text
: Texto que aparece dentro del link (<a>
).file
: Ruta del archivo donde se encontró el link.
Con validate:true
se retorna:
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.
Ejemplo (resultados como comentarios)
const mdLinks = require("md-links");
mdLinks("./some/example.md")
.then(links => {
// => [{ href, text, file }, ...]
})
.catch(console.error);
mdLinks("./some/example.md", { validate: true })
.then(links => {
// => [{ href, text, file, status, ok }, ...]
})
.catch(console.error);
mdLinks("./some/dir")
.then(links => {
// => [{ href, text, file }, ...]
})
.catch(console.error);
2) CLI (Command Line Interface - Interfaz de Línea de Comando)
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
Options
--validate
Si pasamos la opción --validate
, el módulo hace 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
.
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.
--stats
Si pasamos la opción --stats
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
Lina Alejandra Leon