Markdown Links

Índice

• 1. Preámbulo
• 2. Resumen del proyecto y Definición del producto
  • 2.1. JavaScript API
  • 2.2. Interfaz de Línea de Comando - CLI
• 3. Requisitos
• 4. Consideraciones generales
• 5. Planificación

1. Preámbulo

Markdown es un lenguaje de marcado que permite dar formato a textos de una manera sencilla y rápida, usando una serie de caracteres especiales (almohadillas (#), asteriscos (*), guiones (-), corchetes ([ ]), paréntesis (()), etc.) para indicar los elementos que se quieren formatear, como encabezados, énfasis, listas, enlaces, imágenes, etc.

Fue creado en el año 2004 con el objetivo de facilitar la escritura de textos para la web sin tener que usar HTML. Markdown se puede convertir fácilmente a diferentes formatos y se puede usar en muchos sistemas de gestión de contenidos, blogs, foros y aplicaciones web.

2. Resumen del proyecto y Definición del producto

Los 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.

Para este proyecto se ha propuesto crear una herramienta de línea de comando (CLI) usando Node.js, que lea y analice archivos en formato Markdown para verificar los links que contengan y reportar algunas estadísticas. Así mismo, se desarrolla una librería en JavaScript, esta librería consta de DOS partes:

2.1. JavaScript API

● Instalación

Abre una terminal o línea de comandos en tu sistema operativo y ejecuta el siguiente comando:

npm install @laurilugo/md-links

● Uso

La librería puede importarse en otros scripts de Node.js y ofrece la siguiente interfaz:

mdLinks(path, options)

Argumentos

• path: Ruta absoluta o relativa al archivo o directorio.
• options: Un objeto con las siguientes propiedades:
  • validate: Booleano que determina si se desea validar los links encontrados.
  • stats: Booleano que determina si se desean obtener estadísticas de los enlaces.

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

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: Mensaje fail en caso de fallo u ok 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.2. Interfaz de Línea de Comando - CLI

● Instalación

Abre una terminal o línea de comandos en tu sistema operativo y ejecuta el siguiente comando:

npm install @laurilugo/md-links -g

● Uso

El ejecutable puede ejecutarse 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 valida si las URLs responden ok o no, solo 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 se incluye 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 se considera 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

En este caso el output 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 se incluye 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 es posible 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

3. Requisitos

• Node.js permite ejecutar JavaScript en el entorno del sistema operativo, nos abre las puertas para poder interactuar con el sistema en sí, archivos, redes, etc. Asegúrate de tenerlo instalado en tu computadora.
• Estas herramientas fueron desarrolladas para analizar archivos Markdown (.md). Asegúrate de tener uno o varios archivos Markdown en tu proyecto.

4. Consideraciones generales

• La librería y el script ejecutable (herramienta de línea de comando - CLI) están implementados en JavaScript para ser ejecutados con Node.js.

• El módulo es instalable vía npm install <laurilugo>/md-links. Este módulo incluye tanto un ejecutable que se pueda invocar en la línea de comando como una interfaz que se pueda importar con require para usarlo programáticamente.

• Para disminuir la complejidad del algoritmo recursivo, se utiliza la versión síncrona de la función para leer directorios, readdirSync.

5. Planificación

● Github Projects

Se implementaron issues y milestones para priorizar, organizar y hacer seguimiento del trabajo.

● Diagrama de flujo

Se elaboró un diagrama de flujopara visualizar y planificar las tareas y objetivos.

Realizado por :

Laura Lorena Lugo 🐱