"If you think it's expensive to hire a professional to do the job, wait until you hire an amateur"

Red Adair

Obix CommonMark Content Plugin

This content plugin parses CommonMark and GitHub-Flavored Markdown, using the CommonMark parser, provided by the League of Extraordinary Packages.

Raison d'être

Although my HTML and CSS skills are more than adequate for writing website content without the need for a WYSIWYG editor, it can be cumbersome and time-consuming. However, using a WYSIWYG editor has its own disadvantages. Markdown offers a nice compromise between WYSIWYG editing and manually writing HTML and CSS.

If one does not want to use the TinyMCE editor, write raw HTML and CSS, or install a third-party extension in Joomla, one can use CodeMirror, which is bundled by default. Content created with Markdown, whether through CodeMirror or without an editor, is not displayed as regular HTML by default. This plugin parses Markdown content and renders it as standard HTML.

Minimal requirements

Joomla! 5.0
PHP 8.2

BEWARE: Installing this plugin on a server runnning a PHP version that does not match the required minimum, will result in a fatal error and render the site unusable!

Installation and configuration

Installation is the same as for any other Joomla plugin. If it is installed for the first time, as opposed to upgraded, the plugin is supposed to be activated automatically. Doesn't do any harm to check though :)

Configuration

Basic

Enabled for editors
Only enables CommonMark functionality for selected editors.
Enable syntax highlighting
Enables syntax highlighting. Only applicable to CodeMirror editor.
Enable Markdown parsing
Enables parsing of Markdown in content. Currently only in Articles (com_content) and Custom Modules (mod_custom).

Security

HTML input
strip: Strip all HTML
allow: Allow all HTML input as-is
escape: Escape all HTML
Allow unsafe links
Prevent parsing unsafe links: javascript:, vbscript:, file:, data: (except for data:image in png, gif, jpeg, or webp format).
Maximum nesting level
If you need to parse untrusted input, consider setting a reasonable max_nesting_level (perhaps 10-50) depending on your needs. Once this nesting level is hit, any subsequent Markdown will be rendered as plain text. Markdown content which is too deeply-nested (like 10,000 nested blockquotes: ‘> > > > > …’) could result in long render times or segfaults.

Flavor & Extensions

Flavor
CommonMark: Parses Markdown according to the CommonMark Specifications
GitHub-Flavor: Parses Markdown according to the GitHub Flavored Markdown Specifications
Extensions

Manually select individual additonal extensions.

GitHub-Flavor

The following extensions are automatically included when the GitHub flavor is selected and can also be manually chosen when using the CommonMark flavor.

Autolink
Enables automatic linking of URLs within text without needing to wrap them with Markdown syntax.
Disallowed Raw HTML
Disables certain kinds of HTML tags that could affect page rendering.
Strikethrough
Allows using tilde characters (~~) for ~strikethrough~ formatting.
Tables
Enables you to create HTML tables.
Task Lists
Allows the creation of task lists.
Other
Attributes
Add HTML attributes (like id and class) from within the Markdown content.
Description Lists
Create <dl> description lists using Markdown Extra’s syntax.
Embed
Embed rich content (like videos, tweets, and more) from other websites.
External Links
Tags external links with additional markup.
Footnotes
Add footnote references throughout the document and show a listing of them at the bottom.
Front Matter
Parses YAML front matter from your Markdown input.
Heading Permalinks
Makes heading elements linkable.
Inlines Only
Only includes standard CommonMark inline elements - perfect for handling comments and other short bits of text where you only want bold, italic, links, etc..
Smart Punctuation
Intelligently converts ASCII quotes, dashes, and ellipses to their fancy Unicode equivalents
Table of Contents
Automatically inserts links to the headings at the top of your document.

Points of attention

  • Please note that only UTF-8 and ASCII encodings are supported. If your Markdown uses a different encoding please convert it to UTF-8 before running it through this library.
  • Currently only article and custom module content is parsed.
  • Use caution when enabling the plugin on sites with existing content. If the content includes HTML, ensure the plugin's HTML input security settings are configured to allow all HTML input as-is.

Joomla! Extensions