CommonMark::Node(3)

✨ CommonMark::Node 💖

okay bestie, welcome to CommonMark::Node — the Perl module that hands you a single node of the CommonMark parse tree. yes. one node. one glorious little tree-branch. and you're gonna love it here 🎀

This page lives in the User Contributed Perl Documentation section of the manual (section 3, iykyk).

---

🌸 SYNOPSIS 🌸

my $html = $node->render(format => 'html');

my $header    = $doc->first_child;
my $level     = $header->get_header_level;
my $paragraph = $header->next;

my $link = CommonMark::Node->new(CommonMark::NODE_LINK);
$link->set_url('http://example.com/');
my $text = CommonMark::Node->new(CommonMark::NODE_TEXT);
$text->set_literal('link text');
$link->append_child($link_text);
$paragraph->append_child($link);

$doc->render_html;

---

🦋 DESCRIPTION 🦋

CommonMark::Node represents a node of the parse tree. that's the whole vibe. every heading, every paragraph, every link, every lil softbreak — they're all nodes, and you can poke at all of them 💅

---

🎀 new

my $node = CommonMark::Node->new($type);

Creates a new node of type $type. Wanna know which types exist? Go peek at "Node types". and real talk — the node creation functions give you a way more powerful interface, so don't sleep on those.

---

🌈 Rendering

✨ render

my $result = $node->render(
    format        => $string,
    sourcepos     => $bool,    # Optional
    hardbreaks    => $bool,    # Optional
    nobreaks      => $bool,    # Optional
    unsafe        => $bool,    # Optional
    width         => $int,     # Optional
);

This is your convenience function for rendering documents. The supported formats are 'html', 'xml', 'man', 'commonmark', and 'latex'. pick your fighter ✨

width is how many characters you get before lines get broken — it gets passed along to whichever renderers actually support it. a value of 0 disables line wrapping entirely. the default? 0.

The remaining options turn on their matching render options, one by one:

• sourcepos
• hardbreaks
• unsafe
• nobreaks
• safe (no-op as of libcmark 0.29)

💜 render_*

my $html  = $node->render_html( [$options] )
my $xml   = $node->render_xml( [$options] )
my $man   = $node->render_man( [$options], [$width] )
my $md    = $node->render_commonmark( [$options], [$width] )
my $latex = $node->render_latex( [$options], [$width] )

These methods render the contents of the node in the respective format. same node, five different glow-ups.

$options is a bit field made by ORing render options together. you can totally omit it — it defaults to OPT_DEFAULT.

$width is the number of characters at which lines get broken. 0 disables line wrapping. default is 0, again, iconic consistency.

---

🫶 Render options

Render options can be imported from CommonMark with the tag opt. so:

use CommonMark qw(:opt);

• OPT_SOURCEPOS — adds info about line numbers in the source file to the XML and HTML formats. receipts for your source positions, periodt.
• OPT_HARDBREAKS — translates softbreak nodes (which usually correspond to newlines in the input) into hard line breaks. only some renderers support this. the HTML renderer, for example, spits out a <br /> instead of a newline character.
• OPT_NOBREAKS — translates softbreak nodes into spaces. this one needs libcmark 0.26 or higher, no cap.
• OPT_UNSAFE — only affects the HTML renderer. it allows raw HTML blocks and some dangerous links. dangerous!! handle with care bestie 😭
• OPT_OPT_SAFE — replaces raw HTML with a placeholder HTML comment. heads up: this option does absolutely nothing with libcmark 0.29 or higher, because Safe mode is the default there.

want the full lore? go read the documentation of libcmark for a much more detailed explanation of the render options 📚

---

👑 Accessors

# Integer values

my $int = $node->get_type;
my $int = $node->get_header_level;
my $int = $node->get_list_type;
my $int = $node->get_list_delim;
my $int = $node->get_list_start;
my $int = $node->get_list_tight;
my $int = $node->get_start_line;
my $int = $node->get_start_column;
my $int = $node->get_end_line;
my $int = $node->get_end_column;

