Markdown (Semantic Module)

← Back to Modules Reference

The Markdown semantic module validates and sanitizes formatted rich text authored in Markdown syntax.

Markdown is standard for documentation, blog articles, support tickets, and community forums. While Markdown is user-friendly, unvalidated Markdown often exposes applications to Cross-Site Scripting (XSS) attacks through embedded raw HTML or unescaped scripts. Decorating a property with Markdown parses content into an Abstract Syntax Tree (AST), validates syntax against permitted features, and blocks dangerous HTML injection by default.

---

Technical Specifications

Attribute	Specification
Scope	Property (Applied to a text property)
Data Type	String
Parser	marked AST parser
Raw HTML	Disallowed by default (allowHtml: false)
Supported Core Features	Headings, bold, italics, links, images, tables, blockquotes, code blocks
Optional Features	Footnotes, task lists, strikethrough, LaTeX math expressions

---

Key Capabilities

1. Raw HTML & Script Blocking (allowHtml: false)

By default, the Markdown semantic module rejects any raw HTML tags (e.g., <script>, <iframe\>, or <img onerror=...>):

• Standard Markdown image syntax (![Alt](url)) and links ([Title](url)) are fully supported.
• Raw HTML elements are immediately blocked, preventing security vulnerabilities without requiring complex client-side sanitizers.

2. Feature Toggles

You can customize exactly which Markdown capabilities are permitted for a given field:

• allowImages (Default: true): Permits Markdown image embedding.
• allowLinks (Default: true): Permits hyperlinks.
• allowTables (Default: true): Permits GFM pipe tables.
• allowStrikethrough (Default: true): Permits ~~strikethrough~~ formatting.
• allowTaskLists (Default: false): Permits - [ ] interactive task checklists.
• allowFootnotes (Default: false): Permits [^1] academic footnote references.
• allowMath (Default: false): Permits LaTeX mathematical formulas (e.g., $E = mc^2$).

3. Safe HTML Exception Handling (allowedTags)

If your application requires allowing a limited subset of safe HTML tags alongside Markdown (e.g. <b>, <i>, or <kbd>), you can enable allowHtml: true. The engine then cross-validates embedded HTML against an allow list of permitted tags.

---

Configuration Options

When configuring the Markdown semantic in the Domain Modeler, you can customize:

Option	Type	Default	Description
allowHtml	boolean	false	Whether to permit raw HTML elements.
allowImages	boolean	true	Permits image syntax ().
allowLinks	boolean	true	Permits link syntax ([Text](url)).
allowTables	boolean	true	Permits GitHub Flavored Markdown tables.
allowTaskLists	boolean	false	Permits checklist items (- [x]).
allowFootnotes	boolean	false	Permits footnote references.
allowMath	boolean	false	Permits LaTeX formulas ($...$ or $$...$$).
allowedTags	string[]	['b', 'i', 'em', 'strong', 'a', ...]	Allow list of permitted HTML tags when allowHtml is enabled.
sanitizeLevel	'strict' | 'moderate' | 'none'	'strict'	Sanitization strictness for embedded HTML.

---

API Lifecycle Examples

1. Creating a Post with Standard Markdown

A client submits formatted Markdown:

POST /posts
Content-Type: application/json

{
  "title": "Release Notes",
  "content": "## Version 2.0\n\nWe are thrilled to announce:\n* **Faster queries**\n* [New documentation](/docs)\n\n| Metric | Improvement |\n|---|---|\n| Latency | -40% |"
}

Server Response (201 Created):

{
  "data": {
    "id": "post_501",
    "title": "Release Notes",
    "content": "## Version 2.0\n\nWe are thrilled to announce:\n* **Faster queries**\n* [New documentation](/docs)\n\n| Metric | Improvement |\n|---|---|\n| Latency | -40% |"
  }
}

---

2. Validation Failure (Raw HTML Disallowed)

When allowHtml: false (default) and a client passes raw HTML tags:

{
  "content": "Check this out <iframe src=\"https://malicious.example.com\"></iframe>"
}

Server Response (400 Bad Request):

{
  "type": "https://docs.apinow.app/errors/validation",
  "title": "Validation Error",
  "status": 400,
  "code": "E_VALIDATION_ERROR",
  "detail": "The field 'content' contains raw HTML which is not allowed by configuration."
}

---

Validation Rules & Modeling Guidelines

• Applicable Property Types: Apply to a String property in the Domain Modeler.
• Length Constraints: Markdown content frequently exceeds standard single-line limits. Ensure the property’s Maximum Length is increased or left unconstrained for articles and documentation.