Skip to content

Latest commit

 

History

History
232 lines (169 loc) · 7.6 KB

README.md

File metadata and controls

232 lines (169 loc) · 7.6 KB
Raw

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

Testing

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

Fundamentos de programació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).