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. Diagrama de flujo

3. Instalación por la interfaz de lina de comando (CLI)

$ npm install -g Sthephany04/md-links

3.1 Ejecutando comandos

• Obtener links e información: puedes utilizar la ruta de un archivo con extension markdown o un directorio

$ md-links README.md

/mnt/c/Users/Laboratoria2/BOG001-data-lovers/README.md https://www.figma.com/file/hY1jmIMkONC7RzPzyUpz4P/Untitled  Figma

/mnt/c/Users/Laboratoria2/BOG001-data-lovers/README.md https://www.chartjs.org/  Chart.js

• Validar estado de links: Opcion --validate para obtener el estado de los links (OK - FAIL). 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.

$ md-links README.md --validate

/mnt/c/Users/Laboratoria2/BOG001-data-lovers/README.md https://www.figma.com/file/hY1jmIMkONC7RzPzyUpz4P/Untitled OK 200 Figma
 /mnt/c/Users/Laboratoria2/BOG001-data-lovers/README.md https://www.chartjs.org/ OK 200 Chart.js

• Obtener el total de links y los links unicos: Opcion --stats. el output (salida) será un texto con estadísticas básicas sobre los links.

$ md-links README.md --stats

Archivo: /mnt/c/Users/Laboratoria2/BOG001-data-lovers/README.md Links Unicos: 8 Links Totales: 8

• Obtener total de links, unicos y rotos: Opcion --validate --stats

$ md-links README.md --validate --stats

Archivo: /mnt/c/Users/Laboratoria2/BOG001-data-lovers/README.md Links Unicos: 8 Links Totales: 8 Links rotos: 0

4. Instalar y utilizar como modulo

Instalar como dependencia

$ npm install Sthephany04/md-links

const mdLinks = require("@sthephany04/md-links");

//obtener datos de un archivo markdown [{ href, text, file }]
mdLinks("some/example.md", { validate: false, stats: false})
  .then(links => {
    console.log(links)
  })
  .catch(console.error);

//Obtener datos [{ href, text, file, status, ok }]
mdLinks("./some/example.md", { validate: true, stats: false })
  .then(links => {
    console.log(links)
  })
  .catch(console.error);

//Obtener estadisticas [{ total, unicos }]
mdLinks("./some/example.md", { validate: false, stats: true })
  .then(links => {
    console.log(links)
  })
  .catch(console.error);

//Obtener estadisticas y validacion de links [{ total, unique, broken }]
mdLinks("./some/example.md", { validate: true, stats: true })
  .then(links => {
    console.log(links)
  })
  .catch(console.error);

//obtener datos de un directorio [{ href, text, file }]
mdLinks("some/dir")
  .then(links => {
    console.log(links)
  })
  .catch(console.error);

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.

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

Valor de retorno

La función debe retornar 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.

5. Objetivos de aprendizaje

JavaScript

• Uso de condicionales (if-else | switch | operador ternario)
• Uso de funciones (parámetros | argumentos | valor de retorno)
• Manipular arrays (filter | map | sort | reduce)
• Manipular objects (key | value)
• Uso ES modules (import | export)
• Diferenciar entre expression y statements.
• Diferenciar entre tipos de datos atómicos y estructurados.
• Uso de callbacks.
• Consumo de Promesas.
• Creación de Promesas.

Node

• Uso de sistema de archivos. (fs, path)
• Instalar y usar módulos. (npm)
• Creación de modules. (CommonJS)
• Configuración de package.json.
• Configuración de npm-scripts
• Uso de CLI (Command Line Interface - Interfaz de Línea de Comando)

Testing

• Testeo unitario.
• Testeo asíncrono.
• Uso de librerias de Mock.
• Uso de Mocks manuales.
• Testeo para múltiples Sistemas Operativos.

Estructura del código y guía de estilo

• Organizar y dividir el código en módulos (Modularización)
• Uso de identificadores descriptivos (Nomenclatura | Semántica)
• Uso de linter (ESLINT)

Git y GitHub

• Uso de comandos de git (add | commit | pull | status | push)
• Manejo de repositorios de GitHub (clone | fork | gh-pages)
• Colaboración en Github (branches | pull requests | |tags)
• Organización en Github (projects | issues | labels | milestones)
• Probar issues y pull request

HTTP

• Verbos HTTP (http.get)

Fundamentos de programación

• Recursión.

6. Checklist

General

• Puede instalarse via npm install --global <github-user>/md-links

README.md

• Un board con el backlog para la implementación de la librería.
• Documentación técnica de la librería.
• Guía de uso e instalación de la librería

API mdLinks(path, opts)

• El módulo exporta una función con la interfaz (API) esperada.
• Implementa soporte para archivo individual
• Implementa soporte para directorios
• Implementa options.validate

CLI

• Expone ejecutable md-links en el path (configurado en package.json)
• Se ejecuta sin errores / output esperado
• Implementa --validate
• Implementa --stats

Pruebas / tests

• Pruebas unitarias cubren un mínimo del 70% de statements, functions, lines, y branches.
• Pasa tests (y linters) (npm test).