1.0.2 • Published 5 years ago

@etorre/md-links v1.0.2

Weekly downloads
4
License
MIT
Repository
github
Last release
5 years ago

Markdown Links

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.

Diagrama de Flujo del proyecto

Guía de uso e instalación

API mdLinks(path, options)

Instalación

  • Para instalar la libreria vía npm ejecutar la siguiente linea a través de la terminal:

    npm i @etorre/md-links

Uso

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.

Valor de retorno

La función retorna una promesa (Promise) que resuelva a 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

Deberás importar la librería en tu archivo .js:

const mdLinks = require('@etorre/md-links');

Retorno por defecto:

mdLinks.mdLinks('./src', {validate : false})
  .then(links => console.log(links));
    // => [{ href, text, file }]

validate_false

Retorno al verificar cada link:

En éste caso, se adicionan dos propiedades a cada objeto:

  • status: el status(número) de la respuesta recibida a la petición HTTP a dicha URL.
  • ok: OK o FAIL según la respuesta de HTTP al averiguar si el link funciona o no.
mdLinks.mdLinks('./src', { validate: true })
  .then(links => console.log(links));
    // => [{ href, text, file, status, ok }]

validate_true

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

Para ejecutar la aplicación debe hacerlo de la siguiente manera a través de la terminal:

md-links <path-to-file> [options]

Por ejemplo:

onlypath

El comportamiento por defecto no debe validar si las URLs responden ok o no, solo debe identificar el archivo markdown (a partir de la ruta que recibe como argumento), analizar el archivo Markdown e imprimir los links que vaya encontrando, junto con la ruta del archivo donde aparece y el texto que hay dentro del link (truncado a 50 caracteres).

Options

--validate

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

option_validate

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.

option_stats

También podemos combinar --stats y --validate para obtener estadísticas que necesiten de los resultados de la validación.

option_stats_validate

Objetivos de aprendizaje

Javascript

  • Consumo de Promesas
  • Creacion de Promesas
  • Modulos de Js
  • Recursión

Node

  • Sistema de archivos
  • package.json
  • crear modules
  • Instalar y usar modules
  • npm scripts
  • CLI (Command Line Interface - Interfaz de Línea de Comando)

Testing

  • Testeo de tus funciones
  • Testeo asíncrono

Git y Github

  • Organización en Github

Buenas prácticas de desarrollo

  • Modularización
  • Nomenclatura / Semántica
  • Linting

Tutoriales / NodeSchool workshoppers

Otros recursos