API 概览

PSUIP 提供了强大的 API 接口，用于将 PSUIP 格式的 Markdown 内容转换为 HTML 并进行渲染展示。

接口列表

接口名称	方法	用途	返回格式
markdown-to-html	POST	转换 PSUIP 内容为 HTML	JSON
markdown-renderer	GET	直接渲染 PSUIP 内容为页面	HTML 页面

快速开始

1. markdown-to-html 接口

最常用的接口，将 PSUIP 内容转换为 HTML 字符串：


const response = await fetch('https://study-env.dingdaoos.com/api/markdown-to-html', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    markdown: '# Hello PSUIP\n\n[primary][开始使用](https://example.com)',
    width: 800,
    height: 600
  })
});
 
const result = await response.json();
console.log(result.html);

2. markdown-renderer 接口

直接在浏览器中预览 PSUIP 内容：


const markdown = '# Hello PSUIP\n\n[primary][开始使用](https://example.com)';
const encodedMarkdown = encodeURIComponent(markdown);
const url = `https://study-env.dingdaoos.com/api/markdown-renderer?markdown=${encodedMarkdown}`;
 
window.open(url, '_blank');

核心特性

🎨 完整的 PSUIP 语法支持

标准 Markdown：完全兼容标准 Markdown 语法
卡片组件：支持 elegant、techGradient、header 等系列卡片
布局系统：column、row、gallery 等布局方式
图表组件：柱状图、折线图、饼状图等数据可视化
按钮增强：primary、secondary、success 等多种按钮样式

🚀 高性能渲染

响应式设计：自动适配不同屏幕尺寸
优化渲染：服务端预处理，客户端快速显示
缓存机制：相同内容复用渲染结果
异步处理：支持大量内容的批量处理

🔧 开发友好

RESTful API：标准的 HTTP 接口
多语言支持：提供 JavaScript、Python 等示例
错误处理：详细的错误信息和状态码
调试工具：直观的预览界面

使用流程

应用场景

📝 内容管理系统


// CMS 编辑器集成
class PSUIPEditor {
  async saveContent(markdown) {
    const html = await this.convertToHtml(markdown);
    await this.database.save({ markdown, html });
  }
  
  async convertToHtml(markdown) {
    const response = await fetch('/api/markdown-to-html', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ markdown })
    });
    const result = await response.json();
    return result.html;
  }
}

🔍 实时预览


// 编辑器实时预览
function setupLivePreview(editor) {
  let debounceTimer;
  
  editor.on('change', (markdown) => {
    clearTimeout(debounceTimer);
    debounceTimer = setTimeout(() => {
      const url = generatePreviewUrl(markdown);
      updatePreviewFrame(url);
    }, 300);
  });
}

📊 报告生成


# 自动化报告生成
def generate_report(data):
    markdown = f"""
    # 数据分析报告
    
    ## 销售概况
    
    [chart:barh]| 部门 | 销售额 |
    | --- | --- |
    | 销售部 | {data['sales']} |
    | 市场部 | {data['marketing']} |
    
    <card:elegantStandard>
    ## 总结
    ### 业绩亮点
    本月销售业绩创历史新高，同比增长 {data['growth']}%
    
    [查看详情](https://dashboard.example.com)
    </card:elegantStandard>
    """
    
    html = convert_markdown_to_html(markdown)
    save_report(html)

🌐 静态网站生成


// 静态网站构建
async function buildSite() {
  const pages = await glob('content/**/*.md');
  
  for (const page of pages) {
    const markdown = await fs.readFile(page, 'utf-8');
    const html = await convertMarkdownToHtml(markdown);
    const outputPath = page.replace('content/', 'dist/').replace('.md', '.html');
    await fs.writeFile(outputPath, html);
  }
}

最佳实践

✅ 推荐做法

缓存策略：对相同内容实现客户端缓存
错误处理：始终使用 try-catch 处理 API 调用
内容验证：发送前验证 Markdown 语法正确性
性能优化：大内容分批处理，避免超时

❌ 避免的做法

同步调用：避免阻塞主线程的同步请求
忽略错误：不处理 API 调用失败的情况
过大内容：单次请求内容过多导致超时
硬编码：将 API 地址硬编码在客户端代码中

错误码参考

错误码	HTTP 状态	说明	解决方案
`INVALID_MARKDOWN`	400	Markdown 语法错误	检查语法格式
`INVALID_PARAMETERS`	400	参数格式错误	验证请求参数
`PROCESSING_ERROR`	500	内容处理失败	简化内容或重试
`TIMEOUT_ERROR`	408	请求超时	减少内容大小
`MEMORY_ERROR`	507	内存不足	分批处理内容

社区支持

GitHub 仓库：psuip/psuip-core
问题反馈：GitHub Issues
讨论区：GitHub Discussions
文档网站：https://psuip.dev

有问题或建议？欢迎通过以上渠道与我们交流！