Markdown Links

Índice

• 1. Preámbulo
• 2. Resumen del proyecto
• 3. Implementación y uso
• 4. Objetivos de aprendizaje
• 5. Checklist

---

1. Preámbulo

Markdown es un lenguaje de marcado ligero muy popular entre developers. Es usado en muchísimas plataformas que manejan texto plano 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. Resumen del proyecto

En este proyecto se creó una librería usando Node.js. Esta librería lee y analiza archivos en formato Markdown (.md) y verificar los links que contengan. También cuenta la cantidad de links totales, únicos, rotos y los que funcionan correctamente.

En este proyecto se desarrolló una línea de comando (CLI) así como una librería (library) en JavaScript, se utilizó la API 'fetch' para realizar peticiones HTTP asincrónas.

3. Implementación y uso

mdLinks(path, options)

Para utilizar esta librería utiliza el siguiente comando:

npm install cheilanthes/md-links

Argumentos

mdLinks(path)

Puedes utilizar esta librería para ver los links que contiene tu marckdown. Debes poner el comando mdLinks(path)

• path: Ruta absoluta o relativa al archivo o directorio. Si la ruta pasada es relativa, debes estar posicionado en el sitio dónde se encuentra dicho archivo, de lo contrario debes colocar el path absoluto.

D_Elizabeth@Elizabeth MINGW64 ~/laboratoria/proyecto4/DEV003-md-links (main)
$ md-links
WELCOME! This library validate the URL. Please enter a path
if you need help use the following commands: -help or -h

option --hep -h

PS C:\Users\D_Elizabeth\Laboratoria\proyecto4\DEV003-md-links> md-links -help
To use this library you must write an absolute or a relative path
Example with path abs: md-links C:/Users/Users/Laboratoria/proyectos/social-network/README.md
Example with path relative: md-links ./DEV003-social-network/README.md
Also you can use the options --validate  for request the http status, and --stast to count valid, unique or broken links.

default

 C:\Users\D_Elizabeth\Laboratoria\proyecto4\DEV003-md-links> md-links C:\Users\D_Elizabeth\Laboratoria\proyecto4\DEV003-md-links\pruebas\PRUEBA1.md
path: C:\Users\D_Elizabeth\Laboratoria\proyecto4\DEV003-md-links\pruebas\PRUEBA1.md link: https://es.wikipedia.org/wiki/Markdown host: es.wikipedia.org
path: C:\Users\D_Elizabeth\Laboratoria\proyecto4\DEV003-md-links\pruebas\PRUEBA1.md link: https://nodejs.org/ host: nodejs.org
path: C:\Users\D_Elizabeth\Laboratoria\proyecto4\DEV003-md-links\pruebas\PRUEBA1.md link: https://css-tricks.com/oohcrap host: css-tricks.com
path: C:\Users\D_Elizabeth\Laboratoria\proyecto4\DEV003-md-links\pruebas\PRUEBA1.md link: https://css-tricks.com/oohcrap host: css-tricks.com

• path: Ruta del archivo donde se encontró el link. link: URL encontrada. host: Texto que aparecía dentro del link (<a>).

option --validate

Si pasamos la opción --validate, se hace una petición HTTP para averiguar si el link funciona o no. Por ejemplo:

• status: Código de respuesta HTTP (200, 400, etc.).
• ok: Mensaje fail en caso de fallo u ok en caso de éxito. Ejemplo:

C:\Users\D_Elizabeth\Laboratoria\proyecto4\DEV003-md-links> md-links C:\Users\D_Elizabeth\Laboratoria\proyecto4\DEV003-md-links\pruebas\PRUEBA1.md --validate
(node:12536) ExperimentalWarning: The Fetch API is an experimental feature. This feature could change at any time
(Use `node --trace-warnings ...` to show where the warning was created)
path: C:\Users\D_Elizabeth\Laboratoria\proyecto4\DEV003-md-links\pruebas\PRUEBA1.md link: https://es.wikipedia.org/wiki/Markdown status 200 ok host: es.wikipedia.org
path: C:\Users\D_Elizabeth\Laboratoria\proyecto4\DEV003-md-links\pruebas\PRUEBA1.md link: https://nodejs.org/ status 200 ok host: nodejs.org
path: C:\Users\D_Elizabeth\Laboratoria\proyecto4\DEV003-md-links\pruebas\PRUEBA1.md link: https://css-tricks.com/oohcrap status 404 fail host: css-tricks.com 
path: C:\Users\D_Elizabeth\Laboratoria\proyecto4\DEV003-md-links\pruebas\PRUEBA1.md link: https://css-tricks.com/oohcrap status 404 fail host: css-tricks.com 

