Google Codelabs 教程编写规范指南

Google Codelabs 教程编写规范指南

tools Codelabs management & hosting tools 项目地址: https://gitcode.com/gh_mirrors/tool/tools

作为技术教程创作者，编写高质量的交互式教程（Codelab）需要遵循一定的格式规范。本文将详细介绍 Google Codelabs 项目的教程编写规范，帮助开发者创建结构清晰、体验良好的技术教程。

教程编写基础

在开始编写教程前，建议使用官方提供的模板文档作为起点。这个模板已经预设了正确的格式和结构，可以大大提升编写效率。

预览功能

编写过程中，可以通过以下方式预览教程效果：

1. 安装专用浏览器扩展程序（可选一次性设置）
2. 在文档编辑界面点击扩展程序按钮
3. 或者直接访问特定预览URL

预览功能让创作者能够实时查看最终呈现效果，确保格式正确无误。

核心格式规范

1. 目录结构

教程必须使用一级标题（Heading 1）来划分各个步骤。系统会自动根据这些标题生成目录导航，方便学习者了解进度和跳转到特定步骤。

在小屏幕设备上，目录会折叠到菜单中，但仍可通过汉堡菜单访问。

2. 元数据配置

教程需要包含必要的元数据，这些信息应放在第一个步骤之前，以两列表格形式呈现。关键元数据包括：

• 摘要：教程的简短描述，显示在教程浏览界面
• URL后缀：教程发布后的路径后缀
• 分类：教程所属的技术类别
• 状态：草稿、已发布、已弃用或隐藏
• 反馈链接：用户报告问题的URL
• 分析账户：自定义Google Analytics ID

3. 内容层级

在教程步骤内部，应合理使用二级到四级标题（Heading 2-4）来组织内容。这些标题会转换为HTML中的h2-h4标签，保持内容层级清晰。

4. 文本样式

虽然文档编辑器支持多种字体，但最终教程会统一使用Roboto字体。可以通过以下方式强调内容：

• 粗体：转换为<strong>标签
• 斜体：转换为<em>标签
• 等宽字体：转换为<code>标签

5. 多媒体内容

响应式图片

插入的图片会自动适应不同屏幕尺寸。在文档中调整的图片宽度会作为max-width属性应用到最终教程中。

视频嵌入

可以通过以下方式嵌入YouTube视频：

1. 插入任意图片
2. 为图片添加替代文本
3. 在描述字段填入YouTube视频链接

iframe嵌入

iframe嵌入方式与视频类似，但受限于安全策略，只能嵌入特定白名单域名的内容。

6. 信息提示框

为突出重要信息，可以使用两种风格的提示框：

• 绿色背景：用于最佳实践、节省时间的技巧等正面信息
• 橙色背景：用于警告、API使用限制等负面信息

建议保持提示框内容简洁专注，非关键信息可以放在FAQ部分。

7. 代码相关格式

命令行片段

使用单列表格和Consolas字体来展示命令行指令或日志输出。

代码片段

同样使用单列表格，但采用Courier New字体。建议：

1. 在代码上方添加三级标题说明文件名
2. 标题最好包含实际代码文件的链接
3. 系统会根据文件扩展名自动应用语法高亮

8. 常见问题

在每个步骤后添加FAQ部分能显著提升学习体验：

1. 使用三级标题"Frequently Asked Questions"
2. 添加无序列表形式的问题链接
3. 特定域名的链接会自动显示对应图标

9. 下载按钮

通过添加深绿色背景的超链接可以创建下载按钮。如果链接文本以"Download"开头，还会自动添加下载图标。

10. 步骤时间预估

在每个步骤添加时间预估能帮助学习者规划时间：

1. 使用深灰色文本标注"Duration:"
2. 未标注的步骤默认为1分钟
3. 纯祝贺页面可设为0分钟

11. 条件步骤

可以为不同环境创建条件步骤：

1. 使用深灰色文本标注"Environment:"
2. 未标注时默认为"Web, Kiosk"
3. 预览时可通过URL参数切换环境

高级功能

片段导入

支持从其他文档导入内容片段，语法为：

[[**import** [描述文本](文档链接)]]

注意导入的内容只能是步骤片段，不能包含完整步骤。

可恢复教程

系统会自动记录学习进度，当用户通过书签或短链接返回时，会提示是否继续上次的位置。

内联调查

可以在教程中添加简单的多选题：

1. 使用浅蓝色背景的单列表格
2. 问题使用四级标题格式
3. 选项使用无序列表
4. 回答会作为自定义变量发送到Google Analytics

注意要避免收集不必要的信息，保持问题简洁相关。

学习目标清单

使用二级标题"What you'll learn"或"What we've covered"加项目符号列表，会自动生成带勾选框的目标清单。

应避免的做法

• 页脚内容：除页码外的页脚内容可能导致解析问题，不建议使用
• 复杂格式：过度格式化可能无法正确转换
• 过长段落：保持内容简洁易读

遵循这些规范，你将能创建出专业、易用的交互式技术教程，为学习者提供最佳体验。

tools Codelabs management & hosting tools 项目地址: https://gitcode.com/gh_mirrors/tool/tools