Introduction to the Maddy Project
Maddy is a convenient and streamlined C++ library designed to convert Markdown text into HTML. It stands out due to its header-only nature, which simplifies integration into projects by requiring only the inclusion of necessary headers.
Supported Operating Systems
Maddy is designed to function on any operating system that supports the C++14 standard library. Though theoretically compatible with a wide range of systems, it has been explicitly tested and confirmed to work on:
- Linux, using the GCC compiler.
- OSX, utilizing the Clang compiler.
- Windows, with support for Visual Studio 17 2022 and mingw.
Dependencies
The primary requirement for Maddy is the availability of C++14, ensuring compatibility and seamless performance across supported environments.
Rationale Behind Maddy
The developer of Maddy embarked on creating this parser because existing C++ Markdown parsers did not meet their needs. Instead of compromising, they crafted a tool tailored specifically to their expectations and requirements.
Markdown Syntax Support
Maddy supports various Markdown syntaxes, details of which can be found in its definitions documentation. This ensures users have a comprehensive understanding of the capabilities and limitations of the parser.
Integration with CMake Projects
Maddy can be integrated into projects using CMake's FetchContent feature, starting from version 3.11. To include Maddy, users can add the following configuration to their CMake file:
include(FetchContent)
FetchContent_Declare(
maddy
URL https://github.com/progsource/maddy/.../maddy-src.zip
)
FetchContent_MakeAvailable(maddy)
add_executable(my_exe)
target_link_libraries(my_exe PUBLIC maddy)
This inclusion simplifies the process of compiling and linking Maddy with user projects.
Usage Instructions
Using Maddy is straightforward. In a project, users need to add Maddy's include path and utilize the following sample code to parse Markdown:
#include <memory>
#include <string>
#include "maddy/parser.h"
std::stringstream markdownInput("");
// configure parser settings; optional
std::shared_ptr<maddy::ParserConfig> config = std::make_shared<maddy::ParserConfig>();
config->enabledParsers &= ~maddy::types::EMPHASIZED_PARSER;
config->enabledParsers |= maddy::types::HTML_PARSER;
std::shared_ptr<maddy::Parser> parser = std::make_shared<maddy::Parser>(config);
std::string htmlOutput = parser->Parse(markdownInput);
Configurable settings and flags are accessible in include/maddy/parserconfig.h.
Running Tests
For testing Maddy, particularly on Linux, users should execute the following commands in a terminal with Git and CMake installed:
git clone https://github.com/progsource/maddy.git
cd maddy
mkdir tmp
cd tmp
cmake -DMADDY_BUILD_WITH_TESTS=ON ..
make
make test
This process will validate the functionality of Maddy and ensure everything works as expected.
Contributing to Maddy
Community contributions are welcome for enhancing Maddy. Users can contribute by:
- Creating issues on GitHub for bug reports or feature requests.
- Submitting pull requests with their changes or improvements.
Contributors are encouraged to read the CONTRIBUTING.md file for more information on guidelines and processes.
By maintaining an open-source ethos and encouraging contributions, Maddy aims to evolve and continually meet the needs of its users.