module

Luce

Parses text in a Markdown-like format building an AST tree that can then be rendered to HTML.

If you are only interested in rendering Markdown to HTML, please refer to the README which explains the use of Luce.to_html.

The main entrypoint to the library is the Document which encapsulates the parsing process converting a Markdown text into a tree of Node (Array(Node)).

The two main parsing mechanics used are:

  • Blocks, representing top-level elements implemented via BlockSyntax subclasses, such as headers, paragraphs, blockquotes, and code blocks.
  • Inlines, representing chunks of test within a block with special meaning, implemented via InlineSyntax subclasses, such as links, emphasis, and inlined code.

Looking closely at Document.new() a few other concepts merit a mention:

  • ExtensionSet that provides configurations for common Markdown flavors
  • Resolver which aid in resolving links and images.

If you are looking at extending the library to support custom formatting what you might want is to:

  • Implement your own InlineSyntax subclasses
  • Implement your own BlockSyntax subclasses
  • Instruct the library to use those by:
    • Creating a new ExtensionSet from one of the existing flavors and adding your syntaxes.
    • Passing your syntaxes to Document or Luce.to_html as parameters.

Constants

VERSION = "0.5.0"

Class methods

alert_pattern

Alert type patterns.

A alert block is similar to a blockquote, starts with > [!TYPE], and only 5 types are supported (case-insensitive).

ascii_punctuation_characters

ASCII punctuation characters.

ascii_punctuation_escaped

ASCII punctuation characters with some characters escaped, in order to be used in the RegExp character set.

blockquote_fence_pattern

Fenced blockquotes

blockquote_pattern

The line starts with > with one optional space after.

code_fence_pattern

Fenced code block.

dummy_pattern

A pattern which should never be used.

It just satisfies non-nullability of pattern methods.

empty_pattern

The line contains only whitespace or is empty

footnote_pattern

A line starting with [^ and contains with ]:, but without special chars (\] \r\n\x00\t) between. Same as GFM.

header_pattern

Leading (and trailing) # define atx-style headers.

Starts with 1-6 unescaped # characters which must not be followed by a non-space character. Line may end with any number of # characters.

hr_pattern

Three or more hyphens, asterisks or underscores by themselves.

Note that a line like ---- is valid as both HR and SETEXT. In case of a tie, SETEXT should win.

html_block_pattern

A pattern to match the start of an HTML block.

The 7 conditions here correspond to the 7 start conditions in the Commonmark specification one by one: https://spec.commonmark.org/0.30/#html-block.

html_characters_pattern

A pattern to match HTML entity references and numeric character references.

html_entities_map
indent_pattern

A line indented four spaces. Used for code blocks and lists.

list_pattern

Unordered list A list starting with one of these markers: -, *, +. May have up to three leading spaces before the marker and any number of spaces or tabs after.

Ordered list A line starting with a number like 123.. May have up to three leading spaces before the marker and any number of spaces or tabs after.

named_tag_definition

A String pattern to match a named tag like <table> or </table>.

render_html(nodes : Array(Node), enable_tag_filter : Bool = false) : String

Render nodes to HTML.

setext_pattern

A series of = or - (on the next line) define setext-style headers.

table_pattern

A line of hyphens separated by at least one pipe.

to_html(markdown : String, block_syntaxes = Array(BlockSyntax).new, inline_syntaxes = Array(InlineSyntax).new, extension_set : ExtensionSet | Nil = nil, link_resolver : Resolver | Nil = nil, image_link_resolver : Resolver | Nil = nil, inline_only : Bool = false, encode_html : Bool = true, enable_tag_filter : Bool = false, with_default_block_syntaxes : Bool = true, with_default_inline_syntaxes : Bool = true) : String

Converts the given string of Markdown to HTML

Nested types