Skip to content

GloVillagran/DEV004-md-links

 
 

Repository files navigation

Markdown Links

Índice


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. Descripción

Es una herramienta de línea de comando(CLI) y una librería, que permite extraer los links de un archivo tipo Markdown(md), e identifica cuales están funcionando y cuales están rotos. Adicionalmente esta información se puede entregar al usuario como estadísticas donde se puede ver:

  • Total de links
  • Links únicos
  • Links rotos

3. Objetivos de aprendizaje

Objetivos aplicados en este proyecto.

JavaScript

  • Diferenciar entre tipos de datos primitivos y no primitivos

  • Arrays (arreglos)

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

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

    • Estructuras condicionales y repetitivas
    • Tomando decisiones en tu código — condicionales - MDN
  • Funciones (params, args, return)

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

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

  • Promesas

  • Pruebas unitarias (unit tests)

    • Jest
  • Pruebas asíncronas

    • Tests de código asincrónico con Jest
  • 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

  • Configuración de package.json

  • Configuración de npm-scripts

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

  • File system (fs, path)

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

  • Códigos de status de HTTP

4. Diagramas de flujo

  • API

Imagen Diagrama API

  • CLI

Imagen Diagrama API

5. Instalación

Mediante npm, colocando en la terminal:

npm i glovillagran-mdlinks

6. Uso

Este proyecto consta de DOS partes:

1) JavaScript API

Esta es una funcion que retorna una promesa mdLinks(path, options) que recibe dos parámetros: path (ruta absoluta o relativa) y options ({validate: true} o {validate: false}) que retorna un array de objetos por cada link.

Valor de retorno

Con validate:false :

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

Con validate:true :

  • href: URL encontrada.
  • text: Texto que aparecía dentro del link (<a>).
  • file: Ruta del archivo donde se encontró el link.
  • status: Código de respuesta HTTP.
  • ok: Mensaje fail en caso de fallo u ok en caso de éxito.

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

El ejecutable de nuestra aplicación debe poder ejecutarse de la siguiente manera a través de la terminal:

Comando principal:

md-link

Para poder visualizar todas las opciones que tiene el recurso, se ejecuta:

md-link --help

Help

Para poder visualizar los links encontrados en el/los archivos md, se ejecuta sin pasar opciones, se obtendrá información de cada link encontrado. [{ href, text, file }]:

md-link <path-to-file>

Por ejemplo:

md-link'/Users/gloriavillagranrojas/Laboratoria DEV004/MDLinks/DEV004-md-links/md-files/prueba-Links.md'

Only Path

Options

Se debe ejecutar con las siguientes opciones:

md-links <path-to-file> [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.

Por ejemplo:

md-link '/Users/gloriavillagranrojas/Laboratoria DEV004/MDLinks/DEV004-md-links/md-files/prueba-Links.md' --validate

Validate

--stats

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

Por ejemplo:

md-link '/Users/gloriavillagranrojas/Laboratoria DEV004/MDLinks/DEV004-md-links/md-files/prueba-Links.md' --stats

Stats

--validate --stats

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

Por ejemplo:

md-link '/Users/gloriavillagranrojas/Laboratoria DEV004/MDLinks/DEV004-md-links/md-files/prueba-Links.md' --validate --stats

Validate Stats

7. Pruebas Unitarias

Se realizaron 20 test unitarios para cada una de las funciones de la API, como también para testear el funcionamiento completo de la función md-links.

Test

Coverage

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

About

No description, website, or topics provided.

Resources

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published

Languages

  • JavaScript 100.0%