wren/manual_src/pages/api/markdown.html

{# retoor <retoor@molodetz.nl> #}
{% extends 'page.html' %}

{% 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 %}
                <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, images, and GitHub Flavored Markdown (GFM) extensions like tables, task lists, and autolinks.</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)  // &lt;h1&gt;Hello World&lt;/h1&gt;</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("&lt;h1&gt;Hello World&lt;/h1&gt;")
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>&lt;h1&gt;</code> through <code>&lt;h6&gt;</code> tags.</p>

                <h3>Emphasis</h3>
                <pre><code>*italic* or _italic_
**bold** or __bold__
~~strikethrough~~</code></pre>
                <p>Converts to <code>&lt;em&gt;</code>, <code>&lt;strong&gt;</code>, and <code>&lt;del&gt;</code> tags.</p>

                <h3>Code</h3>
                <pre><code>Inline `code` here

```
Code block
Multiple lines
```

```javascript
const x = 1;
```</code></pre>
                <p>Inline code uses <code>&lt;code&gt;</code>, blocks use <code>&lt;pre&gt;&lt;code&gt;</code>. Language identifiers after the opening fence add a <code>class="language-{lang}"</code> attribute to the code element for syntax highlighting integration.</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>&lt;ul&gt;</code> and <code>&lt;ol&gt;</code> with <code>&lt;li&gt;</code> items.</p>

                <h3>Task Lists (GFM)</h3>
                <pre><code>- [ ] Unchecked task
- [x] Checked task
- [X] Also checked</code></pre>
                <p>Creates <code>&lt;ul class="task-list"&gt;</code> with checkbox inputs. Checkboxes are rendered as disabled to indicate they are display-only.</p>

                <h3>Tables (GFM)</h3>
                <pre><code>| Header 1 | Header 2 | Header 3 |
|----------|:--------:|---------:|
| Left     | Center   | Right    |
| Cell     | Cell     | Cell     |</code></pre>
                <p>Creates HTML tables with <code>&lt;thead&gt;</code> and <code>&lt;tbody&gt;</code>. Column alignment is specified in the separator row using colons: <code>:---</code> for left, <code>:---:</code> for center, <code>---:</code> for right.</p>

                <h3>Autolinks (GFM)</h3>
                <pre><code>Visit https://example.com for more info.
Email me at user@example.com</code></pre>
                <p>Bare URLs starting with <code>http://</code> or <code>https://</code> and email addresses are automatically converted to clickable links.</p>

                <h3>Links and Images</h3>
                <pre><code>[Link text](https://example.com)
![Alt text](image.png)</code></pre>
                <p>Creates <code>&lt;a href="..."&gt;</code> and <code>&lt;img src="..." alt="..."&gt;</code>.</p>

                <h3>Blockquotes</h3>
                <pre><code>&gt; This is a quote
&gt; Multiple lines</code></pre>
                <p>Creates <code>&lt;blockquote&gt;</code> with <code>&lt;p&gt;</code> content.</p>

                <h3>Horizontal Rule</h3>
                <pre><code>---
***
___</code></pre>
                <p>Creates <code>&lt;hr&gt;</code> tag.</p>

                <h3>Paragraphs</h3>
                <p>Text separated by blank lines becomes <code>&lt;p&gt;</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>&lt;h1&gt;</code> to <code>&lt;h6&gt;</code></td>
                        <td><code>#</code> to <code>######</code></td>
                    </tr>
                    <tr>
                        <td><code>&lt;strong&gt;</code>, <code>&lt;b&gt;</code></td>
                        <td><code>**text**</code></td>
                    </tr>
                    <tr>
                        <td><code>&lt;em&gt;</code>, <code>&lt;i&gt;</code></td>
                        <td><code>*text*</code></td>
                    </tr>
                    <tr>
                        <td><code>&lt;code&gt;</code></td>
                        <td><code>`text`</code></td>
                    </tr>
                    <tr>
                        <td><code>&lt;pre&gt;&lt;code&gt;</code></td>
                        <td>Fenced code block</td>
                    </tr>
                    <tr>
                        <td><code>&lt;a href="url"&gt;</code></td>
                        <td><code>[text](url)</code></td>
                    </tr>
                    <tr>
                        <td><code>&lt;img src="url" alt=""&gt;</code></td>
                        <td><code>![alt](url)</code></td>
                    </tr>
                    <tr>
                        <td><code>&lt;ul&gt;&lt;li&gt;</code></td>
                        <td><code>- item</code></td>
                    </tr>
                    <tr>
                        <td><code>&lt;ol&gt;&lt;li&gt;</code></td>
                        <td><code>1. item</code></td>
                    </tr>
                    <tr>
                        <td><code>&lt;blockquote&gt;</code></td>
                        <td><code>&gt; text</code></td>
                    </tr>
                    <tr>
                        <td><code>&lt;hr&gt;</code></td>
                        <td><code>---</code></td>
                    </tr>
                    <tr>
                        <td><code>&lt;del&gt;</code>, <code>&lt;s&gt;</code></td>
                        <td><code>~~text~~</code></td>
                    </tr>
                    <tr>
                        <td><code>&lt;table&gt;</code></td>
                        <td>GFM table syntax</td>
                    </tr>
                </table>

                <p>Container tags (<code>&lt;div&gt;</code>, <code>&lt;span&gt;</code>, <code>&lt;section&gt;</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&lt;script&gt;alert('xss')&lt;/script&gt;\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 = "&lt;html&gt;
&lt;head&gt;&lt;title&gt;Blog&lt;/title&gt;&lt;/head&gt;
&lt;body&gt;
&lt;article&gt;
%(html)
&lt;/article&gt;
&lt;/body&gt;
&lt;/html&gt;"

File.write("post.html", page)</code></pre>

                <h3>Code Blocks with Language Classes</h3>
                <pre><code>import "markdown" for Markdown

var md = "
```wren
System.print(\"Hello, World!\")
```
"

var html = Markdown.toHtml(md)
System.print(html)
// &lt;pre&gt;&lt;code class="language-wren"&gt;System.print("Hello, World!")&lt;/code&gt;&lt;/pre&gt;</code></pre>

                <h3>Tables</h3>
                <pre><code>import "markdown" for Markdown

var md = "
| Name  | Age | City      |
|-------|----:|:----------|
| Alice |  30 | New York  |
| Bob   |  25 | London    |
"

var html = Markdown.toHtml(md)
System.print(html)</code></pre>

                <h3>Task Lists</h3>
                <pre><code>import "markdown" for Markdown

var md = "
## Project Tasks

- [x] Design database schema
- [x] Implement API endpoints
- [ ] Write unit tests
- [ ] Deploy to production
"

var html = Markdown.toHtml(md)
System.print(html)</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": "&lt;html&gt;&lt;body&gt;{{ content }}&lt;/body&gt;&lt;/html&gt;"
}))

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 = "
&lt;html&gt;
&lt;body&gt;
&lt;h1&gt;Article Title&lt;/h1&gt;
&lt;p&gt;This is &lt;strong&gt;important&lt;/strong&gt; content.&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;First item&lt;/li&gt;
&lt;li&gt;Second item&lt;/li&gt;
&lt;/ul&gt;
&lt;/body&gt;
&lt;/html&gt;
"

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 = "&lt;div&gt;&lt;script&gt;alert('xss')&lt;/script&gt;&lt;p&gt;Safe &lt;b&gt;content&lt;/b&gt;&lt;/p&gt;&lt;/div&gt;"
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 added as <code>class="language-{lang}"</code> to the code element. This is compatible with syntax highlighters like Prism.js or highlight.js.</p>
                </div>
{% endblock %}