Markdown Links

Index

• 1. Introduction
• 2. Project Summary
• 3. General Considerations
• 4. Usage Instructions
• 5. Project Planning
• 6. Learning Objectives

1. Introduction

Markdown is a lightweight markup language widely used among developers. It is used in many platforms that handle plain text (such as GitHub, forums, blogs, etc.), and it is common to find multiple files in that format in any type of repository (starting with the traditional README.md file).

These Markdown files often contain links that are sometimes broken or no longer valid, which greatly diminishes the value of the shared information.

Within an open-source community, we have been tasked with creating a tool using Node.js that reads and analyzes Markdown files, verifies the links they contain, and reports some statistics.

2. Project Summary

This project is a command-line tool (CLI) / JavaScript library that is executed using Node.js.

Node.js is a runtime environment for JavaScript built on the Chrome V8 JavaScript engine. It allows running JavaScript in the operating system environment, either on a machine or a server, opening the doors to interact with the system itself, files, networks, etc.

3. General Considerations

• This project was completed individually.

• The estimated time range to complete the project was 4 to 5 Sprints, and it was completed in 2.5 Sprints.

• Compatibility was verified in the Linux, Mac and Windows execution environments.

• The library and the executable script (command-line tool - CLI) are implemented in JavaScript to be run with Node.js. External libraries like path, FS, Axios, JSDOM, chalk, and marked were used.

• The module is installable via npm install karlamacedo-md-links.

• For this project, the use of async/await was not allowed.

• The asynchronous version was used to read files.

• ES Modules (import/export) were used with the help of babel.

• To reduce the complexity of the recursive algorithm, the synchronous version of the function to read directories, readdirSync, was used.

4. Usage Instructions

Installation

To install the library, run the following command in the terminal:

npm install karlamacedo-md-links

Usage in the Terminal

To use the library through the terminal, use the following command:

npx karlamacedo-md-links <path-to-file> [options]

Replace <path-to-file> with the path (absolute or relative) of the file or directory you want to process. Replace [options] with the action you want to perform:

Options

If no options are provided (npx karlamacedo-md-links <path-to-file>), it will return the .md files found and the links contained within each file. If no links or files are found, a notification will be displayed.

If only the --valid option is provided (npx karlamacedo-md-links <path-to-file> --valid), it will return the .md files found, the links contained within each file, and validate them through an HTTP request. It will also return their status codes, displaying an "OK ✔" notification for successful requests and a "Fail ✘" notification otherwise. If no links or files are found, a notification will be displayed.

If only the --stats option is provided (npx karlamacedo-md-links <path-to-file> --stats), it will return the .md files found and the links contained within each file. If no links or files are found, a notification will be displayed. Additionally, it will display a statistics section showing the total number of links found in the search and how many of them are unique.

If the --valid and --stats options are provided (npx karlamacedo-md-links <path-to-file> --valid --stats), it will return the .md files found, the links contained within each file, validate them through an HTTP request, and display their status codes with an "OK ✔" notification for successful requests and a "Fail ✘" notification otherwise. If no links or files are found, a notification will be displayed. Additionally, it will display a statistics section showing the total number of links found in the search, how many of them are unique, how many were successful in the HTTP request, and how many were not.

Usage as an API

To use the library as an API (Application Programming Interface), follow these steps:

• Fork the GitHub repository.

• Open your terminal and navigate to the location where you want to save the project using the cd command.

• Run the following command:

git clone https://github.com/karlamacedoedo/DEV007-md-links.git

• Open the project folder in your preferred code editor.

• Open the terminal and execute the project using the following commands, depending on the desired action:

Opciones

If no options are provided (node cli.js <path-to-file>), it will return the .md files found and the links contained within each file. If no links or files are found, a notification will be displayed.

If only the --valid option is provided (node cli.js <path-to-file> --valid), it will return the .md files found, the links contained within each file, and validate them through an HTTP request. It will also return their status codes, displaying an "OK ✔" notification for successful requests and a "Fail ✘" notification otherwise. If no links or files are found, a notification will be displayed.

