Skip to content

md-to-html-api-doc.md

Latest commit

 

History

History
170 lines (135 loc) · 8.77 KB

md-to-html-api-doc.md

File metadata and controls

170 lines (135 loc) · 8.77 KB

MD-CLI 渲染接口文档

本文档描述了将 Markdown 文本转换为微信公众号兼容 HTML 的 API 接口。

接口概览

  • 接口地址: http://localhost:8800/api/render
  • 请求方式: POST
  • Content-Type: application/json

请求参数

请求体为一个 JSON 对象，支持以下参数：

基础参数

参数名 类型 必填 默认值 可选值/说明
markdown string 是 - 需要渲染的 Markdown 源码内容
path string 否 - Markdown 文件路径（与 markdown 二选一）
theme string 否 'default' - 'default': 经典主题
- 'grace': 优雅主题
- 'simple': 简洁主题
primaryColor string 否 '#0F4C81' 主题色，支持任意 CSS 颜色值。预设主题色参考：
- 经典蓝: '#0F4C81'
- 翡翠绿: '#009874'
- 活力橘: '#FA5151'
- 柠檬黄: '#FECE00'
- 薰衣紫: '#92617E'
- 天空蓝: '#55C9EA'
- 玫瑰金: '#B76E79'
- 橄榄绿: '#556B2F'
- 石墨黑: '#333333'
- 雾烟灰: '#A9A9A9'
- 樱花粉: '#FFB7C5'
fontFamily string 否 (系统字体栈)* 任何有效的 CSS font-family 字符串
fontSize string 否 '16px' 任何有效的 CSS 字体大小单位，例如：
- '14px', '15px', '17px'
- '1em', '1.2rem'
highlightTheme string 否 'github' Highlight.js 支持的所有主题名称，例如：
- 'github'
- 'monokai'
- 'dracula'
- 'vs2015'
- 'atom-one-dark'

*默认字体栈: "-apple-system-font,BlinkMacSystemFont, Helvetica Neue, PingFang SC, Hiragino Sans GB , Microsoft YaHei UI , Microsoft YaHei ,Arial,sans-serif"

样式配置参数

参数名 类型 必填 默认值 说明
isMacCodeBlock boolean 否 true 是否显示 Mac 风格代码块（带红黄绿三个圆点）
isShowLineNumber boolean 否 false 是否显示代码块行号
legend string 否 'alt' 图注显示格式：
- 'alt': 只显示 alt
- 'title': 只显示 title
- 'alt-title': alt 优先
- 'title-alt': title 优先
- 'none': 不显示
isCiteStatus boolean 否 false 是否开启微信外链接引用（在文末显示引用链接列表）
isCountStatus boolean 否 false 是否显示字数统计和阅读时间
isUseIndent boolean 否 false 是否开启段落首行缩进（2em）
isUseJustify boolean 否 false 是否开启段落两端对齐
themeMode string 否 'light' 主题模式：
- 'light': 浅色模式
- 'dark': 深色模式

响应结构

成功响应 (200 OK)

返回 JSON 对象，包含渲染后的 HTML 字符串。

{
  "html": "<section class=\"...\" ..."
}

错误响应

  • 400 Bad Request: 缺少必填参数

    {
  "error": "Markdown content is required"
}

  • 500 Internal Server Error: 服务器内部渲染错误

    {
  "error": "Error message details..."
}

调用示例

基础调用 (curl)

curl -X POST http://localhost:8800/api/render \
  -H "Content-Type: application/json" \
  -d '{
    "markdown": "# Hello World\n\nThis is a **markdown** text.",
    "theme": "default",
    "primaryColor": "#0F4C81"
  }'

完整参数调用 (curl)

curl -X POST http://localhost:8800/api/render \
  -H "Content-Type: application/json" \
  -d '{
    "markdown": "# 标题\n\n**加粗**文本和`代码`\n\n> 引用块\n\n- 列表项\n\n[链接](https://example.com)",
    "theme": "grace",
    "primaryColor": "#009874",
    "fontSize": "16px",
    "highlightTheme": "github",
    "isMacCodeBlock": true,
    "isShowLineNumber": true,
    "legend": "alt",
    "isCiteStatus": true,
    "isCountStatus": true,
    "isUseIndent": true,
    "isUseJustify": false,
    "themeMode": "light"
  }'

使用 JavaScript (Fetch) 调用

async function renderMarkdown() {
  const response = await fetch('http://localhost:8800/api/render', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      markdown: '## 测试标题\n\n这是一段测试文本。\n\n[链接](https://example.com)',
      theme: 'grace',
      primaryColor: '#009874',
      fontSize: '16px',
      isCiteStatus: true,
      isCountStatus: true,
      isUseIndent: true
    })
  })

  const data = await response.json()
  if (response.ok) {
    console.log('Rendered HTML:', data.html)
  }
  else {
    console.error('Error:', data.error)
  }
}

使用 Python 调用

import requests
import json

url = "http://localhost:8800/api/render"

payload = {
    "markdown": "# 标题\n\n**加粗**文本\n\n> 引用\n\n[链接](https://example.com)",
    "theme": "grace",
    "primaryColor": "#009874",
    "isCiteStatus": True,
    "isCountStatus": True,
    "isUseIndent": True
}

response = requests.post(url, json=payload)

if response.status_code == 200:
    html = response.json()["html"]
    print("渲染成功，HTML 长度:", len(html))
else:
    print("错误:", response.json()["error"])

启动服务

cd packages/md-cli
node index.js

服务默认运行在 http://localhost:8800。