---
name: "Text::Markup::CommonMark"
section: "3pm"
platform: "linux"
package: "libtext-markup-perl"
version: "0.33-1"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/Text::Markup::CommonMark"
---

# Text::Markup::CommonMark(3pm)

CommonMark Markdown parser for Text::Markup

## Name

Text::Markup::CommonMark - CommonMark Markdown parser for Text::Markup

## Synopsis

```
  use Text::Markup::CommonMark;
  my $html = Text::Markup->new->parse(file => 'README.md');
  my $raw  = Text::Markup->new->parse(
      file    => 'README.md',
      options => [ raw => 1 ],
  );
```

## Description

This is the CommonMark \<https://commonmark.org\> parser for Text::Markup. On load, it replaces the default Text::Markup::Markdown parser for parsing Markdown \<https://daringfireball.net/projects/markdown/\>. Note that Text::Markup does not load this module by default, but when loaded manually will be the preferred Markdown parser.

Text::Markup::CommonMark reads in the file (relying on a BOM \<https://www.unicode.org/unicode/faq/utf\_bom.html#BOM\>), hands it off to CommonMark for parsing, and then returns the generated HTML as an encoded UTF-8 string with an `"http-equiv="Content-Type""` element identifying the encoding as UTF-8.

It recognizes files with the following extensions as CommonMark Markdown:

- *.md*

  - *.mkd*

  - *.mkdn*

  - *.mdown*

  - *.markdown*

  To change it the files it recognizes, load this module directly and pass a regular expression matching the desired extension(s), like so:

```
  use Text::Markup::CommonMark qr{markd?};
```

Normally this module returns the output wrapped in a minimal HTML document skeleton. If you would like the raw output without the skeleton, you can pass the `"raw"` option to `"parse"`.

In addition Text::CommonMark supports all of the CommonMark parse options and render options, including:

- "smart"

  When true, convert straight quotes to curly, --- to em dashes, -- to en dashes. Enabled by default.

- "sourcepos"

  When true, include a data-sourcepos attribute on all block elements. Disabled by default.

  ```
   =item C<hardbreaks>
  ```

  When true, render soft-break elements as hard line breaks. Disabled by default.

  ```
   =item C<nobreaks>
  ```

  When true, render soft-break elements as spaces. Disabled by default.

  ```
   =item C<validate_utf8>
  ```

  When true, validate UTF-8 in the input before parsing, replacing illegal sequences with the replacement character `"U+FFFD"`. Disabled by default.

  ```
   =item C<unsafe>
  ```

  Render raw HTML and unsafe links (`"javascript:"`, `"vbscript:"`, `"file:"`, and `"data:"`, except for `"image/png"`, `"image/gif"`, `"image/jpeg"`, or `"image/webp"` mime types). Raw HTML is replaced by a placeholder HTML comment. Unsafe links are replaced by empty strings. Enabled by default.

## Author

David E. Wheeler \<david@justatheory.com\>

## Copyright and License

Copyright (c) 2011-2024 David E. Wheeler. Some Rights Reserved.

This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself.