Markdown Links

Index

• 1. Preamble
• 2. Project Summary
• 3. Planning
• 4. Installation
• 5. User Manual
• 6. Unit Tests

1. Preamble

Markdown is a markup language very popular among developers. It's used in many platforms that handle plain text (GitHub, forums, blogs, ...) and it's very common to find multiple files in that format in any kind of repository (starting with the traditional README.md).

These Markdown files usually contain links that many times are broken or are no longer valid. This greatly damages the value of the information you want to share.

2. Project Summary

I developed a JavaScript library that reads files in Markdown format, from which it can be verified, through HTTP requests, if the links contained in these files are valid and report relevant information about them, for example, the total number of links and if they'r repeated or broken.

This API uses as dependencies:

• Axios
• Cheerio
• Marked

For the execution of this library, called mdLinks, I developed a command line tool (CLI), which accepts as arguments the options to validate and/or obtain statistics of the links in question.

For the CLI the dependencies are used:

• Colors
• Yargs

3. Planning

As a starting point for the development of this project, I iterated on a flowchart that was created contemplating the minimum elements necessary to cover by the API.

4. Installation

npm i md-links-gchm and configure an alias for the cli execution

or

npm i -D md-links-gchm and then run with npx mdlinks [options]

Whereas to import the module with CommonJS Modules use require/module.exports.

5. User Manual

The mdLinks library is executed and receives arguments from the command line (CLI): mdLinks path options

The path argument refers to the path of the markdown file or the directory containing markdown files, this argument is required.

While options refers to the optional arguments of validation and/or statistics of the links contained in the markdown.

• mdLinks path --validate
• mdLinks path --stats
• mdLinks path --validate --stats

As a support element, I included as an argument --help in the command line. If used, a summary of how to use the library is displayed (mdLinks path --help).

Here are some examples of the visualization of these different options:

mdLinks path !options

mdLinks path --validate

mdLinks path --stats

mdLinks path --validate --stats

mdLinks --help

6. Unit Tests

In order to verify the correct functioning of the API and to procure its optimization, unit tests were developed and implemented of the different functions that make up the library.