sj-mdlinks

Validator of links contained only in md files

Usage no npm install needed!

<script type="module">
  import sjMdlinks from 'https://cdn.skypack.dev/sj-mdlinks';
</script>

README

Markdown Links

Índice

Descripción

sj-mdlinks es una libreria que usa Node.js Contiene una función recursiva que recibe como parámetro una ruta, localiza todos los archivos con extensión .md que esten dentro de la ruta proporcionada (incluyendo subdirectorios), verifica los links que contenga cada archivo, valida su status (ok, fail) y calcula estadisticas básicas sobre los links (totales, únicos y rotos).


Homepage

Github StephanieJolianis


Diagrama de flujo


Instalación y uso (CLI)

Linux o MacOS

$ sudo npm i -g sj-mdlinks

Microsoft Windows

$ npm i -g sj-mdlinks

Ejecución de comandos:

Puedes ejecutar la aplicación de la siguiente manera a través de la terminal md-links [options]

Por ejemplo:
  • Para obtener links

Aquí puedes utilizar una ruta de un archivo con una extensión .md o una ruta de un directorio.

Comando:

$ mdlinks hola.md

Retorno:

[ { file: '/home/stephanie/Escritorio/pruebas-mdlinks/hola.md',
    href: 'https://www.npmjs.com/package/sj-mdlinks',
    text: 'Stephanie' },
  { file: '/home/stephanie/Escritorio/pruebas-mdlinks/hola.md',
    href: 'https://otra-cosa.net/algun-doc.html',
    text: 'Link roto' } ]
  • Options
--validate

Si pasas la opción --validate, el módulo hace 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 se considera el link como ok.

Comando:

$ mdlinks hola.md --validate

Retorno:

[ { href: 'https://www.npmjs.com/package/sj-mdlinks',
    text: 'Stephanie',
    file: '/home/stephanie/Escritorio/pruebas-mdlinks/hola.md',
    code: 200,
    status: 'OK' },
  { href: 'https://otra-cosa.net/algun-doc.html',
    text: 'Link roto',
    file: '/home/stephanie/Escritorio/pruebas-mdlinks/hola.md',
    code: 404,
    status: 'FAIL' } ]
--stats

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

Comando:

$ mdlinks hola.md --stats

Retorno:

[ total: 2, unique: 2 ]

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

Comando:

$ mdlinks hola.md --validate --stats

Retorno:

[ total: 2, unique: 2, broken: 1, ok: 1 ]

Instalación y uso (MÓDULO)

Instalar como dependencia npm

$ npm i sj-mdlinks

Ejemplo uso del módulo


const mdlinks = require("sj-mdlinks");

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

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

//Obtener estadísticas [{ total, unique }]
mdlinks("./some/example.md", { validate: false, stats: true })
  .then(links => {
    console.log(links)
  })
  .catch(console.error);

//Obtener estadísticas y validación de links [{ total, unique, broken, ok }]
mdlinks("./some/example.md", { validate: true, stats: true })
  .then(links => {
    console.log(links)
  })
  .catch(console.error);

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)

HTTP

Fundamentos de programación


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