README.md

This is Marvdown ⚡️ A stupid simple Markdown parser

nimble install marvdown

API reference | Download

Note

Marv is still in early development. Some features are not fully implemented yet. Contributions are welcome!

😍 Key Features

• Extremely Fast & Lightweight! Check benchmarks
• Compiled cross-platform CLI app
• Nim library for easy integration in your 👑 Nim projects
• Markdown to HTML
  • Auto-generate Table of Contents (ToC)
  • Auto-generate heading IDs for anchor links
• Markdown to PDF
• Markdown to JSON (structured data)
• GitHub Flavored Markdown (GFM)

About

Marv is a stupid simple markdown parser written in Nim. It can be used as a library in your Nim projects or as a CLI tool to convert markdown files to HTML. Currently, it supports basic markdown syntax like headings, paragraphs, bold, italic, links, images, lists, blockquotes, code blocks and inline code.

Installing

Install Marvdown via Nimble

nimble install marvdown

Example Usage

Using Marvdown from the command line is super easy. Just run:

marvdown html sample.md --optAnchors --bench

Enable anchor generations for headings with --optAnchors flag. Run benchmarks with --bench flag.

Marvdown as a Markdown library

Import Marvdown in your Nim project and use it to convert markdown contents:

import marvdown

echo marvdown.toHtml(readFile("sample.md"))

A full example of using Marvdown as a library with custom options:

import marvdown

let opts = MarkdownOptions(
  allowed: @[
    tagA, tagAbbr, tagB, tagBlockquote, tagBr,
    tagCode, tagDel, tagEm, tagH1, tagH2, tagH3, tagH4, tagH5, tagH6,
    tagHr, tagI, tagImg, tagLi, tagOl, tagP, tagPre, tagStrong, tagTable,
    tagTbody, tagTd, tagTh, tagThead, tagTr, tagUl
  ],
  allowTagsByType: none(TagType),
  allowInlineStyle: false,
  allowHtmlAttributes: false,
  enableAnchors: true,
  anchorIcon: "🔗"
)

# Convert markdown to HTML with custom options
echo marvdown.toHtml("...", opts)

Marvdown to XML

Marvdown also provides an XML output format, which can be useful for certain applications that require structured data. You can convert markdown to XML like this:

import marvdown

echo marvdown.toXml(readFile("sample.md"))

Marvdown AST

Marvdown also provides an Abstract Syntax Tree (AST) representation of the parsed markdown content. This is useful for advanced use cases, or storing the structured data in a database for later rendering (avoid storing raw HTML in the database). You can access the AST like this:

import marvdown

echo marvdown.getAst(readFile("sample.md"))

For more examples, see the /examples folder. Also check out the API reference for more details 👌

Benchmarks

Marvdown is super fast! It can parse large markdown files in milliseconds. Here is a quick benchmark over 100K lines of markdown text (~5.3 MB)

Benchmark 1: marvdown html bigdoc.md
  Time (abs ≡):        188.1 ms               [User: 166.9 ms, System: 19.8 ms]

Benchmark made with hyperfine

❤ Contributions & Support

• 🐛 Found a bug? Create a new Issue
• 👋 Wanna help? Fork it!
• 😎 Get €20 in cloud credits from Hetzner
• 🥰 Donate to OpenPeeps via PayPal address

Credits

Original illustration made by 💙 Olha remixed with Sora.

🎩 License

Marv | MIT License. Made by Humans from OpenPeeps.
Copyright © 2024 OpenPeeps & Contributors — All rights reserved.