@jobysalex/mdlinks NPM

npm.io .

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.

Entonces esta herramienta, creada con Node.js, lee y analiza archivos en formato Markdown, para verificar los links que contengan y reportar algunas estadísticas.

md-links

2. Proceso de desarrollo:

Como punto de partida para la ejecución de este proyecto, se elaboró la lógica y se diseñó un diagrama de flujo para organizar el proceso.

En este proyecto use la herramienta de planificación y organización de GitHub llamada Github Projects.

Utilice para el desarrollo de este proyecto: CommonJS Modules, es decir, require/module.exports

3. Resumen del proyecto

En este proyecto se ha desarrollado un programa que se ejecutará en la terminal o consola. Para utilizar este, se puede con comandos específicos que he diseñado y programado en la misma línea de comandos.

Estos comandos nos permitirán acceder a los enlaces presentes en archivos o directorios, osea lee y analiza archivos en formato Markdown, para obtener el total de enlaces, identificar enlaces únicos y encontrar enlaces rotos.

4. Que es `mdLinks(path, options)`

Esta es una función llamada mdLinks(path, options) que devuelve una promesa, recibiendo dos parámetros:

path que puede ser la ruta absoluta o relativa a un archivo o directorio. options que puede ser:

**** --validate el módulo debe hacer una petición HTTP para averiguar si el link funciona o no y obtendriamos:

Con validate:false osea si no lo colocamos tendremos:

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

Con validate:true osea si lo colocamos tendremos:

* `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.

**** --stats: entonces si colocamos --stats la salida será un texto con estadísticas básicas sobre los links asi:

`{Total: 3, Unique: 3}`
    * `href`: URL encontrada.
    * `text`: Texto que aparecía dentro del link (`<a>`).
    * `file`: Ruta del archivo donde se encontró el link.

**** --validate --stats: entonces si colocamos las dos al tiempo, te agrega el número de links que están rotos o no funcionan correctamente, donde: Total: seria el número total de links encontrados en el archivo o directorio. Unique: seria el número de links únicos, es decir, aquellos que no se repiten. Broken: seria el número de links que están rotos o no funcionan correctamente. por tanto obtendriamos:

 `{Total: 3, Unique: 3, Broken: 1}`
     * `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.

5. Modo de uso

Debes ingresar la ruta del archivo o directorio de la sigueinte manera:

Si ejecutas: md-links , el módulo hará una petición HTTP para averiguar si los links funcionan o no. Nos debe dar: href, text, file; se mostrarán estadísticas que también requieren los resultados de validación de los links.
Si se usa md-links --validate el módulo hará una petición HTTP para averiguar si los links funcionan o no. Nos debe dar: href, text, file, status y mensaje OK o FAIL.
Si utilizas el comando md-links --stats, recibirás los links y un texto que proporciona estadísticas básicas sobre los links encontrados en el archivo o directorio especificado. Nos debe dar: href, text, file, Total y Unique.
Si ejecutas el comando md-links --validate --stats , se mostrarán: href, text, file, status,
mensaje OK o FAIL, Total, Unique y Broken

6. Tutoriales y Recursos

7. Archivos del proyecto

README.md con descripción del módulo, instrucciones de instalación/uso, documentación del API y ejemplos. Todo lo relevante para que cualquier developer que quiera usar tu librería pueda hacerlo sin inconvenientes.
index.js: Desde este archivo debes exportar una función (mdLinks).
cli.js: En este archivo tendre las funciones.
test-file: Es un directorio con carpetas y archivos de prueba.
package.json con nombre, versión, descripción, autores, licencia, dependencias, scripts (pretest, test, ...), main, bin
.editorconfig con configuración para editores de texto. Este archivo no se debe cambiar.
.eslintrc con configuración para linter. Este archivo contiene una configuración básica para ESLint, si deseas agregar reglas adicionales como Airbnb deberás modificar este archivo.
.gitignore para ignorar node_modules u otras carpetas que no deban incluirse en control de versiones (git).
test/md-links.spec.js debe contener los tests unitarios para la función mdLinks(). Tu implementación debe pasar estos tests.