fran-mdlinks v1.0.2

Markdown Links

Resumen 📚

Es una librería que te permite extraer links de archivos md. De igual modo tambíen permite acceder a estadisticas como cantidad de links totales, únicos, válidos y rotos.

Índice

• 1. Diagrama de flujo
• 2. Instalación
• 3. Uso de mdLinks
• 4. Objetivos de aprendizaje
• 5. Pistas, tips y lecturas complementarias
• 6. Checklist

1. Diagrama de flujo 📝

1. Api

2. Cli

2. Instalación 💻💿

• Instalar la libreria via npm install fran-mdlinks

npm install fran-mdlinks

3. Uso de la mdLinks ⚙️

Detalles de la Api

mdLinks(path, options)

Argumentos

• path: Ruta absoluta o relativa al archivo o directorio. Si la ruta pasada es relativa, debe resolverse como relativa al directorio desde donde se invoca node - current working directory).

• options: Un objeto con las siguientes propiedades:

Valor de retorno

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

Ejemplo

const mdLinks = require("md-links");

mdLinks("./some/example.md")
  .then(links => {
    // => [{ href, text, file }]
  })
  .catch(console.error);

mdLinks("./some/example.md", { validate: true })
  .then(links => {
    // => [{ href, text, file, status, message }]
  })
  .catch(console.error);

mdLinks("./some/dir")
  .then(links => {
    // => [{ href, text, file }]
  })
  .catch(console.error);

CLI (Command Line Interface - Interfaz de Línea de Comando)

Ejecutar la aplicación en la terminal.

1. md-links <path-to-file>

Retorna listado de links.

2. md-links <path-to-file> [options]

Retorna estadisticas de acuerdo a la opción ingresada:

md-links <path-to-file> --validate

Verifica el funcionamiento de cada link.

md-links <path-to-file> --stats

Retorna un texto con estadísticas básicas sobre los links.

md-links <path-to-file> --validate --stats

Retorna estadísticas que necesitan de los resultados de la validación.

3. md-links --help

Muestra una guía básica.

4. Objetivos de aprendizaje 🤓

Diseñar tu propia librería es una experiencia fundamental para cualquier desarrollador porque que te obliga a pensar en la interfaz (API) de tus módulos y cómo será usado por otros developers. Debes tener especial consideración en peculiaridades del lenguaje, convenciones y buenas prácticas.

A continuación puedes ver los objetivos de aprendizaje de este proyecto:

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

• Recursión.

5. Pistas, tips y lecturas complementarias

FAQs

¿Cómo hago para que mi módulo sea instalable desde GitHub?

Para que el módulo sea instalable desde GitHub solo tiene que:

• Estar en un repo público de GitHub
• Contener un package.json válido

Con el comando npm install githubname/reponame podemos instalar directamente desde GitHub. Ver docs oficiales de npm install acá.

Por ejemplo, el course-parser que usamos para la currícula no está publicado en el registro público de NPM, así que lo instalamos directamente desde GitHub con el comando npm install Laboratoria/course-parser.

Sugerencias de implementación

La implementación de este proyecto tiene varias partes: leer del sistema de archivos, recibir argumentos a través de la línea de comando, analizar texto, hacer consultas HTTP, ... y todas estas cosas pueden enfocarse de muchas formas, tanto usando librerías como implementando en VanillaJS.

Por poner un ejemplo, el parseado (análisis) del markdown para extraer los links podría plantearse de las siguientes maneras (todas válidas):

• Usando un módulo como markdown-it, que nos devuelve un arreglo de tokens que podemos recorrer para identificar los links.
• Siguiendo otro camino completamente, podríamos usar expresiones regulares (RegExp).
• También podríamos usar una combinación de varios módulos (podría ser válido transformar el markdown a HTML usando algo como marked y de ahí extraer los link con una librería de DOM como JSDOM o Cheerio entre otras).
• Usando un custom renderer de marked (new marked.Renderer()).

No dudes en consultar a tus compañeras, coaches y/o el foro de la comunidad si tienes dudas existenciales con respecto a estas decisiones. No existe una "única" manera correcta :wink:

Tutoriales / NodeSchool workshoppers

• learnyounode
• how-to-npm
• promise-it-wont-hurt

Otros recursos

• Acerca de Node.js - Documentación oficial
• Node.js file system - Documentación oficial
• Node.js http.get - Documentación oficial
• Node.js - Wikipedia
• What exactly is Node.js? - freeCodeCamp
• ¿Qué es Node.js y para qué sirve? - drauta.com
• ¿Qué es Nodejs? Javascript en el Servidor - Fazt en YouTube
• ¿Simplemente qué es Node.js? - IBM Developer Works, 2011
• Node.js y npm
• Módulos, librerías, paquetes, frameworks... ¿cuál es la diferencia?
• Asíncronía en js
• NPM
• Publicar packpage
• Crear módulos en Node.js
• Leer un archivo
• Leer un directorio
• Path
• Linea de comando CLI

• Promise
• Comprendiendo Promesas en Js
• Pill de recursión - video
• Pill de recursión - repositorio

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