If only the --stats option is provided (node cli.js <path-to-file> --stats), it will return the .md files found and the links contained within each file. If no links or files are found, a notification will be displayed. Additionally, it will display a statistics section showing the total number of links found in the search and how many of them are unique.

If the --valid and --stats options are provided (node cli.js <path-to-file> --valid --stats), it will return the .md files found, the links contained within each file, validate them through an HTTP request, and display their status codes with an "OK ✔" notification for successful requests and a "Fail ✘" notification otherwise. If no links or files are found, a notification will be displayed. Additionally, it will display a statistics section showing the total number of links found in the search, how many of them are unique, how many had successful HTTP requests, and how many had failed requests.

5. Project Planning

This project was planned using GitHub Projects, creating issues, labels, and milestones.

A flowchart was also previously created as a guide for the development of the logic of the project.

6. Learning Objectives

JavaScript

• [✓] Distinguish between primitive and non-primitive data types

• [✓] Arrays

  • Arreglos
  • Array - MDN
  • Array.prototype.sort() - MDN
  • Array.prototype.forEach() - MDN
  • Array.prototype.map() - MDN
  • Array.prototype.filter() - MDN
  • Array.prototype.reduce() - MDN

• [✓] Objects (key, value)

  • Objetos en JavaScript

• [✓] Use of conditionals (if-else, switch, ternary operator, boolean logic)

  • Estructuras condicionales y repetitivas
  • Tomando decisiones en tu código — condicionales - MDN

• [✓] Functions (params, args, return)

  • Funciones (control de flujo)
  • Funciones clásicas
  • Arrow Functions
  • Funciones — bloques de código reutilizables - MDN

• [✓] Recursion

  • Píldora recursión - YouTube Laboratoria Developers
  • Recursión o Recursividad - Laboratoria Developers en Medium

• [✓] CommonJS Modules

  • Modules: CommonJS modules - Node.js Docs

• [✓] Distinguish between expressions and statements

• [✓] Callbacks

  • Función Callback - MDN

• [✓] Promises

  • Promise - MDN
  • How to Write a JavaScript Promise - freecodecamp (en inglés)

• [✓] Unit Testing

  • Empezando con Jest - Documentación oficial

• [✓] Asynchronous Testing

  • Tests de código asincrónico con Jest - Documentación oficial

• [ ] Use of Mocks and Spies

  • Manual Mocks con Jest - Documentación oficial

• [ ] Compatibility Testing in Multiple Execution Environments

• [✓] Use of linter (ESLint)

• [✓] Use of descriptive identifiers (Naming and Semantics)

Node.js

• [✓] Install and Use Modules with npm

  • Sitio oficial de npm (en inglés)

• [✓] Package.json Configuration

  • package.json - Documentación oficial (en inglés)

• [✓] npm-scripts Configuration

  • scripts - Documentación oficial (en inglés)

• [✓] process (env, argv, stdin-stdout-stderr, exit-code)

  • Process - Documentación oficial (en inglés)

• [✓] File system (fs, path)

  • File system - Documentación oficial (en inglés)
  • Path - Documentación oficial (en inglés)

Version Control (Git y GitHub)

• [✓] Git: Installation and Configuration

• [✓] Git: Version Control with Git (init, clone, add, commit, status, push, pull, remote)

• [✓] Git: Integration of Changes Between Branches (branch, checkout, fetch, merge, reset, rebase, tag)

• [✓] GitHub: Account Creation and Repositories, SSH Key Configuration

• [✓] GitHub: Collaboration on Github (branches | forks | pull requests | code review | tags)

• [✓] GitHub: Organization on Github (projects | issues | labels | milestones | releases)

HTTP

• [✓] Request and Response

  • Generalidades del protocolo HTTP - MDN
  • Mensajes HTTP - MDN

• [✓] HTTP Status Codes

  • Códigos de estado de respuesta HTTP - MDN
  • The Complete Guide to Status Codes for Meaningful ReST APIs - dev.to