Markdown to Something

API Usage

You can also use our API to convert markdown programmatically. Here are some examples using cURL:

Convert to DOCX

curl -X POST -H "Content-Type: application/json" \
     -d '{"markdown": "# Hello World"}' \
     https://md.colinknapp.com/api/convert

Convert to HTML (Professional Template)

curl -X POST -H "Content-Type: application/json" \
     -d '{"markdown": "# Hello World", "format": "html", "template": "professional", 
     "title": "Document Title", "subtitle": "Document Subtitle", 
     "contact": "Contact Information", "footer": "Footer Text"}' \
     https://md.colinknapp.com/api/convert

Convert to HTML and Send to Haste

curl -X POST -H "Content-Type: application/json" \
     -d '{"markdown": "# Hello World", "format": "html", "template": "professional", 
     "send_to_haste": true, "feature_set": "mermaid"}' \
     https://md.colinknapp.com/api/convert

When using send_to_haste: true, the response will include haste_key, haste_url, and preview_url fields.

Feature Options

Control Mermaid and MathJax support:

• enable_mermaid (boolean, optional): Enable/disable Mermaid diagram support. Defaults to template's default setting.
• enable_mathjax (boolean, optional): Enable/disable MathJax/LaTeX support. Defaults to template's default setting.

Note: Some templates have default restrictions (e.g., monospace disables MathJax by default). Setting these flags overrides the template defaults.

MCP (Model Context Protocol) Integration

This service is available as an MCP server, allowing you to use markdown conversion capabilities directly from MCP-compatible clients like Cursor, Claude Desktop, and other AI assistants.

Server Card Endpoint

The MCP server card is available at:

https://md.colinknapp.com/.well-known/mcp/server-card.json

This endpoint provides metadata about the service, including available tools, capabilities, and transport configuration.

Adding to Cursor

To add this service to Cursor, edit your MCP configuration file (typically ~/.cursor/mcp.json or .cursor/mcp.json in your project):

{
  "mcpServers": {
    "markdown-to-something": {
      "url": "https://md.colinknapp.com"
    }
  }
}

Note: The server card endpoint (/.well-known/mcp/server-card.json) provides the transport configuration. If your MCP client supports server card discovery, it will automatically use the transport details from the server card.

Adding to Claude Desktop

To add this service to Claude Desktop, edit your MCP configuration file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "markdown-to-something": {
      "url": "https://md.colinknapp.com"
    }
  }
}

If your Claude Desktop version requires using mcp-remote, you can use:

{
  "mcpServers": {
    "markdown-to-something": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://md.colinknapp.com"]
    }
  }
}

Available MCP Tools

The service provides the following MCP tool:

• convert_markdown: Convert Markdown content to HTML, DOCX, or PDF format with various template options

Tool Parameters

• markdown (required): The Markdown content to convert
• template (optional): Template name (e.g., 'minimalist-light', 'professional', 'academic'). Default: 'minimalist-light'
• output_format (optional): Output format - 'html', 'docx', or 'pdf'. Default: 'html'
• title (optional): Document title
• subtitle (optional): Document subtitle
• contact (optional): Contact information
• footer (optional): Footer text
• feature_set (optional): Feature set - 'mermaid' for diagrams, 'mathjax' for math, or 'none'. Default: 'mermaid'

Example Usage

Once configured, you can use the service from your MCP client:

# In Cursor or Claude Desktop, you can now ask:
"Convert this markdown to HTML using the professional template:
# My Document
This is my content."

# The AI assistant will use the MCP tool to convert your markdown
# and return the formatted HTML.

Verifying the Setup

You can verify the MCP server card is accessible by visiting:

curl https://md.colinknapp.com/.well-known/mcp/server-card.json

This should return a JSON document describing the service capabilities.

Feature Flags & Template Configuration

Each template can have different default settings for Mermaid and MathJax support. You can override these defaults using the feature flags in the web UI or API.