• path: Ruta del archivo donde se encontró el link. link: URL encontrada. status: Código de respuesta HTTP. host: Texto que aparecía dentro del link (<a>).

option --stats

Si pasamos la opción --stats el output (salida) será un texto con estadísticas básicas sobre los links. Por ejemplo:

PS C:\Users\D_Elizabeth\Laboratoria\proyecto4\DEV003-md-links> md-links C:\Users\D_Elizabeth\Laboratoria\proyecto4\DEV003-md-links\pruebas\PRUEBA1.md --stats
Total: 4 Links uniques:  3

option --stats --validate

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

PS C:\Users\D_Elizabeth\Laboratoria\proyecto4\DEV003-md-links> md-links C:\Users\D_Elizabeth\Laboratoria\proyecto4\DEV003-md-links\pruebas\PRUEBA1.md --stats --validate
Total: 4 Links ok: 2 Links broken: 2

4. Objetivos de aprendizaje

A continuación se marcan los objetivos que se lograron entender y aplicar:

JavaScript

• Diferenciar entre tipos de datos primitivos y no primitivos

• Arrays (arreglos)

  Links

  • Arreglos
  • Array - MDN
  • Array.prototype.sort() - MDN
  • Array.prototype.forEach() - MDN
  • Array.prototype.map() - MDN
  • Array.prototype.filter() - MDN
  • Array.prototype.reduce() - MDN

• Objetos (key, value)

  Links

  • Objetos en JavaScript

• Uso de condicionales (if-else, switch, operador ternario, lógica booleana)

  Links

  • Estructuras condicionales y repetitivas
  • Tomando decisiones en tu código — condicionales - MDN

• Funciones (params, args, return)

  Links

  • Funciones (control de flujo)
  • Funciones clásicas
  • Arrow Functions
  • Funciones — bloques de código reutilizables - MDN

• Recursión o recursividad

  Links

  • Píldora recursión - YouTube Laboratoria Developers
  • Recursión o Recursividad - Laboratoria Developers en Medium

• Módulos de CommonJS

  Links

  • Modules: CommonJS modules - Node.js Docs

• Diferenciar entre expresiones (expressions) y sentencias (statements)

• Callbacks

  Links

  • Función Callback - MDN

• Promesas

  Links

  • Promise - MDN
  • How to Write a JavaScript Promise - freecodecamp (en inglés)

• Pruebas unitarias (unit tests)

  Links

  • Empezando con Jest - Documentación oficial

• Pruebas asíncronas

  Links

  • Tests de código asincrónico con Jest - Documentación oficial

• Uso de mocks y espías

  Links

  • Manual Mocks con Jest - Documentación oficial

• Pruebas de compatibilidad en múltiples entornos de ejecución

• Uso de linter (ESLINT)

• Uso de identificadores descriptivos (Nomenclatura y Semántica)

Node.js

• Instalar y usar módulos con npm

  Links

  • Sitio oficial de npm (en inglés)

• Configuración de package.json

  Links

  • package.json - Documentación oficial (en inglés)

• Configuración de npm-scripts

  Links

  • scripts - Documentación oficial (en inglés)

• process (env, argv, stdin-stdout-stderr, exit-code)

  Links

  • Process - Documentación oficial (en inglés)

• File system (fs, path)

  Links

  • File system - Documentación oficial (en inglés)
  • Path - Documentación oficial (en inglés)

Control de Versiones (Git y GitHub)

• Git: Instalación y configuración

• Git: Control de versiones con git (init, clone, add, commit, status, push, pull, remote)

• Git: Integración de cambios entre ramas (branch, checkout, fetch, merge, reset, rebase, tag)

• GitHub: Creación de cuenta y repos, configuración de llaves SSH

• GitHub: Colaboración en Github (branches | forks | pull requests | code review | tags)

• GitHub: Organización en Github (projects | issues | labels | milestones | releases)

HTTP

• Consulta o petición (request) y respuesta (response).

  Links

  • Generalidades del protocolo HTTP - MDN
  • Mensajes HTTP - MDN

• Códigos de status de HTTP

  Links

  • Códigos de estado de respuesta HTTP - MDN
  • The Complete Guide to Status Codes for Meaningful ReST APIs - dev.to

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