快速开始
本指南通过实际案例，展示如何在内容中高效使用各类短代码（Shortcode）。
内容增强示例
Callout 示例
信息提示（技巧）：
{{< callout note "💡 实用技巧" >}}
使用 `kubectl get pods -w` 可实时监控 Pod 状态变化，部署和故障排查时非常有用。
{{< /callout >}}
重要信息警告：
{{< callout warning "⚠️ 重大变更" >}}
自 2.0 版本起，API 端点已从 `/api/v1/` 变更为 `/api/v2/`，请及时更新应用。
**迁移截止日期：** 2025 年 3 月 1 日
{{< /callout >}}
成功提示（配置完成）：
{{< callout tip "✅ 配置完成" >}}
您的 Kubernetes 集群已正确配置，包含：
- 已启用 RBAC
- 网络策略已激活
- 监控系统已部署
- 备份系统已配置
{{< /callout >}}
Detail（折叠面板）示例
技术配置详情：
{{< details title="高级 Kubernetes 配置" >}}
生产环境建议增加如下配置：
```yaml
apiVersion: v1
kind: ConfigMap
metadata:
name: advanced-config
data:
max_connections: "1000"
timeout: "30s"
retry_attempts: "3"
log_level: "info"
```
**安全建议：**
- 启用 Pod 安全标准
- 配置网络策略
- 使用最小权限的服务账号
- 启用审计日志
{{< /details >}}
常见问题 FAQ：
{{< details title="如何排查连接问题？" >}}
请按以下步骤诊断连接故障：
1. **检查网络连通性：**
```bash
ping 目标主机
telnet 目标主机 端口
```
2. **验证 DNS 解析：**
```bash
nslookup 目标主机
dig 目标主机
```
3. **检查防火墙规则：**
```bash
iptables -L
ufw status
```
4. **查看应用日志：**
```bash
kubectl logs deployment/app-name
journalctl -u service-name
```
{{< /details >}}
媒体示例
Figure 示例
架构图：
{{< figure src="/images/microservices-architecture.webp"
title="微服务架构总览"
caption="该图展示了完整的微服务架构，包括 API 网关、服务网格和数据层组件。"
width="1200"
height="800" >}}
带注释的截图：
{{< figure src="/images/dashboard-screenshot.png"
title="监控仪表盘"
caption="主监控仪表盘展示 CPU、内存和网络指标。注意 14:00 部署事件对应的流量峰值。"
link="/images/dashboard-screenshot-full.png"
target="_blank" >}}
代码流程图：
{{< figure src="/images/authentication-flow.svg"
title="OAuth 2.0 认证流程"
caption="OAuth 2.0 授权码流程的客户端、授权服务器和资源服务器交互步骤。"
width="800" >}}
Bilibili 视频示例
教程视频：
{{< bilibili bv="BV1GJ411x7h7" caption="Kubernetes 入门教程：从零开始部署你的第一个应用" >}}
本视频内容包括：
- Kubernetes 基本概念
- 如何创建 Deployment
- 如何暴露服务
- 故障排查技巧
大会演讲：
{{< bilibili bv="BV1634y1w7Nu"
caption="KubeCon 2024: Service Mesh 最佳实践分享" >}}
分享内容涵盖：
- Service Mesh 架构演进
- Istio 与 Linkerd 对比
- 生产环境部署经验
- 性能优化技巧
Podcast 示例
播客嵌入：
{{< podcast episode="1000123456789" height="200" >}}
本期播客讨论：
- 云原生技术发展趋势
- 容器化最佳实践
- DevOps 文化建设
- 开源项目参与经验
**嘉宾介绍：** 张三，知名互联网公司架构师，拥有 10 年云计算经验。
交互式示例
Markmap 思维导图示例
项目规划思维导图：
首先创建 project-planning.md：
---
markmap:
initialExpandLevel: 2
colorFreezeLevel: 3
---
# 软件项目规划
## 需求分析
### 功能需求
- 用户认证
- 数据管理
- 报表系统
- API 集成
### 非功能需求
- 性能（响应时间 < 2 秒）
- 安全（OAuth 2.0）
- 可扩展性（支持 1000+ 并发用户）
- 可用性（99.9% 在线率）
## 技术架构
### 前端
- React.js
- TypeScript
- Material-UI
- 状态管理（Redux）
### 后端
- Node.js
- Express.js
- PostgreSQL
- Redis 缓存
### 基础设施
- Docker 容器
- Kubernetes 编排
- AWS 云平台
- CI/CD 流水线
## 开发流程
### 阶段一：基础
- 项目初始化
- 数据库设计
- 认证系统
- 基础 UI 框架
### 阶段二：核心功能
- 用户管理
- 数据 CRUD 操作
- 业务逻辑
- API 开发
### 阶段三：高级功能
- 报表仪表盘
- 实时通知
- 第三方集成
- 性能优化
## 质量保障
### 测试策略
- 单元测试（Jest）
- 集成测试
- 端到端测试（Cypress）
- 性能测试
### 代码质量
- ESLint 配置
- Prettier 格式化
- 代码评审
- 文档编写
然后嵌入：
{{< markmap file="project-planning.md" title="软件项目规划" height="700px" >}}
该思维导图展示了从需求收集到部署的完整项目规划流程。
学习路径思维导图：
创建 kubernetes-learning.md：
# Kubernetes 学习路径
## 基础知识
### 容器基础
- Docker 概念
- 镜像制作
- 容器生命周期
- 网络基础
### Kubernetes 核心
- Pod 与容器
- 服务与网络
- Deployment 与 ReplicaSet
- ConfigMap 与 Secret
## 进阶内容
### 工作负载管理
- DaemonSet
- StatefulSet
- Job 与 CronJob
- 水平 Pod 自动扩缩
### 存储与持久化
- 卷与持久卷
- 存储类
- StatefulSet 存储
- 备份策略
## 高级主题
### 安全
- RBAC（角色权限控制）
- Pod 安全标准
- 网络策略
- Service Mesh（Istio）
### 运维
- 监控（Prometheus）
- 日志（ELK Stack）
- 故障排查
- 集群维护
## 认证路径
### CKA（Kubernetes 管理员认证）
- 集群架构
- 工作负载与调度
- 服务与网络
- 存储与故障排查
### CKAD（Kubernetes 应用开发认证）
- 应用设计
- 应用部署
- 应用可观测性
- 应用环境
{{< markmap file="kubernetes-learning.md" title="Kubernetes 学习路线图" >}}
内容组织示例
List Children 示例
文档导航：
{{< list_children title="📚 文档章节" style="cards" show_summary="true" >}}
系列博客文章：
{{< list_children title="🔗 本系列相关文章"
style="list"
show_date="true"
show_weight="true"
limit="5" >}}
教程步骤：
{{< list_children title="📋 教程步骤"
style="cards"
show_summary="false"
show_weight="true" >}}
Table 示例
对比表：
{{< table title="Kubernetes 发行版对比" >}}
| 发行版 | 云服务商 | 托管 | 费用 | 适用场景 |
|--------|----------|------|------|----------|
| EKS | AWS | 是 | $$$ | AWS 原生应用 |
| GKE | Google Cloud | 是 | $$$ | Google 生态 |
| AKS | Azure | 是 | $$$ | 微软技术栈 |
| k3s | 任意 | 否 | $ | 边缘计算 |
| OpenShift | 任意 | 混合 | $$$$ | 企业级 |
{{< /table >}}
配置参考表：
{{< table title="环境变量配置参考" >}}
| 变量 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `DATABASE_URL` | string | - | PostgreSQL 连接字符串 |
| `REDIS_URL` | string | `redis://localhost:6379` | Redis 缓存地址 |
| `LOG_LEVEL` | string | `info` | 日志级别（debug, info, warn, error） |
| `PORT` | number | `3000` | 应用端口 |
| `NODE_ENV` | string | `development` | 环境模式 |
{{< /table >}}
代码示例
Include Code 示例
配置文件：
{{< include_code file="docker-compose.yml" >}}
该 Docker Compose 配置包含：
- 应用服务器
- PostgreSQL 数据库
- Redis 缓存
- Nginx 反向代理
部署脚本：
{{< include_code file="scripts/deploy.sh" >}}
该部署脚本自动完成：
1. 构建 Docker 镜像
2. 推送到镜像仓库
3. 更新 Kubernetes 部署
4. 验证部署状态
API 客户端示例：
{{< include_code file="examples/api-client.js" >}}
示例演示：
- 认证处理
- 错误管理
- 重试逻辑
- 响应解析
实用工具示例
CTA（行动号召）示例
文档导航：
{{< cta cta_text="📖 阅读完整文档"
cta_link="/docs/getting-started"
cta_alt_text="🎥 查看视频教程"
cta_alt_link="/tutorials/video-series" >}}
下载与演示：
{{< cta cta_text="⬇️ 下载最新版本"
cta_link="https://github.com/user/repo/releases/latest"
cta_new_tab="true"
cta_alt_text="🚀 在线体验"
cta_alt_link="https://demo.example.com"
cta_alt_new_tab="true" >}}
学习路径：
{{< cta cta_text="🎯 开始学习路径"
cta_link="/learning/kubernetes-basics"
cta_alt_text="📋 查看前置知识"
cta_alt_link="/learning/prerequisites" >}}
Gallery 示例
架构截图：
{{< gallery link="/images/frontend-ui.png" title="前端用户界面" >}}
{{< gallery link="/images/admin-dashboard.png" title="管理后台" >}}
{{< gallery link="/images/mobile-app.png" title="移动应用" >}}
{{< gallery link="/images/api-docs.png" title="API 文档" >}}
前后对比：
## 性能优化结果
**优化前：**
{{< gallery link="/images/performance-before.png" title="优化前性能指标 - 3.2 秒加载" >}}
**优化后：**
{{< gallery link="/images/performance-after.png" title="优化后性能指标 - 0.8 秒加载" >}}
Slide 示例
大会演讲：
{{< slide src="https://slides.com/username/kubernetes-best-practices" >}}
内容涵盖：
- 容器编排基础
- 生产部署策略
- 监控与可观测性
- 安全最佳实践
- 成本优化技巧
培训材料：
{{< slide src="/slides/docker-fundamentals.html" >}}
**培训目标：**
- 理解容器化概念
- 掌握 Docker CLI 命令
- 实践镜像构建
- 探索网络与存储
复杂示例
多短代码教程示例
# 完整 Kubernetes 部署教程
{{< callout note "前置条件" >}}
开始本教程前，请确保：
- 已安装并运行 Docker
- 已配置 kubectl
- 有 Kubernetes 集群访问权限
{{< /callout >}}
## 架构总览
{{< figure src="/images/tutorial-architecture.png"
title="教程应用架构"
caption="将部署一个三层应用，包括前端、API 和数据库组件。" >}}
## 步骤一：准备配置文件
{{< include_code file="k8s/namespace.yaml" >}}
{{< include_code file="k8s/deployment.yaml" >}}
{{< details title="部署配置详解" >}}
本部署配置包含：
- **副本数**：3 实例，高可用
- **资源限制**：CPU 和内存约束
- **健康检查**：存活与就绪探针
- **环境变量**：配置注入
{{< /details >}}
## 步骤二：部署到 Kubernetes
```bash
kubectl apply -f k8s/
```
{{< callout tip "部署验证" >}}
使用 `kubectl get pods -w` 实时查看部署进度。
{{< /callout >}}
## 步骤三：验证部署
{{< table title="验证命令" >}}
| 命令 | 作用 | 预期输出 |
|------|------|----------|
| `kubectl get pods` | 查看 Pod 状态 | 所有 Pod 运行中 |
| `kubectl get svc` | 验证服务 | 服务端点可用 |
| `kubectl logs deployment/app` | 查看应用日志 | 无错误信息 |
{{< /table >}}
## 故障排查
{{< details title="常见问题与解决方案" >}}
**Pod 卡在 Pending 状态：**
- 检查资源：`kubectl describe nodes`
- 验证镜像拉取：`kubectl describe pod <pod-name>`
{{< /details >}}
**服务不可访问：**
- 检查服务配置：`kubectl get svc -o yaml`
- 验证网络策略：`kubectl get networkpolicy`
**应用报错：**
- 查看日志：`kubectl logs deployment/app-name`
- 检查配置：`kubectl get configmap`
{{< /details >}}
## 后续步骤
{{< cta cta_text="🚀 部署到生产环境"
cta_link="/tutorials/production-deployment"
cta_alt_text="📊 监控你的应用"
cta_alt_link="/tutorials/monitoring-setup" >}}
## 相关资源
{{< list_children title="相关教程" style="cards" limit="3" >}}
该综合示例展示了多种短代码协同使用，帮助用户完成复杂操作流程，并提供丰富的上下文和资源。
短代码最佳实践
内容流程
- 先给出背景 - 用 callout 设置预期
- 配合视觉元素 - 用 figure 展示复杂概念
- 分解复杂内容 - 用 detail 展示可选信息
- 引导下一步 - 用 CTA 明确后续操作
可访问性
- 图片务必加 alt 文本
- 折叠内容用描述性标题
- 媒体内容加说明
- 测试交互元素键盘导航
性能优化
- 图片先优化再用 figure
- 视频嵌入选合适平台
- 思维导图内容不宜过多
- 布局兼顾移动端体验