JSON 转 Markdown

实际开发中最常见的用法：调用 GitHub API 后嵌套对象拍平为点号键名，再用本工具生成 Markdown 表格。

// 1) 调用 GitHub API 获取用户列表
async function fetchUsers() {
  const res = await fetch('https://api.github.com/users?per_page=10');
  return await res.json();
}

// 2) 嵌套拍平函数（与本工具的拍平逻辑等价）
function flattenObject(obj, prefix = '', sep = '.', result = {}, depth = 0, maxDepth = 3) {
  if (!obj || typeof obj !== 'object' || Array.isArray(obj)) return result;
  if (depth >= maxDepth) {
    if (prefix) result[prefix] = JSON.stringify(obj);
    return result;
  }
  for (const [k, v] of Object.entries(obj)) {
    const key = prefix ? `${prefix}${sep}${k}` : k;
    if (v && typeof v === 'object' && !Array.isArray(v)) {
      flattenObject(v, key, sep, result, depth + 1, maxDepth);
    } else {
      result[key] = v;
    }
  }
  return result;
}

// 3) 把拍平后的数据转 Markdown 表格
function generateMarkdownTable(rows, opts = {}) {
  const { align = 'left', includeIndex = false, sortColumns = false } = opts;
  const flat = rows.map(r => flattenObject(r));
  let cols = [...new Set(flat.flatMap(r => Object.keys(r)))];
  if (sortColumns) cols.sort((a, b) => a.localeCompare(b));

  const alignMap = { left: ':-', center: ':-:', right: '-:' };
  const alignSep = alignMap[align];

  const headers = includeIndex ? ['#', ...cols] : cols;
  const seps = includeIndex ? [alignSep, ...cols.map(() => alignSep)] : cols.map(() => alignSep);

  const escapeCell = v =>
    v == null ? '' :
    typeof v === 'object' ? JSON.stringify(v).slice(0, 60) :
    String(v).replace(/\\|/g, '\\|').replace(/\n/g, '<br>');

  const lines = [];
  lines.push('| ' + headers.join(' | ') + ' |');
  lines.push('| ' + seps.join(' | ') + ' |');
  flat.forEach((r, i) => {
    const idxCell = includeIndex ? [i + 1] : [];
    const cells = cols.map(c => escapeCell(r[c]));
    lines.push('| ' + [...idxCell, ...cells].join(' | ') + ' |');
  });
  return lines.join('\n');
}

// 4) 输出到 README.md
const users = await fetchUsers();
const md = generateMarkdownTable(users, { align: 'left', sortColumns: true });
console.log('## GitHub Users\n\n' + md);
// 复制粘贴到 README.md 即被 GitHub 渲染为表格

后端聚合多源数据后用 Python 生成 Markdown 表格（无前端依赖），适合 CI/CD 自动生成周报。

from flask import Flask, jsonify
import json

app = Flask(__name__)

def flatten(obj, prefix='', sep='.', result=None, depth=0, max_depth=3):
    """递归拍平嵌套对象"""
    if result is None:
        result = {}
    if not isinstance(obj, dict) or depth >= max_depth:
        if prefix:
            result[prefix] = json.dumps(obj) if isinstance(obj, (dict, list)) else obj
        return result
    for k, v in obj.items():
        key = f"{prefix}{sep}{k}" if prefix else k
        if isinstance(v, dict):
            flatten(v, key, sep, result, depth + 1, max_depth)
        else:
            result[key] = v
    return result

def json_to_markdown_table(data, align='left', include_index=False,
                            sort_columns=False, caption=None):
    if isinstance(data, dict):
        data = [data]
    if not data:
        return "<!-- No valid objects found -->"

    flat_rows = [flatten(row) for row in data]
    columns = []
    for row in flat_rows:
        for k in row:
            if k not in columns:
                columns.append(k)
    if sort_columns:
        columns.sort()

    align_sep = {'left': ':-', 'center': ':-:', 'right': '-:'}[align]
    headers = (['#'] if include_index else []) + columns
    seps = ([align_sep] if include_index else []) + [align_sep] * len(columns)

    def escape_cell(v):
        if v is None:
            return ''
        if isinstance(v, (dict, list)):
            s = json.dumps(v)
            return s[:60] + '…' if len(s) > 60 else s
        return str(v).replace('|', '\\|').replace('\n', '<br>')

    lines = []
    if caption:
        lines.append(f'### {caption}\n')
    lines.append('| ' + ' | '.join(headers) + ' |')
    lines.append('| ' + ' | '.join(seps) + ' |')
    for i, row in enumerate(flat_rows):
        idx_cell = [str(i + 1)] if include_index else []
        cells = [escape_cell(row.get(c, '')) for c in columns]
        lines.append('| ' + ' | '.join(idx_cell + cells) + ' |')

    return '\n'.join(lines)


@app.route('/api/stats.md')
def stats_markdown():
    """把内部 API 数据生成 Markdown 表格"""
    data = json.load(open('weekly_stats.json'))
    md = json_to_markdown_table(data['users'], align='left', sort_columns=True, caption='周活跃用户')
    return md, 200, {'Content-Type': 'text/markdown; charset=utf-8'}


if __name__ == '__main__':
    app.run(debug=True)

运维场景：从 GitHub API 拉取 PR 列表，用 jq 聚合并拍平为点号键名，再粘贴到本工具生成 GFM Release Notes。

# 1) 用 gh CLI 拉取最近 50 个 merged PR
PR_JSON=$(gh pr list --state merged --limit 50 --json number,title,author,labels,mergedAt)

# 2) 用 jq 拍平 labels 嵌套数组（与本工具拍平逻辑等价）
echo "$PR_JSON" | jq 'map({
  number: .number,
  title: .title,
  author: .author.login,
  labels: (.labels | map(.name) | join(", ")),
  mergedAt: .mergedAt
})' > release_prs.json

# 3) 打开本工具 (https://geekformat.com/json/to-markdown/)
#    - 粘贴 release_prs.json 内容
#    - 工具栏 Strategy 选 "Single"
#    - 勾选 Sort columns + Include Index
#    - 点击 Convert
#    - 复制生成的 Markdown 表格

# 4) 拼接到 Release Notes
cat > RELEASE.md <<'EOF'
# v2.1.0 Release Notes

## 🆕 What's Changed

EOF

# 把上一步复制的表格粘贴到这里（或用 sed 注入）
sed -i '/## 🆕/r /tmp/table.md' RELEASE.md

cat >> RELEASE.md <<'EOF'

**Full Changelog**: https://github.com/your/repo/compare/v2.0.0...v2.1.0
EOF

# 5) 用 gh CLI 创建 Release
gh release create v2.1.0 -F RELEASE.md -t "v2.1.0"