fran-mdlinks
v1.0.2
Published
Show links and statistics of mdfiles
Downloads
6
Readme
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
- [x] Uso de condicionales (if-else | switch | operador ternario)
- [x] Uso de funciones (parámetros | argumentos | valor de retorno)
- [x] Manipular arrays (filter | map | sort | reduce)
- [x] Manipular objects (key | value)
- [x] Uso ES modules (
import
|export
) - [x] Diferenciar entre expression y statements.
- [x] Diferenciar entre tipos de datos atómicos y estructurados.
- [x] Uso de callbacks.
- [x] Consumo de Promesas.
- [x] Creación de Promesas.
Node
- [x] Uso de sistema de archivos. (fs, path)
- [x] Instalar y usar módulos. (npm)
- [x] Creación de modules. (CommonJS)
- [x] Configuración de package.json.
- [x] Configuración de npm-scripts
- [x] Uso de CLI (Command Line Interface - Interfaz de Línea de Comando)
Testing
- [x] Testeo unitario.
- [x] Testeo asíncrono.
- [x] Uso de librerias de Mock.
- [x] Uso de Mocks manuales.
- [x] Testeo para múltiples Sistemas Operativos.
Estructura del código y guía de estilo
- [x] Organizar y dividir el código en módulos (Modularización)
- [x] Uso de identificadores descriptivos (Nomenclatura | Semántica)
- [x] Uso de linter (ESLINT)
Git y GitHub
- [x] Uso de comandos de git (add | commit | pull | status | push)
- [x] Manejo de repositorios de GitHub (clone | fork | gh-pages)
- [x] Colaboración en Github (branches | pull requests | |tags)
- [x] Organización en Github (projects | issues | labels | milestones)
HTTP
- [x] Verbos HTTP (http.get)
Fundamentos de programación
- [x] 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
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
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 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
).