ipassternak / marcus

A Command Line Interface (CLI) Application for Compiling and Manipulating Markdown

Marcus

Marcus is a Command Line Interface (CLI) application for compiling and manipulating Markdown files effortlessly.

• Revert commit
• Failed commit

Conclusion

Підсумовуючи, тестування є невід'ємною частиною розробки програмного забезпечення. Вони допомагають прискорити написання нового функціоналу та захистити працездатність старого.

Покриття коду тестами допомогло мені виявити кілька багів та легко впровадити розширений функціонал. Не менш важливим для мене є TDD (Test-Driven Development), яке спонукає розробника краще моделювати архітектуру системи, використовувати загальноприйняті техніки, практики та принципи, якими в іншому випадку часто нехтується. Це прискорює та полегшує розробку системи, забезпечує гладке горизонтальне масштабування.

Натомість TDD має й негативні властивості, які зумовлені основною концепцією такого підходу. Контракти та інтерфейси модулів, що тестуються, мають властивість змінюватися у процесі розробки. Це відбувається через різноманітні причини, проте має однаковий негативний наслідок. При зміні інтерфейса модуля, ми змушені змінити й функцію, що його тестує, а це в свою чергу суперечить ідеї TDD, де всі тести повинні бути виключно immutable й незалежити від модуля, що тестується, забезпечуючи правильну перевірку його функціональності.

Table of Contents

• Getting Started
  • Requirements
  • Installation
  • Usage
  • Help
  • Alternative Startup
• Testing
• Features
• Usage Examples
• Contributing
• License

Getting Started

Requirements:

To use Marcus, ensure you have the following dependencies installed on your system:

• Node.js (version 16 or later)
• npm or any other Node package manager
• A shell environment for running scripts

Installation:

To install Marcus, simply clone this repository and install the dependencies using npm:

git clone https://github.com/ipassternak/marcus.git
cd marcus
npm install

Usage:

After installation, you can run Marcus using the following command:

node index.js <input>

Replace <input> with the path to the Markdown file you want to compile or manipulate.

Help:

For a list of all available commands and options, you can use the following command:

node index.js --help

Alternative Startup:

To make Marcus easily accessible from any directory in your system, you can add its directory to your PATH environment variable and make the marcus script executable:

export PATH="$PATH:/path/to/marcus"
sudo chmod u+x ./marcus # -- in project root directory

Then, you can use the marcus command directly:

marcus <input>

Features

• Markdown Compilation: Marcus can compile Markdown files into various formats such as HTML.

Usage Examples

Here are some examples of how you can use Marcus in your workflow:

1. Compile a Markdown file to HTML output result to stdout:

   marcus document.md

2. Compile a Markdown file to HTML and save result as a file:

   marcus document.md --out /path/to/save

Testing

To run the tests for this project, execute the following command in your terminal:

npm test

For development, it's recommended to use the interactive version with the following command:

npm run test:dev

Contributing

Contributions to Marcus are welcome! If you have any suggestions, bug reports, or feature requests, please open an issue or submit a pull request on GitHub.

License

This project is licensed under the MIT License.

marcus's Issues

Update index.js file

index.js file should be entry point of the program and control main workflow

Update project dependencies and development files

• Update README.md file

Add CI workflow

• add continuous integration using GitHub Actions
• update README.md file, include project testing instructions

Add basic project structure

• Init empty npm package
• Apply general file structure

Add --format flag

To support different target compilation formats we need to have appropriate user interface

• add --format=value cli options. It should recognize html and ansi target format
• add unit tests

Add IO module

Input Output module (IO) is responsible for fetching markdown source file and output result to desired destination

• IO module should be compatible to work with file system

Add core markdown logic

• Implement basic markdown parsing and tokenization
• Implement tokens validation and evaluation
• Implement tokens compilation(transpilation) into target format

Add automated tests

• Use Jest test runner
• Tests should cover core logic, cli and io modules
• Add npm command for starting CI

Add ANSI compilation target format

• add ANSI tag map
• export interface function from compiler module
• add unit tests

Add CLI module

• Use commander as the main dependency
• Configure module to implement required user interface