silk.markdown.document.

When to use#

Parse strict CommonMark with MarkdownDocument.parse, or select extensions with MarkdownOptions and MarkdownDocument.parseWithOptions. Walk the tree or render it with silk.markdown.html.

Details#

The document borrows its UTF-8 source. Verbatim text uses source ranges; decoded text uses one owned buffer. Node ids belong to one document. Every span counts bytes in the original source, including syntax delimiters.

Examples#

Inspect a heading and its source span#

import silk.markdown.document { MarkdownDocument, MarkdownNodeId }
import silk.core.effect { Effect }
import silk.mem.allocator { Allocator, OutOfMemoryError }

pub effect fn main() -> i32
  ! OutOfMemoryError {
  let mut allocator = Allocator.systemAllocatorProvider()
  let document = run MarkdownDocument.parse("# Hello")
    |> Effect.provideMut<Allocator>(&mut allocator)
  let heading = MarkdownNodeId { index: 1 }
  if MarkdownDocument.headingLevel(&document, heading) != 1
    || MarkdownDocument.span(&document, heading).end != 7 {
    return 1
  }
  return 0
}

Import as MarkdownDocument with import silk.markdown.document { MarkdownDocument }.

Public declarations: 10.

MarkdownSpan#

pub struct MarkdownSpan

A half-open byte range in the original Markdown source.

Field start#

pub start: usize

The offset of the first byte, including any opening syntax delimiter.

Field end#

pub end: usize

The offset after the last byte, including any closing syntax delimiter.

Implementation Copy for MarkdownSpan#

impl Copy for MarkdownSpan

MarkdownNodeId#

pub struct MarkdownNodeId

The index of one node in one Markdown document. An id from another document is not transferable.

Field index#

pub index: usize

The index in the document's preorder node slice.

Implementation Copy for MarkdownNodeId#

impl Copy for MarkdownNodeId

MarkdownNodeKind#

pub enum MarkdownNodeKind

The syntactic role of a Markdown node.

Document#

Document

The root container of all blocks.

Paragraph#

Paragraph

A paragraph with inline children.

Heading#

Heading

An ATX or setext heading with inline children.

ThematicBreak#

ThematicBreak

A horizontal thematic break.

BlockQuote#

BlockQuote

A block quote container.

List#

List

An ordered or bullet list.

ListItem#

ListItem

One item in a list.

CodeBlock#

CodeBlock

A fenced or indented code block.

HtmlBlock#

HtmlBlock

A raw HTML block.

Text#

Text

Literal inline text with escapes and entities decoded.

SoftBreak#

SoftBreak

A line ending within a paragraph.

HardBreak#

HardBreak

An explicit inline line break.

Code#

Code

An inline code span.

Emphasis#

Emphasis

Emphasized inline content.

Strong#

Strong

Strongly emphasized inline content.

Link#

Link

A link with inline label children.

Image#

Image

An image with inline alternative-text children.

HtmlInline#

HtmlInline

A raw inline HTML fragment.

Table#

Table

A GFM table with row children.

TableRow#

TableRow

A table header or body row with cell children.

TableCell#

TableCell

A table cell with inline children.

Strikethrough#

Strikethrough

Deleted inline content enclosed by one or two tildes.

FootnoteReference#

FootnoteReference

A reference to a defined footnote.

FootnoteDefinition#

FootnoteDefinition

A footnote container with block children.

Frontmatter#

Frontmatter

A leading YAML or TOML metadata block with an unparsed source body.

Alert#

Alert

A GitHub alert container with block children.

MarkdownAlignment#

pub enum MarkdownAlignment

A table column's horizontal alignment.

None#

None

No explicit alignment.

Left#

Left

Left alignment.

Center#

Center

Center alignment.

Right#

Right

Right alignment.

MarkdownTaskState#

pub enum MarkdownTaskState

A list item's task marker state.

None#

None

The item has no task marker, or the node is not a list item.

Unchecked#

Unchecked

The item starts with an unchecked task marker.

Checked#

Checked

The item starts with a checked task marker.

MarkdownFrontmatterKind#

pub enum MarkdownFrontmatterKind

The delimiter of an unparsed frontmatter block.

None#

None

The node is not frontmatter.

Yaml#

Yaml

Three hyphens delimit YAML metadata.

Toml#

Toml

Three plus signs delimit TOML metadata.

MarkdownAlertKind#

pub enum MarkdownAlertKind

The category of a GitHub alert.

None#

None

The node is not an alert.

Note#

Note

Useful information.

Tip#

Tip

Advice for a task.

Important#

Important

Information required for a task.

Warning#

Warning

A potential problem.

Caution#

Caution

A risk that requires attention.

MarkdownOptions#

pub struct MarkdownOptions

Syntax switches and a nesting bound. Every extension is disabled by default. Excess nesting remains literal text or paragraph content.

Field maxNesting#

pub maxNesting: usize

