markdown-renderer

直接在浏览器中渲染 PSUIP 内容，提供即时预览功能。

接口信息

方法：GET
地址：https://study-env.dingdaoos.com/api/markdown-renderer
返回类型：HTML 页面

请求参数

通过 URL 查询参数传递：

参数名	类型	必填	默认值	说明
`markdown`	string	是	-	URL编码后的 PSUIP Markdown 内容
`width`	number	否	800	渲染页面的宽度（像素）
`height`	number	否	600	渲染页面的高度（像素）

参数详细说明

markdown

必须使用 URL 编码 (encodeURIComponent)
支持完整的 PSUIP 语法
建议对特殊字符进行正确编码

width & height

设置渲染容器的尺寸
影响响应式布局效果
影响图表组件的显示

URL 编码示例

JavaScript URL 编码


const markdown = `
<card:headerPrecentCard>
## 市场概述
AI-PC 概念自 2023 年由英特尔提出后，迅速引发行业关注
 
### 中国市场
#### 15%
AI-PC 出货量
 
### 全球市场  
#### 25%
AI-PC 渗透率
</card:headerPrecentCard>
`;
 
const encodedMarkdown = encodeURIComponent(markdown);
const url = `https://study-env.dingdaoos.com/api/markdown-renderer?markdown=${encodedMarkdown}&width=1200&height=600`;
 
// 在新窗口中打开
window.open(url, '_blank');

Python URL 编码


import urllib.parse
 
markdown = """
<card:elegantStandard>
## 产品介绍
### 核心功能
我们提供业界领先的解决方案
 
[了解更多](https://example.com)
</card:elegantStandard>
"""
 
encoded_markdown = urllib.parse.quote(markdown)
url = f"https://study-env.dingdaoos.com/api/markdown-renderer?markdown={encoded_markdown}&width=1000&height=700"
 
print(f"预览链接: {url}")

PHP URL 编码


<?php
$markdown = '
<card:elegantStandard>
## 产品介绍
### 核心功能
我们提供业界领先的解决方案
 
