marked-links v3.1.2

Preámbulo

Markdown es un lenguaje de marcado ligero. 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).

El problema

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.

La solución

Marked-Links es una librería que lee y analiza archivos en formato Markdown, para verificar los links que contengan y reportar algunas estadísticas.

Consideraciones generales

• Marked-Links se ejecuta con Node.js lo que nos permite ejecutar JavaScript en el entorno del sistema operativo ya sea en tu máquina o un servidor, y así poder interactuar con el sistema de archivos, entorno, redes, etc.

• El parseado (análisis) del markdown para extraer los links se realiza mediante una combinación de módulos; primero, transformamos el markdown a HTML usando marked y de ahí extraemos los links con una librería de DOM, en este caso JSDOM.

• La librería incluye un ejecutable que podemos invocar en la línea de comando y una interfaz que podemos importar con require para usarlo programáticamente.

• El módulo es instalable desde el registro público de NPM y, también, desde Github ya que el repositorio es público y contiene un package.json válido.

Algoritmo empleado

El diagrama de flujo fue elaborado con el programa Dia.

Instalación

• Desde NPM:

$ npm install marked-links

• Desde Github:

$ npm install yamiroot/marked-links

Guía de uso

Como módulo:

API mdLinks(path, options)

Argumentos

• 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 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 resuelve 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

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", { validate: false })
  .then(links => {
    // => [{ href, text, file }]
  })
  .catch(console.error);

Como ejecutable:

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

El ejecutable se ejecuta de la siguiente manera a través de 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 debe validar si las URLs responden ok o fail, solo debe identificar el archivo markdown (a partir de la ruta que recibe como argumento), analizar el mismo e imprimir los links que vaya encontrando, junto con la ruta del archivo donde aparece y el texto dentro del link.

Options

--validate

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

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

Sobre la librería:

• Implementada en JavaScript.
• Se ejecuta utilizando Node.js.
• Dependencias: marked, node-fetch, jsdom y colors.
• Linter: Eslint.
• Otras tecnologías: Jest.
• Las pruebas unitarias cubren el 100% de coverage.

Recursos

• Módulos, librerías, paquetes, frameworks... ¿cuál es la diferencia?
• Linea de comando CLI
• Promise
• Pill de recursión - video
• Destructuring
• Comprendiendo Promesas en Js
• usr/bin/env node
• Shebang
• Herencia del Unix
• package.json
• Publicar primer módulo - video
• Tutorial NPM

Licencia

Copyleft 🄯 2020, Licencia MIT.