Once you have parsed a document, you can manipulate the AST using the following methods and attribute assignments:

Structural Operations:

• insert_before(node)
• insert_after(node)
• prepend_child(node)
• append_child(node)
• delete

Attribute Modifications: You can directly modify the following attributes on supported nodes:

• url
• title
• header_level
• list_type
• list_start
• list_tight
• fence_info
• alert_type

Source Position: Call source_position on a node to retrieve its location in the original string as a hash containing :start_line, :start_column, :end_line, and :end_column.

doc = Commonmarker.parse("*Hello* world")
puts doc.first_child.first_child.source_position
# => {:start_line=>1, :start_column=>1, :end_line=>1, :end_column=>7}

You can install commonmarker using Bundler or by installing the gem directly via the command line.

To use it in a Bundler-managed application, add this to your Gemfile:

gem 'commonmarker'

Then run:

bundle

Alternatively, install it globally using:

gem install commonmarker

To set up a local development environment, clone the repository and run the bootstrap script followed by the compilation rake task. If errors occur, ensure you have followed the comrak dependency instructions.

script/bootstrap
bundle exec rake compile

Use the walk method to traverse the entire document tree. This is useful for finding specific node types (like :link) and either extracting data or modifying the tree structure.

Example: Extracting link URLs

doc.walk do |node|
  if node.type == :link
    printf("URL = %s\n", node.url)
  end
end

Example: Removing links and replacing them with plain text

doc.walk do |node|
  if node.type == :link
    node.insert_before(node.first_child)
    node.delete
  end
end

require 'commonmarker'

doc = Commonmarker.parse("# The site\n\n [GitHub](https://www.github.com)")

doc.walk do |node|
  if node.type == :link
    node.insert_before(node.first_child)
    node.delete
  end
end

doc.to_commonmark
# => # The site\n\nGitHub\n

Use Commonmarker.parse to convert a Markdown string into a :document node. This node allows you to inspect the Abstract Syntax Tree (AST), iterate over nodes, and modify the document structure before rendering.

Common operations on a document node include:

• to_html: Renders the node (and its children) to an HTML string.
• to_commonmark: Renders the node back into raw Markdown text.
• walk: Recursively iterates over the node and all its descendants.
• each: Iterates only over the direct children of the node.

require 'commonmarker'

doc = Commonmarker.parse("*Hello* world", options: {
    parse: { smart: true }
})
puts doc.to_html # => <p><em>Hello</em> world</p>\n
doc.walk do |node|
  puts node.type # => [:document, :paragraph, :emph, :text, :text]
end

Use Commonmarker.to_html to quickly convert a Markdown string into an HTML string. This method accepts an optional options hash to configure parsing behavior.

Note: This gem expects UTF-8 encoded strings. Ensure your input is correctly encoded before passing it to Commonmarker.

require 'commonmarker'
Commonmarker.to_html('"Hi *there*"', options: {
    parse: { smart: true }
})
# => <p>“Hi <em>there</em>”</p>\n

Commonmarker currently supports generating output in HTML format. Use the Commonmarker.to_html method to convert a Markdown string into an HTML string.

puts Commonmarker.to_html('*Hello* world!')
# <p><em>Hello</em> world!</p>

When converting code to HTML, you can specify a custom syntax highlighting theme by passing a path to a directory containing .tmtheme files within the plugins options hash.

Commonmarker.to_html(code, plugins: { syntax_highlighter: { theme: "Monokai", path: "./themes" } })

When parsing Markdown, you can pass a hash of options to control the parser's behavior. Use the following keys to configure parsing:

• smart: Boolean. Enables smart typography (e.g., curly quotes).
• default_info_string: String. Sets the default info string for fenced code blocks.
• relaxed_tasklist_matching: Boolean. Enables relaxed matching for task lists.
• relaxed_autolinks: Boolean. Enables relaxed autolinks.
• leave_footnote_definitions: Boolean. If true, leaves footnote definitions in the document.
• sourcepos_chars: Boolean. Enables source position characters.

# Example usage (conceptual Ruby/Hash interface)
options = {
  smart: true,
  default_info_string: "custom_info"
}