astridtimana-md-links v0.1.3
Markdown Links
Índice
1. Preámbulo
Markdown es un lenguaje de marcado ligero muy popular entre developers. Es usado en muchs 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. Resumen del proyecto
El proyecto MDLinks crea una librería usando Node JS, que lee y analiza archivos en formato Markdown
, para verificar los links que contengan y reportar algunas estadísticas, así como una herramienta de línea de comando (CLI).
2.1. Diagramas de Flujo
A. API
B. CLI
3. Guía de Uso
Para la instalación, usar el siguiente comando:
npm i astridtimana-md-links
El ejecutable de la aplicación se ejecuta de la siguiente manera a través de la terminal:
md-links <path-to-file> [options]
Options
--stats
Si pasamos la opción '-s' o '--stats', el output (salida) será un texto con estadísticas básicas sobre los links.
$ md-links ./some/example.md --stats
Por ejemplo:
--validate
Si pasamos la opción '--validate' o '-v' o 'validate link', 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.
$ md-links ./some/example.md --validate
Por ejemplo:
--statsValidate
También podemos combinar --stats y --validate o pasarla opción '-a' para obtener estadísticas que necesiten de los resultados de la validación.
$ md-links <path-to-file> --stats --validate
Por ejemplo:
No Option
Si no se ingresa una opción, por default se identifica al archivo markdown (a partir de la ruta que recibe como argumento), analiza , e imprimevlos links que vaya encontrando, junto con la ruta del archivo donde aparece y el texto que hay dentro del link (truncado a 50 caracteres).
$ md-links <path-to-file>
Por ejemplo:
--help
Si se desea conocer los comandos a usar, se debe ingresar elcomando '-h' o '--help' (sin ingresar el 'path') , de la siguiente forma:
$ md-links --help
Por ejemplo:
4. 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
- 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 librerias de Mock.
- Uso de Mocks manuales.
- Testeo para múltiples Sistemas Operativos.
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)
Fundamentos de programación
5. 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 enpackage.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
).