Richtext Markdown

The Markdown editor adds Write and Preview controls to the OpenACS richtext widget. It uses Marked and DOMPurify. It supports fenced code, tables, strikethrough, and task lists with read-only markers.

Installation

  1. Copy richtext-markdown into the OpenACS packages directory and install it through the Package Manager.
  2. Reload or restart OpenACS so the editor registers as markdown.
  3. Enable UseHtmlAreaForRichtextP and set RichTextEditor to markdown in the acs-templating parameters to use it in standard richtext fields, including forum message forms.

A specific ad_form field can select the editor with {options {editor markdown}} and {htmlarea_p 1}.

Library administration

The sitewide admin page shows the configured and latest library versions, the source in use, and links to security advisories. To select different versions, set the following parameters in the NaviServer configuration and restart OpenACS.

ns_section ns/server/${server}/acs/richtext-markdown {
    ns_param MarkedVersion 18.2.1
    ns_param DOMPurifyVersion 3.4.18
    ns_param TurndownVersion 7.2.5
}

The example values are the defaults. A local copy takes precedence. When the configured version is missing locally, OpenACS serves it through jsDelivr. Use the admin page to download that version and update the registered URN to the local copy. Downloads are verified against the selected version's SHA-256 file hash from jsDelivr metadata using NaviServer's built-in checksum support. A failed verification leaves the existing local file intact.

Other OpenACS pages can load the same libraries with template::head::add_javascript -src urn:ad:js:marked and template::head::add_javascript -src urn:ad:js:dompurify.

Storage and rendering

New and edited Markdown is submitted as text/html through the standard richtext widget. The HTML ends with a versioned comment containing the original Markdown encoded as UTF-8 Base64. The editor reads the comment when reopening the value. OpenACS can display the HTML directly and use its existing HTML-to-text conversion for search. Keep the comment intact if an import or post-processing step needs to preserve the Markdown source. Keep the size of both the HTML and its source in mind when choosing fields with a fixed storage limit.

Existing text/markdown values are converted when saved through this editor. Other existing values keep their original content and MIME type until edited. Turndown converts legacy HTML to Markdown in Write mode. Some elements, such as tables and definition lists, remain HTML where Markdown cannot preserve their structure. Preview and submission use the original HTML while the body is unchanged. JavaScript is required for preview and Markdown conversion.

Pasting images

In XoWiki, paste a PNG, JPEG, or GIF into the Write tab to insert a Markdown image link. The upload is visible to you in Preview as soon as it finishes. Saving the page attaches each referenced image to the page so it is deleted with the page. Uploading requires permission to create content in the page's folder. Unused staged uploads expire after a day. The OpenACS HTML policy must allow IMG in saved content.

In Forums, paste into Write when the forum allows attachments. Pasted images appear in the editor preview and in the forum's posting preview. Saving the message adds each referenced upload to the message's attachments. Unused draft uploads expire after a day.

In News, pasted images appear in the editor's Preview and in the article confirmation preview. Saving attaches them to the article item, so the URLs keep working across revisions. Unused staged uploads expire after a day.

OpenACS HTML policy

DOMPurify sanitizes the browser-generated HTML. The regular server-side OpenACS HTML checks still apply when the form is submitted. If your acs-kernel HTML policy starts from the stock defaults, allow THEAD and TH for tables, DEL for strikethrough, and IMG for images where appropriate. Allow the start attribute if you use ordered lists starting at a number other than one.