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.

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.

2. Como usarlo

---

Instalar CLI

$ npm install -g angelicabonilla/md-links

Uso CLI

Recibe como argumento un archivo ".md" o una carpeta que contenga un archivo ".md".

Al ejecutar el comando, te imprime un arreglo de objetos con las url, la referencia dada al enlace, el archivo donde se encontró el enlace

$ md-links ./README.md

   {
   href: 'https://es.wikipedia.org/wiki/Markdown',
   text: 'Markdown',
   file: 'C:\\Users\\angel\\Documents\\Repositories\\bog001-md-links\\README.md'
 },

Si ejecutas el comando con --validate, verifica el status de los links

$ md-links ./README.md --validate

  {
   href: 'https://nodejs.org/api/fs.html#fs_fs_readfile_path_options_callback',
   text: 'Leer un archivo',
   file: 'C:\\Users\\angel\\Documents\\Repositories\\bog001-md-links\\README.md',
   status: 200,
   ok: true
 },

Si ejecutas el comando con --stats, te muestra cuantos enlaces hay en total y cuantos son únicos

$ md-links ./README.md --stats

 {
   href: 'https://medium.com/netscape/a-guide-to-create-a-nodejs-command-line-package-c2166ad0452e',
   text: 'Linea de comando CLI',
   file: 'C:\\Users\\angel\\Documents\\Repositories\\bog001-md-links\\README.md'
 }
] { total: 51, unique: 46 }

Si ejecutas el comando con --validate --stats, verifica el status de los links y te imprime cuantos enlaces hay en total, cuantos son únicos y cuantos están rotos

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

{
   href: 'https://medium.com/netscape/a-guide-to-create-a-nodejs-command-line-package-c2166ad0452e',
   text: 'Linea de comando CLI',
   file: 'C:\\Users\\angel\\Documents\\Repositories\\bog001-md-links\\README.md',
   status: 200,
   ok: true
 }
] { total: 51, unique: 46, broken: 1 }

Instalar como Modulo

Github Packages $ npm install @angelicab7/md-links

Uso del Modulo

const mdlinks = require('@angelicab7/md-links')

Muestra un arreglo de objetos con las url y el archivo donde se encontró el enlace

mdlinks('./README.md')
  .then((res) => {
    console.log(res);
  })

Muestra un arreglo de objetos con las url, el archivo donde se encontró el link y verifica cada uno de los links, imprimiendo así el status de cada link

mdlinks('./README.md', { validate: true})
  .then((res) => {
    console.log(res);
  })

Devuelve las estadísticas de los links en el archivo, cuantos hay en total y cuantos son únicos

mdlinks('./README.md', { stats: true})
  .then((res) => {
    console.log(res);
  })

Muestra las estadísticas de los links en el archivo, cuantos hay en total, cuantos son únicos y cuales están rotos

mdlinks('./README.md', { validate: true, stats: true})
  .then((res) => {
    console.log(res);
  })

---

3. 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)

HTTP

• Verbos HTTP (http.get)

Fundamentos de programación

• Recursión.

• 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).