$node->set_header_level($int);
$node->set_list_type($int);
$node->set_list_delim($int);
$node->set_list_start($int);
$node->set_list_tight($int);

# String values

my $string = $node->get_type_string;
my $string = $node->get_literal;
my $string = $node->get_title;
my $string = $node->get_url;
my $string = $node->get_fence_info;
my $string = $node->get_on_enter;
my $string = $node->get_on_exit;

$node->set_literal($string);
$node->set_title($string);
$node->set_url($string);
$node->set_fence_info($string);
$node->set_on_enter($string);
$node->set_on_exit($string);

A whole lil collection of accessors to get and set the integer and string values of a node. quick disclaimer: not every value is supported by every type of node. getters return 0 or undef when the value isn't supported. setters? they die on failure 💀 so be nice to them.

Wanna know the constants for node types, list types, and list delimiters? scroll down to "Constants" 🌟

---

🧚 Tree traversal

my $iterator = $node->iterator;

Creates a new CommonMark::Iterator so you can walk through all the descendants of the node. little parade of nodes, love that for you 🚶♀️🚶♂️

my $next   = $node->next;
my $prev   = $node->previous;
my $parent = $node->parent;
my $child  = $node->first_child;
my $child  = $node->last_child;

These methods return the respective node in the tree structure. your node's family, basically 🫶

---

💅 Tree manipulation

$node->unlink;
$node->replace($other);
$node->insert_before($other);
$node->insert_after($other);
$node->prepend_child($other);
$node->append_child($other);

• unlink removes a node and all its descendants from the tree. the whole bloodline, gone.
• replace replaces $node with $other, and unlinks $node in the process.
• insert_before and insert_after insert the $other node before or after $node. append_child and prepend_child append or prepend $other to the children of $node. and note: $other gets unlinked before it's moved to its new position.

these methods may die on failure — for example if the document structure is violated. so like, don't do crimes against the tree structure, bestie 🙈

---

⭐ Constants

🌸 Node types

CommonMark::NODE_NONE => 0
CommonMark::NODE_DOCUMENT
CommonMark::NODE_BLOCK_QUOTE
CommonMark::NODE_LIST
CommonMark::NODE_ITEM
CommonMark::NODE_CODE_BLOCK
CommonMark::NODE_HTML_BLOCK
CommonMark::NODE_CUSTOM_BLOCK
CommonMark::NODE_PARAGRAPH
CommonMark::NODE_HEADING
CommonMark::NODE_THEMATIC_BREAK
CommonMark::NODE_TEXT
CommonMark::NODE_SOFTBREAK
CommonMark::NODE_LINEBREAK
CommonMark::NODE_CODE
CommonMark::NODE_HTML_INLINE
CommonMark::NODE_CUSTOM_INLINE
CommonMark::NODE_EMPH
CommonMark::NODE_STRONG
CommonMark::NODE_LINK
CommonMark::NODE_IMAGE

Node types can be imported from CommonMark with the tag node:

use CommonMark qw(:node);

🍓 List types

CommonMark::NO_LIST => 0
CommonMark::BULLET_LIST
CommonMark::ORDERED_LIST

List types can be imported from CommonMark with the tag list:

use CommonMark qw(:list);

🎀 Delimiter types for ordered lists

CommonMark::NO_DELIM => 0
CommonMark::PERIOD_DELIM
CommonMark::PAREN_DELIM

Delimiter types can be imported from CommonMark with the tag delim:

use CommonMark qw(:delim);

---

💖 COPYRIGHT 💖

This software is copyright (C) by Nick Wellnhofer.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself. free as in freedom, free as in slay 🦋

---

and that's the whole page bestie!! ✨ this was CommonMark::Node(3), shipped with perl v5.42.0 and dated 2025-07-25 — go forth and manipulate some tree nodes, you absolute icon 👑💅