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. Resumen del proyecto
Md-links es un librería que es ejecutada en la terminal, en donde podemos ver los links de un archivo .md, con opción de ver el estado http de cada url y sus estadisticas.
3. Documentación técnica
Requerimientos
Tener instalado:
- node.js
- Npm
Instalación
$ npm i @ivvnv/md-links
Uso
Inserta en tu código
const mdLinks = require('@ivvnv/md-links')
En la terminal ingresa
node archivoQueLlamaMdLinks.js archivoMdALeer.md [options]
Opciones
--validate Arrojará una lista con los links y su status.
--stats Esta opción arroja las estadísticas básicas de los links.
--validate --stats Permitirá ejecutar ambas opciones.
CLI (Command Line Interface - Interfaz de Línea de Comando)
El ejecutable de nuestra aplicación se ejecuta de la siguiente manera a través de la terminal:
node archivoQueLlamaMdLinks.js archivoMdALeer.md [options]
Por ejemplo:
$ node index.js ./some/example.md
http://algo.com/2/3/ Link a algo
https://otra-cosa.net/algun-doc.html algún doc
http://google.com/ GoogleOptions
--validate | --v
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 consideramos el link como ok.
Por ejemplo:
$ node index.js ./some/example.md
--validate
http://algo.com/2/3/ ok 200 Link a algo
https://otra-cosa.net/algun-doc.html fail 404 algún doc
http://google.com/ ok 301 Google--stats | --s
Si pasas la opción --stats el output (salida) será un texto con estadísticas
básicas sobre los links.
$ node index.js ./some/example.md --stats
Total: 3
4. Planificación
Nuestra planificación fue en Trello y Miró, haciendo en esta última un product backlog y un spring backlog para un mayor orden a la hora de ir desarrollando el programa; también se crearon flujos por cada realease del product backlog que en conjuntos hacen las historias de usuario y el flujo de trabajo.
Flujogramas
Product Backlog
5. Checklist
General
Puede instalarse via
npm install --global <github-user>/md-linksUso 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)
Node
- Uso de sistema de archivos. (fs, path)
- Instalar y usar módulos. (npm)
- Creación de modules. (CommonJS)
- Configuración de package.json.
- Configuración de npm-scripts
- Uso de CLI (Command Line Interface - Interfaz de Línea de Comando)
Testing
- Testeo unitario.
- Testeo asíncrono.
- Uso de Mocks manuales.
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
- Verbos HTTP (http.get)