The maximum block-container and inline nesting depth. The default is 256; zero disables nesting.

Field tables#

pub tables: bool

Enables GFM tables. The default is false.

Field strikethrough#

pub strikethrough: bool

Enables matching one- or two-tilde strikethrough. The default is false.

Field taskLists#

pub taskLists: bool

Enables task markers in list items. The default is false.

Field autolinkLiterals#

pub autolinkLiterals: bool

Enables GFM URL and email literals, including ftp, mailto, and xmpp. The default is false.

Field footnotes#

pub footnotes: bool

Enables footnote definitions and references. The default is false.

Field frontmatter#

pub frontmatter: bool

Enables leading YAML or TOML frontmatter capture. The default is false.

Field alerts#

pub alerts: bool

Enables GitHub alert block quotes. The default is false.

Implementation Copy for MarkdownOptions#

impl Copy for MarkdownOptions

Implementation MarkdownOptions#

impl MarkdownOptions

Associated function make#

pub fn make() -> MarkdownOptions

Returns strict CommonMark options with a nesting bound of 256 and every extension disabled.

Associated function gfm#

pub fn gfm() -> MarkdownOptions

Returns GFM table, strikethrough, task-list, and autolink options with a nesting bound of 256. Footnotes, frontmatter, and alerts remain disabled.

MarkdownNode#

pub struct MarkdownNode

One node in a Markdown document. Read payloads and tree links with MarkdownDocument operations. The node slice is in preorder, with each parent before its children.

Field kind#

pub kind: MarkdownNodeKind

The syntactic role of this node.

Implementation Copy for MarkdownNode#

impl Copy for MarkdownNode

MarkdownDocument#

pub struct MarkdownDocument<'source>

A parsed Markdown tree that borrows the source and owns decoded text and a flat node arena.

Details#

Verbatim literals are views into the original source. Decoded literals borrow one owned side buffer. Returned text cannot outlive the document. Invalid ids return absent links, empty text, and zero payloads. Footnote definitions follow main blocks in first-reference order. Unused definitions follow referenced definitions.

Implementation MarkdownDocument<'source>#

impl<'source> MarkdownDocument<'source>

Associated function parse#

pub effect fn parse(source: string<'source>) -> MarkdownDocument<'source>
    ! OutOfMemoryError
    ? &mut Allocator

Parses strict CommonMark 0.31.2 with a nesting bound of 256 and every extension disabled. Every input produces a document. The document borrows source and owns its nodes and decoded text.

Details#

Bounded inline lookahead and reference expansion leave excess candidates as literal text.

Errors#

• OutOfMemoryError if the allocator cannot supply the tree or decoded text.

Associated function parseWithOptions#

pub effect fn parseWithOptions(
    source: string<'source>,
    options: &MarkdownOptions,
  ) -> MarkdownDocument<'source>
    ! OutOfMemoryError
    ? &mut Allocator

Parses UTF-8 Markdown with the extension switches and nesting bound in options. Disabled extensions retain CommonMark syntax. Excess nesting remains literal text or paragraph content. The document borrows source and owns its nodes and decoded text.

Details#

Bounded inline lookahead and reference expansion leave excess candidates as literal text.

Errors#

• OutOfMemoryError if the allocator cannot supply the tree or decoded text.

Method root#

pub fn root(self: &Self) -> MarkdownNodeId

Returns the document root, whose index is zero, including for an empty source.

Method nodes#

pub fn nodes(self: &Self) -> &[MarkdownNode]

Borrows all nodes in preorder. A node's id is its index in this slice.

Method kind#

pub fn kind(self: &Self, id: MarkdownNodeId) -> MarkdownNodeKind

Returns the node kind, or Text for an invalid id.

Method span#

pub fn span(self: &Self, id: MarkdownNodeId) -> MarkdownSpan

Returns the source byte range, including delimiters, or 0..0 for an invalid id. Container spans include prefixes and line endings; inline spans include only their own syntax.

Method parent#

pub fn parent(self: &Self, id: MarkdownNodeId) -> Option<MarkdownNodeId>

Returns the parent, or None if the link is absent or the id is invalid.

Method firstChild#

pub fn firstChild(self: &Self, id: MarkdownNodeId) -> Option<MarkdownNodeId>

Returns the first child, or None if the link is absent or the id is invalid.

Method lastChild#

pub fn lastChild(self: &Self, id: MarkdownNodeId) -> Option<MarkdownNodeId>

Returns the last child, or None if the link is absent or the id is invalid.

Method nextSibling#

pub fn nextSibling(self: &Self, id: MarkdownNodeId) -> Option<MarkdownNodeId>

Returns the next sibling, or None if the link is absent or the id is invalid.

Method previousSibling#

pub fn previousSibling(self: &Self, id: MarkdownNodeId) -> Option<MarkdownNodeId>

Returns the previous sibling, or None if the link is absent or the id is invalid.

Method headingLevel#

pub fn headingLevel(self: &Self, id: MarkdownNodeId) -> u8

Returns the heading level from one through six, or zero for other kinds.

Method ordered#

pub fn ordered(self: &Self, id: MarkdownNodeId) -> bool

Returns whether a list is ordered; returns false for other kinds.

Method start#

pub fn start(self: &Self, id: MarkdownNodeId) -> usize

Returns the initial ordered-list number, or zero for other kinds.

Method tight#

pub fn tight(self: &Self, id: MarkdownNodeId) -> bool

Returns whether a list suppresses paragraph tags; returns false for other kinds.

Method marker#

pub fn marker(self: &Self, id: MarkdownNodeId) -> u8

Returns the bullet or ordered-list delimiter byte, or zero for other kinds.

Method isFenced#

pub fn isFenced(self: &Self, id: MarkdownNodeId) -> bool

Returns whether a code block uses a fence; returns false for other kinds.

Method literal#

pub fn literal<'a>(self: &'a Self, id: MarkdownNodeId) -> string<'a>

