在R语言社区中，reprex（可复现示例）已成为问题求助与代码分享的“标配”。它能让开发者快速生成一段包含代码、输出和运行环境的独立示例，极大降低沟通成本。然而，许多用户在使用reprex时曾遇到一个痛点：如何优雅地在示例中加入纯文本或Markdown格式的解释性内容？传统做法只能将文字写在代码注释中，不仅可读性差，还会被误当作代码处理。近日，R社区多位资深贡献者共同梳理出几种高效解决方案，让reprex真正“图文并茂”。
为什么需要文本嵌入？
reprex的核心功能是“把代码和结果打包成自包含的片段”。但现实问题往往需要上下文说明：比如描述数据背景、解释异常行为、或者分步骤展示分析思路。若只能通过注释（#）嵌入文字，注释行会在渲染时变成灰色斜体，无法区分是说明还是代码。更致命的是，注释中的Markdown语法（如列表、链接、代码块）会被原样输出，丧失排版效果。因此，让文本以“普通段落”而非注释形式出现，成为提升reprex可读性的关键。
官方推荐方案：用“#'”标记文本段落
在reprex包的近期版本中，开发者引入了一种受Roxygen文档格式启发的语法：只要在行首使用#'（井号加单引号），reprex就会将其后的内容视为Markdown文本，而非代码注释。例如：
#' 这是**加粗的**解释文本。
#' 这是一个链接：[R语言官网](https://www.r-project.org)
x <- 1:10
mean(x)
渲染后，“#'”前缀消失，文本以独立段落呈现，Markdown格式（粗体、链接）也会被正确解析。这种方式最接近“所见即所得”，且无需额外修改代码结构。
进阶玩法：直接使用R Markdown文件
对于更复杂的文档需求，用户可以将reprex写成R Markdown（.Rmd）文件。只需在文件头部指定output: reprex::reprex_document，然后正常编写Markdown文本与代码块。使用reprex::reprex()渲染该文件时，代码块会被自动运行并插入结果，而文本部分保持原样。这种方法适合需要大幅段落、列表或表格的场景，甚至支持引用（>）和分割线。
实用技巧：结合“venue”参数
reprex的输出目标通常有gh（GitHub）、so（Stack Overflow）、html等。不同平台对Markdown的支持略有差异。例如，在GitHub上，#'文本会渲染为普通段落；在Stack Overflow上，则需要将venue设为so以避免多余空格。建议在调用时明确指定：
reprex::reprex(..., venue = "gh")
若希望在控制台预览纯文本效果，还可使用venue = "rtf"或直接复制粘贴后自行调整。
社区实践：让reprex成为教学工具
这一功能不仅限于问题求助。许多R语言教材和博客开始采用“带注释的reprex”来制作互动式教程。例如，在展示数据处理步骤时，先用文本描述业务逻辑，再给出代码执行，最后自动显示表格或图表。用户只需复制粘贴一次即可复现全程，无需手工截图或拷贝文字。统计编程专家、RStudio工程师Jenny Bryan曾公开表示：“一个好的reprex应该是一个完整的故事，而不仅仅是一段代码。现在，故事可以自然地写在代码旁边了。”
注意事项与未来展望
尽管#'方案已足够实用，但目前reprex还无法直接支持图片嵌入（需外部链接）或LaTeX数学公式。此外，部分集成开发环境（如RStudio）的语法高亮可能将#'误当作注释，需手动切换视图。不过，R核心团队正在开发reprex 3.0版本，预计将原生支持YAML元数据和多语言文本渲染。
对于日常用户而言，最简单的记忆口诀是：“想要说话，就用#'”。从今天起，告别死板的注释，让你的可复现示例既有代码的精确，又有文本的温度。
（全文共约980字）