大模型系列——Markdown扩展功能详解#

动态仓库展示#

GitHub 仓库卡片是一个强大的功能，它会在页面加载时自动从 GitHub API 拉取仓库信息，包括星标数、fork 数、描述等实时数据。

技巧提示 (tip)#

提供可选的辅助信息，帮助读者更加成功或高效地完成任务：

TIP

这是技巧提示框。用于提供可选的辅助信息，帮助读者更加成功或高效地完成任务。通常包含一些实用的建议或最佳实践。

重要信息 (important)#

标记关键信息，这些信息对于读者理解内容或完成任务至关重要：

IMPORTANT

这是重要信息框。用于标记关键信息，这些信息对于读者理解内容或完成任务至关重要。请确保读者不会忽略这些内容。

警告信息 (warning)#

标记需要立即关注的关键内容，因为可能存在潜在风险：

WARNING

这是警告信息框。用于标记需要立即关注的关键内容，因为可能存在潜在风险。读者在继续操作前应该特别注意这些信息。

谨慎提示 (caution)#

提醒读者注意某个操作的潜在负面后果：

CAUTION

这是谨慎提示框。用于提醒读者注意某个操作的潜在负面后果。在执行某些可能有风险的操作前，请仔细阅读这些提示。

基础语法#

使用三冒号语法定义提示框类型：

1
::::note
2
这是普通的提示框。
3
::::
4

5
::::tip
6
这是技巧提示框。
7
::::
8

9
::::important
10
这是重要信息框。
11
::::
12

13
::::warning
14
这是警告信息框。
15
::::
16

17
::::caution
18
这是谨慎提示框。
19
::::

自定义标题#

你可以为提示框添加自定义标题，让信息更加明确：

自定义标题

这是一个带有自定义标题的提示框。自定义标题可以让提示信息更加具体和明确。

1
::::note[自定义标题]
2
这是一个带有自定义标题的提示框。
3
::::

GitHub 风格语法#

除了三冒号语法，还支持 GitHub 风格的引用提示语法：

NOTE

GitHub 风格的普通提示框语法。

TIP

GitHub 风格的技巧提示框语法。

WARNING

GitHub 风格的重要信息框语法。

WARNING

GitHub 风格的警告信息框语法。

1
> [!NOTE]
2
> GitHub 风格的普通提示框语法。
3

4
> [!TIP]
5
> GitHub 风格的技巧提示框语法。
6

7
> [!IMPORTANT]
8
> GitHub 风格的重要信息框语法。
9

10
> [!WARNING]
11
> GitHub 风格的警告信息框语法。
12

13
> [!CAUTION]
14
> GitHub 风格的谨慎提示框语法。

基础用法#

折叠内容功能允许你隐藏特定文本，读者需要点击才能查看。这对于避免剧透或隐藏次要信息非常有用。

默认情况下，折叠内容使用 “点击显示” 作为标签。

The content is hidden ayyy!

1
The content :spoiler[is hidden **ayyy**]!

自定义标签#

你可以为折叠内容设置自定义标签：

隐藏内容 这里是被折叠的内容，点击查看!

1
隐藏内容 :spoiler[这里是被折叠的内容，点击查看]!

应用场景#

1. 避免剧透: 在影评或游戏评测中隐藏关键情节
2. 隐藏细节: 将技术细节折叠，保持主要内容的简洁
3. 答案保护: 在练习题中隐藏答案
4. 隐私信息: 隐藏敏感的个人或商业信息

高级技巧#

折叠内容支持完整的 Markdown 语法，包括加粗、斜体、链接等：

The secret The answer is 42 according to the Hitchhiker’s Guide to the Galaxy!

1
The secret :spoiler[The answer is **42** according to the Hitchhiker's Guide to the Galaxy!]

提示框与代码结合#

在提示框中嵌入代码块，提供更完整的说明：

最佳实践

使用 RAG 时，建议按照以下顺序优化系统：

1. 提示词工程
2. 检索增强生成 (RAG)
3. 模型微调

1
# 示例代码
2
def rag_pipeline(query, knowledge_base):
3
    # 检索相关文档
4
    context = retrieve(query, knowledge_base)
5
    # 增强生成
6
    response = generate(query, context)
7
    return response

多提示框组合#

在复杂的技术文档中，可以组合使用不同类型的提示框来引导读者：

前置知识

在阅读本文之前，你应该具备以下基础：

• 了解 Python 基本语法
• 熟悉机器学习基本概念
• 有一定的编程经验

学习建议

建议按照以下顺序学习：

1. 先理解核心概念
2. 再动手实践示例代码
3. 最后深入分析源码

注意事项

实践过程中请注意：

• 确保环境配置正确
• 注意版本兼容性问题
• 及时备份重要数据

关键要点

掌握这些扩展功能将帮助你：

• 提升博客的可读性
• 增强用户体验
• 让技术文档更加专业

颜色运用#

• 蓝色系 (note): 传递信息、提供补充说明
• 绿色系 (tip): 积极正向、鼓励探索
• 紫色系 (important): 重要但不紧急、强调价值
• 黄色系 (warning): 警示注意、需要立即关注
• 红色系 (caution): 风险提示、需要谨慎处理

使用频率建议#

在技术文档中，建议遵循以下使用频率原则：

1. note - 可频繁使用，但要有实际价值
2. tip - 适量使用，确保内容质量
3. important - 按需使用，避免泛滥
4. warning - 谨慎使用，只在真正需要时
5. caution - 最少使用，仅用于高风险场景

创建交互式教程#

结合多种扩展功能，创建交互式的学习体验：

教程目标

本教程将教你如何搭建一个完整的 AI 应用。

环境准备

确保你已经安装了以下工具：

• Python 3.8+
• pip 包管理器
• Git 版本控制

费用注意

本教程会消耗 API 配额，建议：

• 先在测试环境验证
• 设置预算提醒
• 监控使用情况

学习成果

完成本教程后，你将能够：

• 集成 OpenAI API
• 构建基础对话系统
• 理解最佳实践

技术文档最佳实践#

在撰写技术文档时，合理使用扩展功能：

1
:::note[章节概述]
2
本章介绍系统的核心架构和设计理念。
3
:::
4

5
主要内容：
6

7
:::tip[学习重点]
8
重点关注数据流和模块交互方式。
9
:::
10

11
1. 系统架构设计
12
2. 核心模块说明
13
3. 数据流转过程
14

15
:::warning[常见问题]
16
部署时请注意端口占用和权限配置。
17
:::
18

19
:::important[关键要点]
20
掌握这些内容是系统维护的基础。
21
:::
22

23
高级内容（展开查看）：
24

25
:::spoiler[深度阅读]
26
了解底层实现细节和优化策略。
27
:::

内容组织#

1. 合理使用提示框: 不要过度使用，每个提示框都应该有其存在的价值
2. 保持一致性: 在整个文档中使用一致的提示框风格
3. 注重层次: 使用不同类型的提示框创建信息层次
4. 视觉平衡: 避免在短距离内使用过多的提示框

读者体验#

1. 快速扫描: 确保读者通过提示框就能抓住重点
2. 深度阅读: 为想要深入了解的读者提供详细信息
3. 交互友好: 使用折叠内容保护敏感信息，避免剧透
4. 视觉舒适: 注意色彩搭配和空间布局

通过合理运用这些 Markdown 扩展功能，你可以创建既美观又实用的技术文档，为读者提供更好的阅读体验。

📚 相关文章:

• 代码高亮与样式指南
• 智能 Agent 简介

🎯 下期预告: 我们将介绍如何使用这些扩展功能来创建交互式教程和案例研究。