2026-01-26 04:12:14 +00:00
{# retoor < retoor @ molodetz . nl > #}
{% extends 'page.html' %}
2026-01-25 01:47:47 +00:00
2026-01-26 04:12:14 +00:00
{% set page_title = "markdown" %}
{% set breadcrumb = [{"url": "api/index.html", "title": "API Reference"}, {"title": "markdown"}] %}
{% set prev_page = {"url": "api/dataset.html", "title": "dataset"} %}
{% set next_page = {"url": "api/web.html", "title": "web"} %}
{% block article %}
2026-01-25 01:47:47 +00:00
< h1 > markdown</ h1 >
< p > The < code > markdown</ code > module provides bidirectional conversion between Markdown and HTML. It supports common Markdown syntax including headings, emphasis, code blocks, lists, links, and images.</ p >
< pre >< code > import "markdown" for Markdown</ code ></ pre >
< h2 > Markdown Class</ h2 >
< div class = "class-header" >
< h3 > Markdown</ h3 >
< p > Markdown to HTML converter</ p >
</ div >
< h3 > Static Methods</ h3 >
< div class = "method-signature" >
< span class = "method-name" > Markdown.toHtml</ span > (< span class = "param" > text</ span > ) → < span class = "type" > String</ span >
</ div >
< p > Converts Markdown text to HTML.</ p >
< ul class = "param-list" >
< li >< span class = "param-name" > text</ span > < span class = "param-type" > (String)</ span > - Markdown text</ li >
< li >< span class = "returns" > Returns:</ span > HTML string</ li >
</ ul >
< pre >< code > var html = Markdown.toHtml("# Hello World")
System.print(html) // < h1> Hello World< /h1> </ code ></ pre >
< div class = "method-signature" >
< span class = "method-name" > Markdown.toHtml</ span > (< span class = "param" > text</ span > , < span class = "param" > options</ span > ) → < span class = "type" > String</ span >
</ div >
< p > Converts Markdown text to HTML with options.</ p >
< ul class = "param-list" >
< li >< span class = "param-name" > text</ span > < span class = "param-type" > (String)</ span > - Markdown text</ li >
< li >< span class = "param-name" > options</ span > < span class = "param-type" > (Map)</ span > - Conversion options</ li >
< li >< span class = "returns" > Returns:</ span > HTML string</ li >
</ ul >
< div class = "method-signature" >
< span class = "method-name" > Markdown.fromHtml</ span > (< span class = "param" > html</ span > ) → < span class = "type" > String</ span >
</ div >
< p > Converts HTML to Markdown text.</ p >
< ul class = "param-list" >
< li >< span class = "param-name" > html</ span > < span class = "param-type" > (String)</ span > - HTML string</ li >
< li >< span class = "returns" > Returns:</ span > Markdown text</ li >
</ ul >
< pre >< code > var md = Markdown.fromHtml("< h1> Hello World< /h1> ")
System.print(md) // # Hello World</ code ></ pre >
< div class = "method-signature" >
< span class = "method-name" > Markdown.fromHtml</ span > (< span class = "param" > html</ span > , < span class = "param" > options</ span > ) → < span class = "type" > String</ span >
</ div >
< p > Converts HTML to Markdown text with options.</ p >
< ul class = "param-list" >
< li >< span class = "param-name" > html</ span > < span class = "param-type" > (String)</ span > - HTML string</ li >
< li >< span class = "param-name" > options</ span > < span class = "param-type" > (Map)</ span > - Conversion options</ li >
< li >< span class = "returns" > Returns:</ span > Markdown text</ li >
</ ul >
< h2 > Options</ h2 >
< h3 > toHtml Options</ h3 >
< table >
< tr >
< th > Option</ th >
< th > Type</ th >
< th > Default</ th >
< th > Description</ th >
</ tr >
< tr >
< td >< code > safeMode</ code ></ td >
< td > Bool</ td >
< td >< code > false</ code ></ td >
< td > Escape HTML in input to prevent XSS</ td >
</ tr >
</ table >
< h3 > fromHtml Options</ h3 >
< table >
< tr >
< th > Option</ th >
< th > Type</ th >
< th > Default</ th >
< th > Description</ th >
</ tr >
< tr >
< td >< code > stripUnknown</ code ></ td >
< td > Bool</ td >
< td >< code > true</ code ></ td >
< td > Strip unknown HTML tags, keeping their content</ td >
</ tr >
</ table >
< h2 > Supported Syntax</ h2 >
< h3 > Headings</ h3 >
< pre >< code > # Heading 1
## Heading 2
### Heading 3
#### Heading 4
##### Heading 5
###### Heading 6</ code ></ pre >
< p > Converts to < code > < h1> </ code > through < code > < h6> </ code > tags.</ p >
< h3 > Emphasis</ h3 >
< pre >< code > *italic* or _italic_
**bold** or __bold__
~~strikethrough~~</ code ></ pre >
< p > Converts to < code > < em> </ code > , < code > < strong> </ code > , and < code > < del> </ code > tags.</ p >
< h3 > Code</ h3 >
< pre >< code > Inline `code` here
```
Code block
Multiple lines
```</ code ></ pre >
< p > Inline code uses < code > < code> </ code > , blocks use < code > < pre>< code> </ code > .</ p >
< h3 > Lists</ h3 >
< pre >< code > Unordered:
- Item 1
- Item 2
* Also works
+ And this
Ordered:
1. First
2. Second
3. Third</ code ></ pre >
< p > Creates < code > < ul> </ code > and < code > < ol> </ code > with < code > < li> </ code > items.</ p >
< h3 > Links and Images</ h3 >
< pre >< code > [Link text](https://example.com)
</ code ></ pre >
< p > Creates < code > < a href="..."> </ code > and < code > < img src="..." alt="..."> </ code > .</ p >
< h3 > Blockquotes</ h3 >
< pre >< code > > This is a quote
> Multiple lines</ code ></ pre >
< p > Creates < code > < blockquote> </ code > with < code > < p> </ code > content.</ p >
< h3 > Horizontal Rule</ h3 >
< pre >< code > ---
***
___</ code ></ pre >
< p > Creates < code > < hr> </ code > tag.</ p >
< h3 > Paragraphs</ h3 >
< p > Text separated by blank lines becomes < code > < p> </ code > elements.</ p >
< h2 > HTML to Markdown Conversions</ h2 >
< p > The < code > fromHtml</ code > method converts the following HTML elements to Markdown:</ p >
< table >
< tr >
< th > HTML</ th >
< th > Markdown</ th >
</ tr >
< tr >
< td >< code > < h1> </ code > to < code > < h6> </ code ></ td >
< td >< code > #</ code > to < code > ######</ code ></ td >
</ tr >
< tr >
< td >< code > < strong> </ code > , < code > < b> </ code ></ td >
< td >< code > **text**</ code ></ td >
</ tr >
< tr >
< td >< code > < em> </ code > , < code > < i> </ code ></ td >
< td >< code > *text*</ code ></ td >
</ tr >
< tr >
< td >< code > < code> </ code ></ td >
< td >< code > `text`</ code ></ td >
</ tr >
< tr >
< td >< code > < pre>< code> </ code ></ td >
< td > Fenced code block</ td >
</ tr >
< tr >
< td >< code > < a href="url"> </ code ></ td >
< td >< code > [text](url)</ code ></ td >
</ tr >
< tr >
< td >< code > < img src="url" alt=""> </ code ></ td >
< td >< code > </ code ></ td >
</ tr >
< tr >
< td >< code > < ul>< li> </ code ></ td >
< td >< code > - item</ code ></ td >
</ tr >
< tr >
< td >< code > < ol>< li> </ code ></ td >
< td >< code > 1. item</ code ></ td >
</ tr >
< tr >
< td >< code > < blockquote> </ code ></ td >
< td >< code > > text</ code ></ td >
</ tr >
< tr >
< td >< code > < hr> </ code ></ td >
< td >< code > ---</ code ></ td >
</ tr >
< tr >
< td >< code > < del> </ code > , < code > < s> </ code ></ td >
< td >< code > ~~text~~</ code ></ td >
</ tr >
</ table >
< p > Container tags (< code > < div> </ code > , < code > < span> </ code > , < code > < section> </ code > , etc.) are stripped but their content is preserved. Script and style tags are removed entirely.</ p >
< h2 > Examples</ h2 >
< h3 > Basic Conversion</ h3 >
< pre >< code > import "markdown" for Markdown
var md = "
# Welcome
This is a **Markdown** document with:
- Lists
- *Emphasis*
- `Code`
Visit [Wren](https://wren.io) for more.
"
var html = Markdown.toHtml(md)
System.print(html)</ code ></ pre >
< h3 > Safe Mode for User Content</ h3 >
< pre >< code > import "markdown" for Markdown
var userInput = "# Title\n< script> alert('xss')< /script> \nContent here."
var safeHtml = Markdown.toHtml(userInput, {"safeMode": true})
System.print(safeHtml)</ code ></ pre >
< h3 > Rendering a Blog Post</ h3 >
< pre >< code > import "markdown" for Markdown
import "io" for File
var postContent = File.read("post.md")
var html = Markdown.toHtml(postContent)
var page = "< html>
< head>< title> Blog< /title>< /head>
< body>
< article>
%(html)
< /article>
< /body>
< /html> "
File.write("post.html", page)</ code ></ pre >
< h3 > Code Blocks with Language Hints</ h3 >
< pre >< code > import "markdown" for Markdown
var md = "
```wren
System.print(\"Hello, World!\")
```
"
var html = Markdown.toHtml(md)
System.print(html)
// < pre>< code> System.print("Hello, World!")< /code>< /pre> </ code ></ pre >
< h3 > Combining with Templates</ h3 >
< pre >< code > import "markdown" for Markdown
import "jinja" for Environment, DictLoader
var env = Environment.new(DictLoader.new({
"base": "< html>< body> {{ content }}< /body>< /html> "
}))
var md = "# Hello\n\nThis is **Markdown**."
var content = Markdown.toHtml(md)
var html = env.getTemplate("base").render({"content": content})
System.print(html)</ code ></ pre >
< h3 > Converting HTML to Markdown</ h3 >
< pre >< code > import "markdown" for Markdown
var html = "
< html>
< body>
< h1> Article Title< /h1>
< p> This is < strong> important< /strong> content.< /p>
< ul>
< li> First item< /li>
< li> Second item< /li>
< /ul>
< /body>
< /html>
"
var md = Markdown.fromHtml(html)
System.print(md)
// # Article Title
//
// This is **important** content.
//
// - First item
// - Second item</ code ></ pre >
< h3 > Cleaning HTML for Plain Text</ h3 >
< pre >< code > import "markdown" for Markdown
var webContent = "< div>< script> alert('xss')< /script>< p> Safe < b> content< /b>< /p>< /div> "
var clean = Markdown.fromHtml(webContent)
System.print(clean) // Safe **content**</ code ></ pre >
< div class = "admonition warning" >
< div class = "admonition-title" > Warning</ div >
< p > When rendering user-provided Markdown, always use < code > safeMode: true</ code > to prevent cross-site scripting (XSS) attacks. Safe mode escapes HTML entities in the input text.</ p >
</ div >
< div class = "admonition note" >
< div class = "admonition-title" > Note</ div >
< p > Language identifiers after code fences (e.g., < code > ```wren</ code > ) are currently ignored. The code is rendered without syntax highlighting. Consider using a client-side syntax highlighter like Prism.js or highlight.js for the resulting HTML.</ p >
</ div >
2026-01-26 04:12:14 +00:00
{% endblock %}