[了解更多](https://example.com)
</card:elegantStandard>
';
 
$encodedMarkdown = urlencode($markdown);
$url = "https://study-env.dingdaoos.com/api/markdown-renderer?markdown={$encodedMarkdown}&width=1000&height=700";
 
echo "预览链接: " . $url;
?>

使用示例

1. 基础卡片预览


https://study-env.dingdaoos.com/api/markdown-renderer?markdown=%3Ccard%3AelegantStandard%3E%0A%23%23%20%E4%BA%A7%E5%93%81%E4%BB%8B%E7%BB%8D%0A%23%23%23%20%E6%A0%B8%E5%BF%83%E5%8A%9F%E8%83%BD%0A%E6%88%91%E4%BB%AC%E6%8F%90%E4%BE%9B%E4%B8%9A%E7%95%8C%E9%A2%86%E5%85%88%E7%9A%84%E8%A7%A3%E5%86%B3%E6%96%B9%E6%A1%88%0A%0A%5B%E4%BA%86%E8%A7%A3%E6%9B%B4%E5%A4%9A%5D(https%3A//example.com)%0A%3C/card%3AelegantStandard%3E&width=800&height=600

2. 图表展示预览


https://study-env.dingdaoos.com/api/markdown-renderer?markdown=%5Bchart%3Abarh%5D%7C%20%E9%83%A8%E9%97%A8%20%7C%20%E9%94%80%E5%94%AE%E9%A2%9D%20%7C%0A%7C%20---%20%7C%20---%20%7C%0A%7C%20%E9%94%80%E5%94%AE%E9%83%A8%20%7C%201250%20%7C%0A%7C%20%E5%B8%82%E5%9C%BA%E9%83%A8%20%7C%20980%20%7C&width=1000&height=500

3. 复杂布局预览


https://study-env.dingdaoos.com/api/markdown-renderer?markdown=%23%23%20%E4%BA%A7%E5%93%81%E5%AF%B9%E6%AF%94%0A%3Clayout%3Arow%3E%0A%23%23%23%20%E4%BA%A7%E5%93%81A%0A%3Clayout%3Acolumn%3E%0A%23%23%23%23%20%E5%8A%9F%E8%83%BD%E7%89%B9%E6%80%A7%0A-%20%E7%89%B9%E6%80%A71%0A-%20%E7%89%B9%E6%80%A72%0A%23%23%23%23%20%E4%BB%B7%E6%A0%BC%E4%BF%A1%E6%81%AF%0A%2499/%E6%9C%88%0A%3C/layout%3Acolumn%3E%0A%23%23%23%20%E4%BA%A7%E5%93%81B%0A%3Clayout%3Acolumn%3E%0A%23%23%23%23%20%E5%8A%9F%E8%83%BD%E7%89%B9%E6%80%A7%0A-%20%E7%89%B9%E6%80%A71%0A-%20%E7%89%B9%E6%80%A72%0A%23%23%23%23%20%E4%BB%B7%E6%A0%BC%E4%BF%A1%E6%81%AF%0A%24199/%E6%9C%88%0A%3C/layout%3Acolumn%3E%0A%3C/layout%3Arow%3E&width=1200&height=800

实用工具函数

JavaScript 工具函数


/**
 * 生成 markdown-renderer 预览链接
 * @param {string} markdown - PSUIP Markdown 内容
 * @param {number} width - 宽度
 * @param {number} height - 高度
 * @param {string} baseUrl - 基础 URL
 * @returns {string} 完整的预览链接
 */
function generatePreviewUrl(markdown, width = 800, height = 600, baseUrl = 'https://study-env.dingdaoos.com') {
  const encodedMarkdown = encodeURIComponent(markdown);
  return `${baseUrl}/api/markdown-renderer?markdown=${encodedMarkdown}&width=${width}&height=${height}`;
}
 
/**
 * 在新窗口中打开预览
 * @param {string} markdown - PSUIP Markdown 内容
 * @param {Object} options - 配置选项
 */
function openPreview(markdown, options = {}) {
  const { width = 800, height = 600, baseUrl = 'https://study-env.dingdaoos.com' } = options;
  const url = generatePreviewUrl(markdown, width, height, baseUrl);
  
  const windowFeatures = `width=${width + 100},height=${height + 100},scrollbars=yes,resizable=yes`;
  window.open(url, '_blank', windowFeatures);
}
 
// 使用示例
const markdown = `
# 产品展示
 
<card:elegantStandard>
## 核心特性
### 智能分析
提供强大的数据分析能力
 
[立即体验](https://example.com)
</card:elegantStandard>
`;
 
openPreview(markdown, { width: 1200, height: 800 });

Python 工具函数


import urllib.parse
import webbrowser
 
def generate_preview_url(markdown, width=800, height=600, base_url='https://study-env.dingdaoos.com'):
    """
    生成 markdown-renderer 预览链接
    
    Args:
        markdown (str): PSUIP Markdown 内容
        width (int): 宽度
        height (int): 高度
        base_url (str): 基础 URL
    
    Returns:
        str: 完整的预览链接
    """
    encoded_markdown = urllib.parse.quote(markdown)
    return f"{base_url}/api/markdown-renderer?markdown={encoded_markdown}&width={width}&height={height}"
 
def open_preview(markdown, width=800, height=600, base_url='https://study-env.dingdaoos.com'):
    """
    在浏览器中打开预览
    
    Args:
        markdown (str): PSUIP Markdown 内容
        width (int): 宽度
        height (int): 高度
        base_url (str): 基础 URL
    """
    url = generate_preview_url(markdown, width, height, base_url)
    webbrowser.open(url)
 
# 使用示例
markdown = """
# 数据分析报告
 
[chart:pie]| 销售渠道 | 占比 |
| --- | --- |
| 线上 | 60 |
| 线下 | 40 |
"""
 
open_preview(markdown, width=1000, height=700)

响应特性

完整的 HTML 页面：包含所有必要的 CSS 和 JavaScript
响应式设计：自动适配不同设备和屏幕尺寸
交互功能：支持图表交互、按钮点击等
实时渲染：内容变更后刷新页面即可看到效果

使用场景

1. 开发调试


// 开发时快速预览 PSUIP 内容
function debugPreview(markdown) {
  const url = generatePreviewUrl(markdown);
  console.log('预览链接:', url);
  window.open(url, '_blank');
}

2. 内容编辑器


// 编辑器中的预览按钮
class MarkdownEditor {
  constructor(containerId) {
    this.container = document.getElementById(containerId);
    this.setupPreviewButton();
  }
  
  setupPreviewButton() {
    const previewBtn = document.createElement('button');
    previewBtn.textContent = '预览';
    previewBtn.onclick = () => {
      const markdown = this.getMarkdown();
      openPreview(markdown);
    };
    this.container.appendChild(previewBtn);
  }
  
  getMarkdown() {
    return this.container.querySelector('textarea').value;
  }
}

3. 文档分享


// 生成可分享的预览链接
function shareMarkdown(markdown, title = '文档预览') {
  const url = generatePreviewUrl(markdown);
  
  if (navigator.share) {
    navigator.share({
      title: title,
      url: url
    });
  } else {
    // 复制到剪贴板
    navigator.clipboard.writeText(url).then(() => {
      alert('预览链接已复制到剪贴板');
    });
  }
}

4. 自动化测试


# 自动化测试中验证渲染效果
import requests
from selenium import webdriver
 
def test_markdown_rendering(markdown):
    """测试 Markdown 渲染效果"""
    url = generate_preview_url(markdown)
    
    # 检查页面是否正常响应
    response = requests.get(url)
    assert response.status_code == 200
    
    # 使用 Selenium 检查渲染结果
    driver = webdriver.Chrome()
    driver.get(url)
    
    # 检查是否包含预期元素
    assert driver.find_element_by_class_name('psuip-root')
    
    driver.quit()

错误处理

常见错误情况

URL 编码错误
- 特殊字符未正确编码
- 超长 URL（超过浏览器限制）
- 中文字符编码问题
参数错误
- 缺少必填参数 markdown
- 参数格式不正确
- 非法的宽高值
内容错误
- Markdown 语法错误
- 不支持的组件类型
- 图表数据格式错误

错误处理示例


function safeOpenPreview(markdown, options = {}) {
  try {
    // 验证 Markdown 内容
    if (!markdown || typeof markdown !== 'string') {
      throw new Error('Markdown 内容不能为空');
    }
    
    // 检查内容长度（URL 限制）
    const encodedLength = encodeURIComponent(markdown).length;
    if (encodedLength > 2000) {
      throw new Error('内容过长，建议使用 markdown-to-html 接口');
    }
    
    // 验证尺寸参数
    const { width = 800, height = 600 } = options;
    if (width <= 0 || height <= 0) {
      throw new Error('宽高必须为正数');
    }
    
    openPreview(markdown, options);
    
  } catch (error) {
    console.error('预览失败:', error.message);
    alert(`预览失败: ${error.message}`);
  }
}

性能考虑

URL 长度限制

不同浏览器对 URL 长度有不同限制：

Chrome: ~8192 字符
Firefox: ~65536 字符
Safari: ~80000 字符
IE: ~2083 字符

优化建议

内容分割：长内容考虑使用 markdown-to-html 接口
缓存策略：相同内容可以缓存渲染结果
懒加载：图片和图表使用懒加载
压缩传输：服务端启用 gzip 压缩

使用限制

建议单次预览的 Markdown 内容不超过 1000 行
图表数据量建议控制在 100 条以内
避免过多的嵌套布局结构
图片建议使用外链而非 base64 编码