parsedown v1.8+要求PHP≥7.4，低版本需降级至^1.7.4；中文乱码因UTF-8未统一，须设mb_internal_encoding并urlencode中文链接；模板中HTML需禁用转义如{!! $html !!}；CommonMark v3废弃MarkdownConverter静态方法，改用Environment实例化；部署需确保全链路UTF-8编码一致。

安装 parsedown 时 PHP 版本不匹配导致失败

parsedown v1.8+ 要求 PHP ≥ 7.4，低于该版本会直接报 Your requirements could not be resolved。这不是包名写错，而是 Composer 主动拒绝安装。

• 先运行 php -v 确认当前版本；若为 PHP 7.2 或更低，改用 composer require erusev/parsedown:^1.7.4
• 检查 composer.json 中的 "platform" 配置项，它可能偷偷降级依赖却无提示
• 换镜像源或升级 Composer 后，务必执行 composer clear-cache，否则旧缓存可能卡住解析逻辑

中文标题乱码或链接失效的根本原因

parsedown 不做 UTF-8 编码校验，也不自动处理 URL 中文字符。输入内容若来自 GBK 编码旧系统、或未设 mb_internal_encoding('UTF-8')，就会静默丢字节——不报错，只输出乱码或截断链接。

知识产权官文PDF转markdown

Convert Chinese patent PDFs/DOCX/DOCs to structured Markdown. Supports patent publications (A/B/U) and office action documents (审查意见通知书/驳回决定/复审决定书/无效宣告请求审查决定书). Uses MinerU for high-quality OCR text extraction (falls back to Tesseract), Python scripts for

下载

• 入口文件（如 index.php）开头必须加 mb_internal_encoding('UTF-8')
• 用户提交的中文路径链接，如 [文章](/文章/你好.md)，需提前用 rawurlencode() 处理，否则会被解析器当成非法 URI 丢弃
• trim() 或 str_replace("\r\n", "\n", $input) 可能破坏段落分隔空行，应仅对首尾调用 trim($_POST['content'])

渲染后 HTML 被模板引擎二次转义

在 Laravel 或 Twig 中直接 {{ $html }} 输出解析结果，浏览器看到的是 <p>Hello</p> 而非真实标签——这不是解析器问题，是模板层把已生成的 HTML 当纯文本处理了。

• Laravel 中正确做法：返回 Illuminate\Support\HtmlString 实例，例如 return new HtmlString($parsedown->text($md))
• Blade 里禁用双大括号自动转义：{!! $html !!}，但前提是内容已由 setSafeMode(true) 或 setMarkupEscaped(true) 过滤过原始 HTML
• 别在循环中反复 new Parsedown()，实例化开销小但非零；可复用单例或注入容器管理

CommonMark v3 升级后 Class not found 或 getContent() 报错

v3 彻底废弃 MarkdownConverter 类和静态工厂方法，老代码 new MarkdownConverter() 会直接崩，且 convert() 返回 Document 对象而非字符串。

• v2 写法：$converter = new MarkdownConverter(); $html = $converter->convertToHtml($md);
• v3 正确写法：$environment = Environment::createCommonMarkEnvironment(); $converter = new MarkdownConverter($environment); $html = $converter->convert($md)->getContent();
• Laravel 项目注意：v3 不再提供 Environment::createCommonMarkEnvironment() 静态快捷方法，必须手动 new Environment()
• 中文锚点支持需显式注册 HeadingPermalinkExtension，基础环境不带；表格支持要额外加 TableExtension

实际部署时最容易被忽略的是编码链路的完整性：从 HTTP 请求头、PHP 内部编码、数据库连接 charset，到 HTML 响应头的 Content-Type: text/html; charset=utf-8，任一环节断裂都会让中文渲染失真——而 parsedown 或 commonmark 本身不会提醒你。