Markdown Links

Índice

• 1. Preámbulo
• 2. Primeros pasos
• 3. API de la librería
• 4. Entregables
• 5. Hacker edition

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.

2. Primeros pasos

La librería Marckdown-read-link nos permite analizar archivos en formato Markdown, para validar los links que contenga y reportar algunas estadísticas usando Node.js.

Mediante npm se hace la instalación de la librería

> npm i markdown-read-links

Cuando la librería este instalada, deberá ingresar mediante la terminal las siguientes series de comandos para hacer el uso correcto de la librería.

Para poder obtener los links de un archivo markdown o archivos markdown que se encuentren en un directorio, el comando básico que debe de ingresar es:

> mdLink <path>

Si desea obtener los links de un archivo markdown ingrese el path de ubicación del archivo, se recomienda ingresar un path relativo, ejemplo: > mdLink ./doc/example.md

Si desea obtener los links de un directorio que contiene archivos markdown, ingrese un path relativo de la ubicación del directorio, ejemplo: > mdLink ./doc/

Si desea usar un path absoluto, se recomienda escribirlo entre comillas dobles o simples.

Ejemplo gráfica de resultados por consola

Si desea validar los links encontrados en el archivo o directorio ingrese el siguiente comando:

> mdLink <path> --validate

Ejemplo gráfica de resultados por consola

Si desea obtener estadistica de los links encontrados (Total de links y links únicos) en el/los archivos markdown, ingrese el siguiente comando:

> mdLink <path> --stats

Ejemplo gráfica de resultados por consola

Si quieres obtener estadistica y validación de los links encontrados en el/los archivos markdown ingrese la siguiente combinación de comandos:

> mdLink <path> --stats --validate

El orden de los comandos --stats y --validate no difiere en la obtención de los resultados.

Ejemplo gráfica de resultados por consola

Si necesita ayuda ingrese el comando --help seguido del comando mdLink

> mdLink --help

Ejemplo gráfica de resultados por consola

3. API de la librería

Si desea modificar la librería, puede requerir el API de la siguiente manera:

const API = require('markdown-read-links/src/mdLinks');

API.mdLinks('./readmes/curve/readme2.md',false).then((msg) => {
console.log(msg);
});

el API tiene una función llamada mdLinks que recibe dos parametros, un String y Boolean, el primer parámetro debe de ser una ruta que apunte al archivo markdown que desea analizar; el segundo parámetro puede ser: false/true, si no desea validar los links, ingrese false como segundo parámetro de lo contrario ingrese true. La función mdLinks retorna una promesa que debe de ser consumida para poder visualizar los resultados.

Ejemplo gráfica de resultados por consola

4. Entregables

Módulo instalable via npm install <github-user>/md-links. Este módulo debe incluir tanto un ejecutable como una interfaz que podamos importar con require para usarlo programáticamente.

5. Hacker edition

Las secciones llamadas Hacker Edition son opcionales. Si terminaste con todo lo anterior y te queda tiempo, intenta completarlas. Así podrás profundizar y/o ejercitar más sobre los objetivos de aprendizaje del proyecto.

• Puedes agregar la propiedad line a cada objeto link indicando en qué línea del archivo se encontró el link.
• Puedes agregar más estadísticas.
• Integración continua con Travis o Circle CI.