- 1. Introduction
- 2. Project definition
- 3. User guide
- 4. Unit tests
- 5. Planning
- 6. Requirements checklist
- 7. Tools and skills
Markdown is an lightweight markup language that is used with plain text to add formatting elements (headings, bulleted lists, URLs) to text without the use of a formal text editor or the use of HTML tags. Markdown is used in many platforms that handle plain text, such as Slack, forums, blogs, among others, so it's very common to find several files using this format in different kinds of repositories. We don't need to go that far to find examples of this, for instance, the classic README file, such as this very one, uses Markdown and you can verify that by checking the file's extension, which is ".md" and stands for Markdown documentation.
Usually these .md files, contains links that are often broken, or no longer accessible. This situation diminish the value of the information you are trying to share. That's why this project intends to tackle that problem by reading and analyzing Markdown files, verifying the links inside of them and creating a report with these links' stats.
This module is a library that can be used to retrieve all links, inside all markdown files that are present in a specific path (folder or file). Besides that, you can check the status of all the links retrieved and see a summary with the stats found on the analysis. Node JS was the javascript framework chosen to develop this tool. You can use this library as CLI application or as an API.
This library and the CLI use external libraries as dependencies (such as the path module, the FS module, the HTTP client Axios, and the terminal string styling API Chalk) and were developed with Javascript to be run with NodeJS. Babel, Eslint and Jest were also used for the developing/testing stages.
Open your terminal and run the following command:
npm i @sara-rioseco/md-links
Once the installation is complete, run the following command in your terminal:
npx @sara-rioseco/md-links <path> [options]
Where path is the route to the file or directory (it can be an absolute or relative path), and options are the additional actions you want to perform. Options are non mandatory, and the application will still run if only a path is provided. Possible options are: --validate, --stats, or both.
-
No options: if no options are entered , the application will show you all the links found in that path. If the path is not valid, or no .md file is found and error will appear.
npx @sara-rioseco/md-links <path>
-
Only --validate: if only the --validate option is entered, the application will show you all the links found and will check if they are valid through an HTTP request. The status code and a message of ok/fail will be added to each link. If the path is not valid, or no .md file is found and error will appear.
npx @sara-rioseco/md-links <path> --validate
-
Only --stats: if only the --stats option is entered, the application will show you all the links found and will add a message with the total links found, and how many of them are unique links (the ones that are not repeated). If the path is not valid, or no .md file is found and error will appear.
npx @sara-rioseco/md-links <path> --stats
-
--validate and --stats: if the --validate and --stats options are provided, the application will show you all the links found and will check if they are valid through an HTTP request. The status code and a message of ok/fail will be added to each link. Also, a message will be added at te end saying the total amount of links found, how many of them are unique links (the ones that are not repeated) and how many are broken. If the path is not valid, or no .md file is found and error will appear.
npx @sara-rioseco/md-links <path> --validate --stats
In order to use the library as an API, follow these steps:
-
Fork the GitHub Repository.
-
Open your terminal and use the cd command to go to the folder where you want to save the project.
-
Run the following command:
git clone https://github.com/sara-rioseco/DEV007-md-links.git
-
Open the folder you chose on your code editor software.
-
Open the terminal and you can start using the API.
Run the following command in your terminal:
node cli.js <path> [options]
Where path is the route to the file or directory (it can be an absolute or relative path), and options are the additional actions you want to perform. Options are non mandatory, and the application will still run if only a path is provided. Possible options are: --validate, --stats, or both.
-
No options: if no options are entered , the application will show you all the links found in that path. If the path is not valid, or no .md file is found and error will appear.
node cli.js <path>
-
Only --validate: if only the --validate option is entered, the application will show you all the links found and will check if they are valid through an HTTP request. The status code and a message of ok/fail will be added to each link. If the path is not valid, or no .md file is found and error will appear.
node cli.js <path> --validate
-
Only --stats: if only the --stats option is entered, the application will show you all the links found and will add a message with the total links found, and how many of them are unique links (the ones that are not repeated). If the path is not valid, or no .md file is found and error will appear.
node cli.js <path> --stats
-
--validate and --stats: if the --validate and --stats options are provided, the application will show you all the links found and will check if they are valid through an HTTP request. The status code and a message of ok/fail will be added to each link. Also, a message will be added at te end saying the total amount of links found, how many of them are unique links (the ones that are not repeated) and how many are broken. If the path is not valid, or no .md file is found and error will appear.
node cli.js <path> --validate --stats
Unit tests were run using Jest, achieving a 97.89% of statements, 94.87% of branches, 91.3% of functions and 100% of lines, considering both files tested. You can check the results below:
For the planning of this project, I used the Trello app and also GitHub Projects, Issues, Milestones and Boards. You can find an image of both tools below.
Also during this stage, I designed a flowchart of the main function of the project. There were at least 3 different versions of this flowchart, you can see the final version below.
- Can be installed with
npm install --global <github-user>/md-links
- Backlog board for the implementation.
- Technical documentation.
- Installation and usage guide.
- The module exports a function with the expected API.
- Individual file support implementation
- Folder support implementation
- Implementation of
options.validate
- Displays excutable
md-links
in the path (added inpackage.json
) - It runs without errors / with the expected output
- Implementation of
--validate
- Implementation of
--stats
- Unit test coverage of at least 70% of statements, functions, lines and branches.
- Tests passed (including linters) (
npm test
).
- Difference between primitive and non-primitive data structures
- Arrays
- Objects (key, value)
- Conditionals (if-else, switch, ternary operator, boolean logic)
- Functions (params, args, return)
- Recursion
- CommonJS Modules/ES Modules
- Difference between expressions and statements
- Callbacks
- Promises
- Unit tests
- Asynchronous tests
- Mocks and spies
- Compatibility tests in different environments
- Usage of linter (ESLINT)
- Usage of descriptive identifiers (naming conventions and semantics)
- Installation and usage of npm modules
- Package.json setup
- Npm-scripts setup
- process (env, argv, stdin-stdout-stderr, exit-code)
- File system (fs, path)
- Git: Installation and setup
- Git: Version control (init, clone, add, commit, status, push, pull, remote)
- Git: Branching and integration (branch, checkout, fetch, merge, reset, rebase, tag)
- GitHub: Sign up, create a repository, add a SSH key
- GitHub: Collaboration (branches | forks | pull requests | code review | tags)
- GitHub: Organization (projects | issues | labels | milestones | releases)
- Request and response.
- HTTP status codes