NAME

tcmark -- Ffidl based Tcl interface to CommonMark / Github Flavored Markdown

SYNOPSIS

    package require tcmark
    tcmark::render ?options? text
    tcmark::hasgfm

DESCRIPTION

The tcmark package provides a Tcl script level interface to the cmark-gfm library for parsing and rendering CommonMark formatted text which is a formalized specification of the commonly used Markdown syntax. The library includes support for Github extensions which add several features to the original specification. The extended syntax accepted by the library is described in the Github Flavored Markdown specification. Here we refer to all these syntax variants collectively as CommonMark. This package prefers the Github version of the library (cmark-gfm) but provides a fall back to the commonmark library (cmark).

The most important command exported from the package is the render command. >

    tcmark::render ?options? text

The command parses text which should be in CommonMark format and returns it rendered in one of several different output formats. Currently supported output formats are HTML, Latex, Groff manpage, CommonMark XML, CommonMark and plain text.

Parsing

The following options affect parsing of text.

-footnotes

Enable parsing of footnotes.

-ghprelang

Uses Github style tags for code blocks that have a language attribute. This uses the lang attribute on the <pre> tag instead of a class on the <code> tag that wrap the block.

-liberaltag

Be liberal in interpretation of HTML tags.

-smart

Replaces straight quotes with curly quotes and double or triple hyphens with en dash and em dash respectively.

-utf8validate

Checks and replaces invalid UTF-8 character in text with the U+FFFD replacement character.

Rendering

The following options control the rendering of the input text.

-hardbreaks

Renders soft line breaks as hard line breaks.

-nobreaks

Renders soft line breaks as spaces.

-sourcepos

Includes the data-sourcepos attribute on all block elements.

-to format

Specifies the output format. format must be one of html, latex, man , xml, commonmark or text. The man output is a groff manpage page without the header.

-unsafe

Enables raw HTML by placeholder comments and unsafe links such as javascript:, vbscript: etc. By default, raw HTML is replaced by placeholder string and unsafe links removed.

-width width

Specifies a max line width for wrapping. The default of 0 implies no wrapping. Only applies to CommonMark, Latex, man and text output formats.

Note that the HTML output format is a fragment and does not include any HTML header boilerplate.

Enabling GFM extensions

By default, the command adheres to the CommonMark specification. Various extensions specified in Github Flavored Markdown (GFM) may be enabled through the options below.

-gfm

Enables all GFM extensions. Equivalent to specifying all options below. Throws an error in fallback mode, i.e. when libcmark is used.

-autolink

Enables autolink enhancements. Throws an error in fallback mode, i.e. when libcmark is used.

-strikethrough

Enables the strikethrough extension for wrapping strikethrough text in tilde ~ characters. Throws an error in fallback mode, i.e. when libcmark is used.

-table

Enables the table for formatting tables. Throws an error in fallback mode, i.e. when libcmark is used.

-tagfilter

Enables the tagfilter extension that disallows certain HTML tags. Throws an error in fallback mode, i.e. when libcmark is used.

In order to check for libcmark-gfm availability, the following command returns true in that case.

    tcmark::hasgfm

ORIGIN

Original idea and documentation borrowed from Ashok P. Nadkarni's tclcmark package.