Module markdown

Provides Markdown parser that supports Obsidian flavor. Obsidian flavor is a combination of different flavors and a few differences.

Namely CommonMark and GitHub Flavored Markdown. More info here.

NOTE: Current iteration does not handle Obsidian flavor, unless it is covered by pulldown-cmark. Part of Obsidian flavor is for example use of any character inside tasks to mark them as completed - [?] Completed.

This crate uses pulldown_cmark to parse the markdown and enable the applicable features. This crate uses own intermediate types to provide the parsed markdown nodes. A Markdown parser that transforms Markdown input into a custom abstract syntax tree (AST) intented to be rendered with basalt—a TUI application for Obsidian.

This module provides a [Parser] type, which processes raw Markdown input into a Vec of [Node]s. These [Node]s represent semantic elements such as headings, paragraphs, block quotes, and code blocks.

The parser is built on top of pulldown_cmark.

Simple usage

At the simplest level, you can parse a Markdown string by calling the [from_str] function:

use basalt_core::markdown::{from_str, Range, Node, MarkdownNode, HeadingLevel, Text};

let markdown = "# My Heading\n\nSome text.";
let nodes = from_str(markdown);

assert_eq!(nodes, vec![
  Node {
    markdown_node: MarkdownNode::Heading {
      level: HeadingLevel::H1,
      text: Text::from("My Heading"),
    },
    source_range: Range { start: 0, end: 13 },
  },
  Node {
    markdown_node: MarkdownNode::Paragraph {
      text: Text::from("Some text."),
    },
    source_range: Range { start: 14, end: 24 }
  },
])

Implementation details

The [Parser] processes pulldown_cmark::Events one by one, building up the current [Node] in current_node. When an event indicates the start of a new structure (e.g., Event::Start(Tag::Heading {..})), the [Parser] pushes or replaces the current node with a new one. When an event indicates the end of that structure, the node is finalized and pushed into [Parser::output].

Unrecognized events (such as InlineHtml) are simply ignored for the time being.

Not yet implemented

• Handling of inline HTML, math blocks, etc.
• Tracking code block language (lang) properly (currently set to None).

Structs

Node

A node in the Markdown AST.

Parser

A parser that consumes pulldown_cmark::Events and produces a Vec of Node.

Text

A wrapper type holding a list of TextNodes.

TextNode

A single unit of text that is optionally styled (e.g., code).

Enums

BlockQuoteKind

Represents specialized block quote kind variants (tip, note, warning, etc.).

HeadingLevel

ItemKind

Represents the variant of a list or task item (checked, unchecked, etc.).

ListKind

Denotes whether a list is ordered or unordered.

MarkdownNode

The Markdown AST node enumeration.

Style

A style that can be applied to TextNode (code, emphasis, strikethrough, strong).

Functions

from_str

Parses the given Markdown input into a list of Nodes.

Type Aliases

Range

A std::ops::Range type for depicting range in crate::markdown.