WCAG-Compliant Templates

All WCAG-compliant templates support both Mermaid and MathJax by default:

• professional, classic, modern, creative
• academic, blog, corporate, newspaper
• minimalist-light, playful, modern-photo, compact

Template Defaults

Some templates have restrictions by default:

• monospace: Mermaid enabled, MathJax disabled (conflicts with monospace styling)
• hacker: Mermaid enabled, MathJax disabled (conflicts with terminal styling)
• glitch: Both disabled (conflicts with glitch effects)
• slides-monospace: Mermaid enabled, MathJax disabled

How Feature Flags Work

1. Mutual Exclusivity: Mermaid and MathJax cannot be enabled simultaneously
2. Web UI: Radio buttons allow choosing one feature set or disabling both
3. API: Use feature_set parameter with value "mermaid", "mathjax", or "none"
4. Default: If not specified, defaults to "mermaid"

Example API Usage

// Enable Mermaid (default)
{"markdown": "# Test", "template": "playful", "feature_set": "mermaid"}

// Enable MathJax instead
{"markdown": "# Test", "template": "playful", "feature_set": "mathjax"}

// Disable both
{"markdown": "# Test", "template": "playful", "feature_set": "none"}

// Legacy format (still supported, but mutually exclusive)
{"markdown": "# Test", "template": "playful", 
 "enable_mermaid": true, "enable_mathjax": false}

Testing & Consistency

All WCAG-compliant templates are tested to ensure consistent behavior:

• ✅ Feature flags work identically across all WCAG templates
• ✅ Script injection respects flag settings
• ✅ Template defaults are properly configured
• ✅ Overrides work as expected

For more details, see FEATURE_FLAGS_CONSISTENCY_PLAN.md in the repository.

Advanced Features

Using Mermaid Diagrams

Include Mermaid diagrams in your markdown using code blocks with the mermaid language identifier:

```mermaid
graph TD
    A[Start] --> B{Is it raining?}
    B -->|Yes| C[Take umbrella]
    B -->|No| D[Enjoy the weather]
```

Using LaTeX Equations

Include mathematical expressions using LaTeX syntax:

• Inline equations: Use single dollar signs $E = mc^2$
• Display equations: Use double dollar signs

  $$
  \frac{d}{dx}[x^n] = nx^{n-1}
  $$

Note: For currency symbols in text, escape the dollar sign with a backslash: \$5.99

Template Feature Configuration

This application uses a feature flag system to control Mermaid and MathJax support per template. This ensures consistency across WCAG-compliant templates while allowing flexibility for templates with special requirements.

Quick Reference

Testing & Verification

All templates are tested to ensure feature flags work correctly:

• ✅ Template defaults are respected when flags not provided
• ✅ Feature flags override template defaults
• ✅ Script injection matches flag settings
• ✅ WCAG templates behave consistently

For Developers: See FEATURE_FLAGS_CONSISTENCY_PLAN.md for the complete testing and implementation plan.

Haste Integration

This application integrates with haste.nixc.us to allow sharing HTML output without requiring server-side storage:

• HTML Sharing: Convert markdown to HTML and share via a unique URL
• Preview Endpoint: View shared HTML documents through the application's preview endpoint

To use this feature, check the "Send HTML to haste.nixc.us" option before converting.

The preview URL format is: https://md.colinknapp.com/haste/{haste_key}

Template Feature Configuration

This application uses a feature flag system to control Mermaid and MathJax support per template. This ensures consistency across WCAG-compliant templates while allowing flexibility for templates with special requirements.

Quick Reference

Testing & Verification

All templates are tested to ensure feature flags work correctly:

• ✅ Template defaults are respected when flags not provided
• ✅ Feature flags override template defaults
• ✅ Script injection matches flag settings
• ✅ WCAG templates behave consistently

For Developers: See FEATURE_FLAGS_CONSISTENCY_PLAN.md for the complete testing and implementation plan.