markd

Yet another markdown parser built for speed, written in Crystal, Compliant to CommonMark specification (v0.29). Copy from commonmark.js.

Installation

Add this to your application's shard.yml:

dependencies:
  markd:
    github: icyleaf/markd

Quick start

require "markd"

markdown = <<-MD
# Hello Markd

> Yet another markdown parser built for speed, written in Crystal, Compliant to CommonMark specification.
MD

html = Markd.to_html(markdown)

Also here are options to configure the parse and render.

options = Markd::Options.new(smart: true, safe: true)
Markd.to_html(markdown, options)

Options

Name	Type	Default value	Description
time	Bool	false	render parse cost time during read source, parse blocks, parse inline.
smart	Bool	false	if true, straight quotes will be made curly,-- will be changed to an en dash,--- will be changed to an em dash, and... will be changed to ellipses.
source_pos	Bool	false	if true, source position information for block-level elementswill be rendered in the data-sourcepos attribute (for HTML)
safe	Bool	false	if true, raw HTML will not be passed through to HTML output (it will be replaced by comments)
prettyprint	Bool	false	if true, code tags generated by code blocks will have a prettyprint class added to them, to be used by Google code-prettify.
gfm	Bool	false	Partial support
autolink	Bool	false	if true, more autolinks are detected, like bare email addresses or http links
toc	Bool	false	Not supported for now
emoji	Bool	false	if true, convert Github style emoji chars.
tagfilter	Bool	false	if true, escape certain HTML tags.
base_url	URI?	nil	if not nil, relative URLs of links are resolved against this URI. It act's like HTML's <base href="base_url"> in the context of a Markdown document.

Advanced

If you want to use a custom renderer, it can!

class CustomRenderer < Markd::Renderer

  def strong(node, entering)
  end

  # more methods following in render.
end

options = Markd::Options.new(time: true)
document = Markd::Parser.parse(markdown, options)
renderer = CustomRenderer.new(options)

html = renderer.render(document)

Use tartrazine shards to render code block.

Added and require tartrazine before markd will use it to render code block.

By default, it use formatter like following:

formatter = Tartrazine::Html.new(
  theme: Tartrazine.theme("catppuccin-macchiato"),
  line_numbers: true,
  standalone: true,
)

You can passing a formatter instead.

e.g.

require "tartrazine" # require it before markd
require "markd"

formatter = Tartrazine::Html.new(
  theme: Tartrazine.theme("emacs"),

  # Disable print line number
  line_numbers: false,

  # Set standalone to false for better performace.
  #
  # You need generate css file use `bin/tartrazine -f html -t "emacs" --css`,
  # then link it in you site.
  standalone: false,
)

html = Markd.to_html(markdown,formatter: formatter)

If you don't care about the formatter config, you can just passing a string instead.

require "tartrazine" # require it before markd
require "markd"

html = Markd.to_html(markdown, formatter: "emacs")

Currently Tartrazine supports 247 languages and 331 themes, you can retrieve the supported languages use Tartrazine::LEXERS_BY_NAME.values.uniq.sort, for now the result is:

[
  "LiquidLexer", "VelocityLexer",

  "abap", "abnf", "actionscript", "actionscript_3", "ada", "agda", "al", "alloy", "angular2",
  "antlr",   "apacheconf", "apl", "applescript", "arangodb_aql", "arduino", "armasm",
  "autohotkey", "autoit", "awk",

  "ballerina", "bash", "bash_session", "batchfile", "bbcode", "bibtex", "bicep", "blitzbasic",
  "bnf", "bqn", "brainfuck",

  "c", "c#", "c++", "cap_n_proto", "cassandra_cql", "ceylon", "cfengine3", "cfstatement",
  "chaiscript", "chapel",   "cheetah", "clojure", "cmake", "cobol", "coffeescript",
  "common_lisp", "coq", "crystal", "css", "cue", "cython",

  "d", "dart", "dax", "desktop_entry", "diff", "django_jinja", "dns", "docker", "dtd", "dylan",

  "ebnf", "elixir", "elm", "emacslisp", "erlang",

  "factor", "fennel", "fish", "forth", "fortran", "fortranfixed", "fsharp",

  "gas", "gdscript", "gdscript3", "gherkin", "gleam", "glsl", "gnuplot", "go_template",
  "graphql", "groff", "groovy",

  "handlebars", "hare", "haskell", "hcl", "hexdump", "hlb", "hlsl", "holyc", "html", "hy",

  "idris", "igor", "ini", "io", "iscdhcpd",

  "j", "java", "javascript", "json", "jsonata", "julia", "jungle",

  "kotlin",

  "lighttpd_configuration_file", "llvm", "lua",

  "makefile", "mako", "markdown", "mason", "materialize_sql_dialect", "mathematica", "matlab",
  "mcfunction", "meson", "metal", "minizinc", "mlir", "modula-2", "moinwiki", "monkeyc",
  "morrowindscript", "myghty", "mysql",

  "nasm", "natural", "ndisasm", "newspeak", "nginx_configuration_file", "nim", "nix",

  "objective-c", "objectpascal", "ocaml", "octave", "odin", "onesenterprise", "openedge_abl",
  "openscad", "org_mode",

  "pacmanconf", "perl", "php", "pig", "pkgconfig", "pl_pgsql", "plaintext", "plutus_core",
  "pony", "postgresql_sql_dialect", "postscript", "povray", "powerquery", "powershell",
  "prolog", "promela", "promql", "properties", "protocol_buffer",   "prql", "psl", "puppet",
  "python", "python_2",

  "qbasic", "qml",

  "r", "racket", "ragel", "react", "reasonml", "reg", "rego", "rexx", "rpm_spec", "rst",
  "ruby", "rust",

  "sas", "sass", "scala", "scheme", "scilab", "scss", "sed", "sieve", "smali", "smalltalk",
  "smarty", "snobol", "solidity", "sourcepawn", "sparql", "sql", "squidconf", "standard_ml",
  "stas", "stylus", "swift", "systemd", "systemverilog",

  "tablegen", "tal", "tasm", "tcl", "tcsh", "termcap", "terminfo", "terraform", "tex",
  "thrift",  "toml", "tradingview", "transact-sql", "turing", "turtle", "twig", "typescript",
  "typoscript", "typoscriptcssdata", "typoscripthtmldata",

  "ucode",

  "v", "v_shell", "vala", "vb_net", "verilog", "vhdl", "vhs", "viml", "vue", "wdte",

  "webgpu_shading_language", "whiley",

  "xml", "xorg",

  "yaml", "yang", "z80_assembly",

  "zed", "zig"
]

For details usage, check tartrazine documents.

Performance

Here is the result of a sample markdown file parse at MacBook Pro Retina 2015 (2.2 GHz):

Crystal Markdown (no longer present)   3.28k (305.29µs) (± 0.92%)       fastest
           Markd                       305.36 (  3.27ms) (± 5.52%) 10.73× slower

Recently, I'm working to compare the other popular commonmark parser, the code is stored in benchmarks.

How to Contribute

Your contributions are always welcome! Please submit a pull request or create an issue to add a new question, bug or feature to the list.

All Contributors are on the wall.

You may also like

• halite - HTTP Requests Client with a chainable REST API, built-in sessions and middlewares.
• totem - Load and parse a configuration file or string in JSON, YAML, dotenv formats.
• poncho - A .env parser/loader improved for performance.
• popcorn - Easy and Safe casting from one type to another.
• fast-crystal - 💨 Writing Fast Crystal 😍 -- Collect Common Crystal idioms.

License

MIT License © icyleaf