angelicamcs-md-links v0.1.1
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. Uso de la aplicación
Para usar el modulo, lo puedes instalar con el siguiente comando desde tu terminal:
npm i angelicamcs-md-links
La biblioteca se importa y usa de acuerdo al siguiente ejemplo:
const {mdLinks} = require('angelicamcs-md-links')
los comandos validos de opciones desde la terminal son: --validate --stats
mdLinks(path, options)
Argumentos
path
: Ruta absoluta o relativa al archivo o directorio. .options
:--validate
: Valida los links encontrados.--stats
: Si se desea tener información estadística general.
Valor de retorno:
si ingresa solo la ruta (Path)
:
href
: URL encontrada.text
: Texto que aparecía dentro del link (<a>
).file
: Ruta del archivo donde se encontró el link.
Con --validate
:
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.
Con --stats
:
- Total: 3
- Unique: 3
Con --stats --validate
:
- Total: 3
- Unique: 3
- Broken: 1
ejemplos de uso: md-links
$ md-links ./some/example.md
href: ./some/example.md
file: http://algo.com/2/3/
text: Link a algo
Identifica el archivo markdown (a partir de la ruta que recibe como argumento), analiza el archivo Markdown e imprime los links que vaya encontrando, junto con la ruta del archivo donde aparece y el texto que hay dentro del link.
Options
--validate
Si pasa la opción --validate
, si el link funciona responde ok, entonces consideraremos el link como ok, si falla responde Fail.
$ md-links ./some/example.md --validate
href: ./some/example.md
file: http://algo.com/2/3/
text: Link a algo
status: 200
OK: ok
href: ./some/example.md
file: https://otra-cosa.net/algun-doc.html
text: algún doc
status: 404
OK: fail
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
$ md-links ./some/example.md --stats
Total: 3
Unique: 3
También puede combinar --stats
y --validate
para obtener estadísticas que necesite de los resultados de la validación.
$ md-links ./some/example.md --stats --validate
Total: 3
Unique: 3
Broken: 1