Returns the literal of Text, Code, CodeBlock, HtmlBlock, or HtmlInline; returns empty text for other kinds. The result borrows the document. Text has decoded backslash escapes and character references. Code spans replace line endings with spaces and remove one enclosing space when required. Block literals normalize line endings to line feeds. All literals replace NUL with U+FFFD.

Method info#

pub fn info<'a>(self: &'a Self, id: MarkdownNodeId) -> string<'a>

Returns the decoded fence info string, or empty text for other kinds. The result borrows the document.

Method destination#

pub fn destination<'a>(self: &'a Self, id: MarkdownNodeId) -> string<'a>

Returns the decoded link or image destination, or empty text for other kinds. The result borrows the document.

Method isTableHeader#

pub fn isTableHeader(self: &Self, id: MarkdownNodeId) -> bool

Returns whether a table row is the header row; returns false for other kinds.

Method tableColumns#

pub fn tableColumns(self: &Self, id: MarkdownNodeId) -> usize

Returns the number of columns in a table; returns zero for other kinds or invalid ids.

Method columnAlignment#

pub fn columnAlignment(self: &Self, id: MarkdownNodeId, column: usize) -> MarkdownAlignment

Returns a table column's alignment in constant time. Columns have zero-based indices. Returns None for other kinds, invalid ids, or out-of-range columns.

Method alignment#

pub fn alignment(self: &Self, id: MarkdownNodeId) -> MarkdownAlignment

Returns a cell's column alignment; returns None for other kinds or invalid ids.

Method taskState#

pub fn taskState(self: &Self, id: MarkdownNodeId) -> MarkdownTaskState

Returns a list item's task state; returns None for other kinds or items without a marker.

Method frontmatterKind#

pub fn frontmatterKind(self: &Self, id: MarkdownNodeId) -> MarkdownFrontmatterKind

Returns the frontmatter delimiter kind; returns None for other kinds or invalid ids.

Method frontmatterBody#

pub fn frontmatterBody<'a>(self: &'a Self, id: MarkdownNodeId) -> string<'a>

Borrows the unparsed frontmatter body directly from the source, including its final line ending. Excludes both delimiter lines. Returns empty text for other kinds or invalid ids.

Method alertKind#

pub fn alertKind(self: &Self, id: MarkdownNodeId) -> MarkdownAlertKind

Returns the alert category; returns None for other kinds or invalid ids.

Method footnoteLabel#

pub fn footnoteLabel<'a>(self: &'a Self, id: MarkdownNodeId) -> string<'a>

Borrows the source label of a footnote reference or definition, without brackets or the caret. Returns empty text for other kinds. Resolution collapses label whitespace and folds Unicode case.

Method footnoteDefinition#

pub fn footnoteDefinition(self: &Self, id: MarkdownNodeId) -> Option<MarkdownNodeId>

Returns the definition resolved by a footnote reference; returns None for other kinds or invalid ids.

Method footnoteNumber#

pub fn footnoteNumber(self: &Self, id: MarkdownNodeId) -> usize

Returns a footnote's one-based first-reference number; returns zero for unused definitions and other kinds.

Method footnoteReferences#

pub fn footnoteReferences(self: &Self, id: MarkdownNodeId) -> usize

Returns a reference's one-based occurrence, or a definition's reference count; returns zero for other kinds.

Method title#

pub fn title<'a>(self: &'a Self, id: MarkdownNodeId) -> Option<string<'a>>

Returns the decoded link or image title, or None for an absent title or another kind. A present empty title differs from an absent title. The text borrows the document.

Category: Data formats.

Profiles: aarch64-apple-darwin, aarch64-unknown-linux-gnu, aarch64-unknown-linux-gnu-no-libc, x86_64-unknown-linux-gnu, x86_64-unknown-linux-gnu-no-libc, wasm32-unknown-unknown, wasm32-wasip1, wasm32-wasip2, x86_64-pc-windows-msvc, wasm64-unknown-unknown.