CommonMark without any of the extensions.
the reference
Every public name.
Generated from the package interface and the comments in the sources, so the page cannot drift from the library: the docs workflow regenerates it and fails when the result differs from what is committed.
3 values · 2 functions · 9 methods · 19 types · one package, and the examples are not part of it.
§01
values
pub let commonmark : Flavor
pub let flavor : Flavor
The preset parse uses when the caller does not pass one: gfm.
pub let gfm : Flavor
CommonMark as GitHub reads it: tables, strikethrough, bare links, task list items, the tag filter and footnotes. This is the default.
§02
functions
pub fn parse(StringView, flavor? : Flavor) -> Document
Parse a Markdown document.
test {
let document = @moonmd.parse("# Title")
assert_eq(document.html(safe=false), "<h1>Title</h1>\n")
}
pub fn walk(Document, (Node) -> Unit) -> Unit
Visit every node of the document, each container before its children and siblings in order.
§03
types
pub(all) enum Align
How a table column lines up its cells, taken from the delimiter row.
Default
No colons in the delimiter row: the column follows the page.
Left
A colon on the left only.
Center
A colon on both ends.
Right
A colon on the right only.
pub(all) enum Block
A block level node.
Heading(Heading)
A heading of level 1 to 6.
Paragraph(Array[Inline])
A paragraph, holding its inlines.
Code(Code)
A code block.
Quote(Array[Block])
A block quote, holding the blocks inside it.
List(ListBlock)
A bullet or ordered list.
Table(Table)
A table.
Html(String)
A block of raw HTML, which the renderer escapes unless asked not to.
Break
A thematic break, the line of three or more -, * or _.
Footnote(Footnote)
The body of a footnote definition.
pub(all) enum Break
A line break inside a paragraph.
Soft
A newline in the source, which HTML renders as a space or a newline.
Hard
Two trailing spaces or a trailing backslash, which HTML renders as <br />.
pub(all) struct Code
A code block, fenced or indented. info is the word after the opening fence, empty for indented code.
info : String
text : String
fenced : Bool
pub struct Document
A parsed document: the blocks in order, and the flavor it was read with, which the HTML renderer needs for the tag filter.
pub fn Document::blocks(Self) -> Array[Block]
The top level blocks of the document, in order.
pub fn Document::flavor(Self) -> Flavor
The flavor this document was parsed with.
pub fn Document::html(Self, safe? : Bool, xhtml? : Bool) -> String
Render the document as HTML. With safe set, which is the default, raw HTML is escaped and links to dangerous destinations lose their anchor; pass safe=false to write a document that may embed HTML of its own.
xhtml closes the elements that carry nothing (<br />, <hr />, <img />) the way the reference implementation does; pass xhtml=false for the form a document written to HTML5 uses.
pub fn Document::lines(Self) -> Array[LineSpan]
The lines of the source each top level block was read from, counted from one, one entry per block of blocks() and in the same order. Blank lines between blocks belong to neither. A document assembled with of_blocks was not read from text, so its list is empty.
test {
let document = @moonmd.parse("# One\n\ntwo\n")
let spans = document.lines()
assert_eq((spans[0].first, spans[0].last), (1, 1))
assert_eq((spans[1].first, spans[1].last), (3, 3))
}
pub fn Document::markdown(Self) -> String
Render the document as Markdown.
pub fn Document::of_blocks(Array[Block], flavor? : Flavor) -> Self
Assemble a document out of blocks, which is what a caller collecting the output of a Stream needs in order to render it. Footnote references are resolved against the definitions in the blocks, so a definition read after the reference that uses it still applies.
pub(all) struct Flavor
What a parser accepts beyond the CommonMark core. The presets commonmark and gfm cover the two dialects this library is asked for; the fields are public so a caller can take one and drop what it does not want.
tables : Bool
Pipe tables.
strikethrough : Bool
~one~ and ~~two~~ strikethrough.
autolinks : Bool
Links written bare, without angle brackets or a destination.
task_lists : Bool
- [ ] and - [x] list items.
tag_filter : Bool
Escape the raw HTML tags that would change the meaning of the page.
footnotes : Bool
[^label] references with their [^label]: definitions.
smart : Bool
Typographic punctuation: "x" and 'x' curl towards the text they wrap, --- and -- become an em and an en dash, and ... becomes an ellipsis. Code spans, raw HTML and destinations are left as written.
breaks : Bool
A line ending inside a paragraph is a hard break, the way a message box reads it, rather than the soft break the specification gives it.
pub(all) struct Footnote
A footnote, the body of one [^label]: definition. label is the label as it was written. number is the order the footnote is shown with, assigned in the order its first reference appears in the text; backrefs is how many references point at it.
label : String
blocks : Array[Block]
number : Int32
The number the footnote is shown with, or 0 until the document is read.
backrefs : Int32
The references that point at the footnote, in the order they appear.
pub(all) struct FootnoteRef
A footnote reference, [^label], and where it lands: the definition's label, the number that definition is shown with, and ref_ix, the order of this reference among the ones that point at the definition.
label : String
The label of the definition the reference points at, as written.
number : Int32
The number the definition is shown with.
ref_ix : Int32
The order of this reference among the ones pointing at the definition.
pub(all) struct Heading
A heading, level counting the ATX # marks or the setext underline.
level : Int32
content : Array[Inline]
pub(all) enum Inline
An inline level node.
Text(String)
Literal text.
Code(String)
A code span, already with its newlines turned into spaces.
Emphasis(Array[Inline])
Emphasis with a single * or _.
Strong(Array[Inline])
Strong emphasis with a double * or _.
Link(Link)
A link.
Image(Link)
An image.
Html(String)
Raw inline HTML.
Strike(Array[Inline])
Struck out text between tildes.
Break(Break)
A soft or hard line break.
FootnoteRef(FootnoteRef)
A footnote reference, [^label], with the number of the definition it points at and its order among the references to that definition.
pub(all) struct Item
One item of a list, with the task marker that introduced it if any.
blocks : Array[Block]
task : Task
pub(all) struct LineSpan
A run of source lines, counted from one, that a block was read from.
first : Int32
The first line of the run.
last : Int32
The last line of the run.
pub(all) struct Link
The destination, title and content of a link or image. For an image the content is the alternative text.
dest : String
title : String
content : Array[Inline]
pub(all) struct ListBlock
A list, with its items and whether it is tight (no blank lines between items, so their paragraphs are rendered without <p>).
kind : ListKind
tight : Bool
items : Array[Item]
pub(all) enum ListKind
What kind of list a ListBlock is, together with the marks needed to write it back unchanged.
Bullet(Char)
-, + or *.
Ordered(Int32, Char)
The first number, then . or ).
pub(all) enum Node
A node as walk hands it to its visitor: either a block or an inline.
Block(Block)
A block level node, with everything inside it.
Inline(Inline)
An inline level node, with everything inside it.
pub struct Stream
A parser that reads a document in pieces. Text that has arrived is parsed again on every call, but only the part that has not been handed out yet, so the work per chunk is proportional to the unfinished tail rather than to the whole document.
pub fn Stream::feed(Self, StringView) -> Array[Block]
Take the next piece of the document and return the blocks it completed.
pub fn Stream::finish(Self) -> Array[Block]
Close the stream and return whatever was still open.
pub fn Stream::new(flavor? : Flavor, defer_links? : Bool) -> Self
Start a stream.
defer_links keeps a block that mentions [ back until the whole document has arrived, because a link reference definition written later still applies to it. With it off such a block is handed out as soon as it closes, at the cost of a forward reference not resolving; the blocks are then the same as a whole parse for any document that defines its labels before using them.
pub(all) struct Table
A table: the alignment of each column, the header row, then the body rows. A row holds one cell per column, and a cell holds the inlines inside it.
align : Array[Align]
head : Array[Array[Inline]]
body : Array[Array[Array[Inline]]]
pub(all) enum Task
Whether a list item is a task list item, and if so whether it is done.
Plain
An ordinary list item.
Unchecked
[ ].
Checked
[x] or [X].
§04