文档中心 实验室相关 投稿语法说明

投稿语法说明

最近更新时间:2019-07-23 20:41:34

腾讯云实验室上线了 在线投稿 能力,现在除了官方推出的实验室之外,允许有能力的开发者把自己的技术和经验通过在实验室投稿的方式来进行分享和传播。

如果想要自己的实验可以顺利地通过官方的审核,就需要提供到规范、高质量的实验内容。本文为希望进行投稿的开发者提供一些指引和帮助,仔细阅读这些内容,可以在投稿到实验上线的过程中少走弯路。

1. 概念:实验的组成

1.1 实验任务和实验步骤

一个实验会包含若干个实验任务,每个实验任务会包含若干个实验步骤。实验任务希望可以给到用户阶段性的实验成果,每个实验任务可能需要分解成多个实验步骤进行。每个实验步骤应尽量做到明确和可验证。
举个例子,下图是 搭建 FTP 文件服务 实验的截图。
enter image description here

该实验定义了 4 个实验任务,分别是:

  1. 安装并启动 FTP 服务
  2. 配置 FTP 权限
  3. 准备域名和证书
  4. 访问 FTP 服务

其中可以看到第 1 个实验任务包含了 2 个实验步骤,分别是:

  • 安装 VSFTPD
  • 启动 VSFTPD

1.2 实验内容

当你进入投稿的教程编辑模式时,会获得一个教程编写环境。该环境和实际实验环境非常相似,但是会多出一个名为教程文档的编辑器。教程文档编辑器使用 Markdown 作为基本编辑语法,编辑的内容保存后会实时生成右侧的实验区域。
图片

1.3 实验元素一览

展示类元素 - 基础

实验元素 定义方式
实验名称 Markdown 一级标题
实验任务 Markdown 二级标题
时间声明 <time> 指令
实验步骤 Markdown 三级标题
强调内容 Markdown 强调内容
列表 Markdown 列表
代码 Markdown 内联代码或 Markdown 代码块
链接 Markdown 链接或 <link> 指令
图片 Markdown 图片
表格 Markdown 表格
公式 Markdown XML 代码块 + <formula> 指令
视频 <video> 指令
网页 <webpage 指令

交互类元素 - 进阶

实验元素 定义方式 交互说明
解释气泡 <bubble> 指令 将并非完成实验必须的内容折叠展示
环境变量 ${runtime.vars.<VAR_NAME>} 插入跟环境相关的实验变量
检查器 <checker> 指令 检查步骤是否正确完成,给到还未完成的提示
路径定位 <locate> 指令 在文件树上定位某个目录或文件,并给到操作提醒
文件编辑 <edit> 指令 在工作区打开一个现有的文件进行编辑
示例代码 <example> 指令 期望用户创建或编辑某个文件,并给到范例进行对比

接下来,会为大家介绍这些元素的详细使用方法。

2. 基础:实验的书写

2.1 插入实验名称

使用 Markdown 一级标题来插入实验名称的声明。

语法

# 实验名称

效果

图片

注意事项:

  • # 后面必须有空格,否则无法识别
  • 每个实验只能定义一个实验名称,多定义的会被忽略
  • 请规范化实验名称书写格式,中文和英文之间添加空格

2.2 插入实验任务

使用 Markdown 二级标题来插入实验任务的声明。

语法

## 实验任务

效果

图片

** 注意事项:**

  • ## 后面必须有空格,否则无法识别
  • 请规范化实验任务书写格式,中文和英文之间添加空格

2.3 插入实验步骤

使用 Markdown 三级标题插入实验步骤的声明。

语法

### 实验步骤

效果

图片

注意事项:

  • ### 后面必须有空格,否则无法识别
  • 实验步骤必须在某个实验任务下插入,否则无法识别
  • 请规范化实验步骤书写格式,中文和英文之间添加空格

2.4 插入实验正文

在实验任务定义下面的正文,会作为任务概要显示;在实验步骤定义下面的正文,会作为步骤的内容。对于正文的书写,要求做到工整、简洁、规范。具体的标准请参考本文后面的投稿规范说明。

图片

注意事项:

  • 请规范化实验正文书写格式,中文和英文之间添加空格

2.5 插入时间声明

对于一个实验任务,可以声明完成该任务所需要的预估时间,让用户对实验长度和进度有一个心理预期。

语法

> <time>5min~10min</time>

效果

图片

** 注意事项:**

  • 行首的 > 前面不能有其它字符,后面必须有一个空格,否则无法正确识别
  • 可以使用工具栏的时间工具快速插入时间声明
  • 只允许在实验任务定义后面插入时间声明

2.6 插入列表

在展示一些具有强并列关系的内容的时候,尽量使用列表来使得表达更清晰。云实验室的列表语法和 Markdown 一致。

语法

编号列表:
1. 第一项
2. 第二项

无序列表:
* 第一项
* 第二项

示例效果

图片

注意事项:

  • * 后面必须有空格,否则无法识别

2.7 插入代码

在正文内容里面需要突出显示的关键字、变量或者短代码,可以使用内联代码;而对于希望用户输入到终端的命令,或者希望用户复制的内容,可以用代码块。

示例

图片

说明

  • 使用 &grave; 包裹内联代码的内容
  • 在行首使用 &grave;&grave;&grave; 开始代码块的内容,后面可跟代码块所使用的语言。再次使用在行首使用 &grave;&grave;&grave; 结束代码块

2.8 插入超链接

实验当中需要提供外部链接时使用。

语法

下面几种方式都可以在实验室插入超链接:

1. 如有疑问,可到[腾讯云问答社区](https://cloud.tencent.com/developer/ask)提问
2. 如有疑问,可到[腾讯云问答社区][https://cloud.tencent.com/developer/ask]提问
3. 如有疑问,可到 [https://cloud.tencent.com/developer/ask][] 提问
4. 如有疑问,可到 <https://cloud.tencent.com/developer/ask> 提问
5. 如有疑问,可到[腾讯云问答社区][community]提问

> <link for="community" href="https://cloud.tencent.com/developer/ask" />

示例效果

图片

注意事项:

  • 超链接必须http://https://ftp:// 开头,并统一在新窗口打开
  • 示例中的第 5 种声明方式非 Markdown 标准,属实验室拓展语法,方便声明重复使用的超链接地址

2.9 插入图片

必要时,可以插入图片辅助实验内容。

语法

![图片说明](https://url.totheimage.com)

示例效果

图片

注意事项:

  • 不允许引用非 HTTPS 的图片,否则投稿将被拒绝
  • 不允许引用具有防盗链特性的外站图片,否则投稿将被拒绝
  • 可以通过工具栏中的插入图片按钮上传本地图片,非 HTTPS 或外站图片可以保存到本地后上传
  • 教程编辑器支持使用 Ctrl + V(Windows)或 Cmd + V(Mac) 粘贴剪贴板中的图片内容(如 QQ 截图)

2.10 插入表格

使用 Markdown 表格语法可在实验正文中插入表格。

语法

表头 1 | 表头 2 | 表头 3
------|--------|------
内容 1 | 内容 2 | 内容 3

效果

图片

注意事项:
实验室右侧的篇幅有限,不宜插入过大的表格。如有这种情况,请考虑使用更合适的表达方案。

2.11 插入公式

对于部分需要介绍数学背景的实验,可以插入 AMS LaTeX 语法 的公式。

示例

图片

说明

  • 使用类型为 XML 的代码块插入公式
  • 公式内容使用 <formula> 标签包裹
  • 需要使用 \\ 来表示 \

2.12 插入视频

必要时,可以插入视频内容来辅助实验。目前实验室只支持插入腾讯视频的内容。需要在实验室插入视频的,需要先在腾讯视频注册并且上传视频,审核成功后方可插入。

示例用法

如果你对实验内容有疑问,可参考[视频教程][video-1]

> <video for="video-1" platform="qq" vid="p01578c394j" name="视频 - 腾讯云"></video>

示例效果

用户点击视频教程的链接后,会在工作区打开视频播放窗口。

图片

注意事项:

  • 只能插入腾讯视频的内容
  • vid 在视频上传并通过审核后,从视频的 URL 中获取

图片

2.13 插入网页

如果觉得有必要,可以添加一个能在工作区打开的网页。

示例用法

我们可以参考[小程序的开发文档][mp-doc]来进行实验。

> <webpage for="mp-doc" url="https://mp.weixin.qq.com/debug/wxadoc/dev/index.html"></webpage>

示例效果

用户点击交互连接之后,会在工作区打开一个网页。
图片

注意事项:

  • 如果可能,尽量使用超链接,而不是插入网页
  • 只允许插入 HTTPS 网页,否则投稿将不能通过审核

3. 进阶:沉浸式实验能力

3.1 标签和指令

在上面的基础书写说明里,我们已经使用到了标签和指令(如插入时间、插入超链接、视频、公式、网页等)。对于比较复杂的交互,都需要通过标签和指令来定义。

语法

[标签][label-name]

效果

图片

说明:

  • 创建了一个显示内容为「标签」,名称为 label-name 的标签
  • 创建的标签在实验过程中会被渲染成超链接的样式,用户可以点击
  • 仅仅声明一个标签不能让标签工作(即用户在标签上点击毫无反应),需要指令配合才能工作(如使用 <link> 指令)
  • 标签名称没有指令配合的情况下,如果标签名称是一个 URL,则标签会变成一个普通的超链接
  • 标签名称可以缺省,此时使用标签内容作为标签名称,如 [app.js][] 创建了一个显示内容和名称都是 app.js 的标签

指令工作机制

我们使用最简单的 <link> 指令来解释标签的工作机制。

[GitHub][github] 是一个在线代码托管平台,我们可以[点击此处][github]进入 GitHub 主页。 

> <link for="github" href="https://github.com" />

上面的解释说明如下:

  • 指令在 Markdown 引用内容下用 XML 标签定义。
    • 引用内容要在行首以 > 开始,后跟一个空格
    • 如果 XML 占多行,则每一行都需要是引用内容
  • 指令使用 for 属性来指明要作用的标签名称,如果有多个同名标签,则它们都会生效
  • 同一个标签被多个指令作用,只会生效第一个指令
  • 标签和指令只能在步骤正文中使用,在任务正文中无法使用
  • 标签和指令的作用域是实验步骤
    • 在步骤 1 定义的标签,无法在步骤 2 中通过指令来产生作用,反之亦然
    • 部分指令只会在用户当前实验步骤才生效,如 <checker><example>

<link> 指令

标签点击后打开一个超链接。

> <link for="LABEL" href="URL" />
参数 说明
for 作用标签名称
href 链接 URL

<video> 指令

标签点击后在工作区播放视频。

> <video for="LABEL" platform="qq" vid="VID" name="NAME"></video>
参数 说明
for 作用标签名称
platform 视频提供平台,只允许取值为 qq
vid 视频的 ID

<webpage> 指令

标签点击后在工作区打开网页。

> <webpage for="LABEL" url="URL"></webpage>
参数 说明
for 作用标签名称
url 网页 URL

3.2 解释气泡

解释气泡是使你的实验内容变得简洁的工具。用最小的篇幅跟实验用户表达清楚「应该做什么」,至于「为什么这么做」和「更多参考内容」都可以放到解释气泡里显示。
图片

<bubble> 指令

鼠标移动到标签上显示气泡内容。

> <bubble for="LABEL">
>   CONTENT
> </bubble>
参数 说明
for 作用标签名称
children 解释气泡的内容

示例

启动后,可以看到系统已经[监听了 21 端口][21]:

> <bubble for="21">
> FTP 协议默认使用 21 端口作为服务端口
> </bubble>

使用解释图标

如果要解释的内容不方便聚焦在某个短语上,可以使用解释图标表示。

创建一个用户 `ftpuser` [:question][user]:

> <bubble for="user">
> 为了方便后面的实验步骤,不建议使用其它的用户名
> </bubble>

其效果如下:

图片

3.3 检查器

检查器是打造沉浸式实验体验的重要元素。检查器会定时在云主机上运行一条命令,通过命令输出来判断当前步骤是否已经完成。

图片

<checker> 指令

> <checker type="output-contains" command="COMMAND" hint="HINT">
>    <keyword regex="REGEX" />
> </checker>
参数 说明
type 允许取值为 output-containsoutput-contains-no,前者表示输出内容包含指定的内容后通过,后者表示输出内容不包含指定的内容后通过
command 检查器要在云主机后台执行的检查命令
hint 在检查器没有通过,用户又点击下一步时给到用户的提示
keyword.regex 在输出内容中的匹配正则

使用示例

### 创建目录

请使用 mkdir 命令创建目录:`mkdir $HOME/testFolder`

> <checker type="output-contains" command="ls $HOME -la" hint="创建 testFolder 目录">
>     <keyword regex="testFolder" />
> </checker>

在用户按照实验的指引输入命令后,检查器就能检查通过,允许进入下一步。

注意事项:
在检查器的使用中,有一些需要注意的问题。部分 Linux 命令的输出内容是在 stderr 输出的,如果检查器需要检查这部分的输出,需要重定向到 stdin,具体的做法如下:

> <checker type="output-contains" command="nginx -v 2>&amp;1" hint="请先安装 nginx">
>    <keyword regex="\\d" />
> </checker>

命令 nginx -v 的输出是在 2-stderr 上的,我们把它重定向到 1-stdout 上,就可以让检查器正常工作。
在实际书写的过程中,如果碰到指令参数中要使用 &,因为是在 XML 字符串中,我们要转义成 &amp;
如果要使用反斜杠 \,也需要转义,使用 \\

请特别注意:“检查器要在云主机后台执行的检查命令”并非用户键入的命令!

3.4 路径定位

云实验室提供了目录树的功能方便用户进行文件浏览和操作。如果实验过程中希望定位到目录树的某个位置,可以的使用路径定位交互。
图片

<locate> 指令

> <locate for="LABEL" path="PATH" hint="HINT"></locate>
参数 说明
for 作用的标签名
path 要定位的文件或目录路径
hint 定位完成后显示的文案

使用示例

* [定位到 /data 目录][locate-data]
* [定位到 /etc/hosts 文件][locate-host]

> <locate for="locate-data" path="/data" hint="这是 Linux 机器数据存储目录"></locate>
> <locate for="locate-host" path="/etc/hosts" hint="这是 Linux 静态主机记录"></locate>

3.5 文件编辑

和路径定位有点类似,如果希望用户直接打开某个文件编辑,可以使用文件编辑交互。

图片

<edit> 指令

> <edit for="LABEL" file="PATH""></edit>
参数 说明
for 作用的标签名
file 要编辑的文件路径

使用示例

[编辑 /etc/hosts][edit-host],添加一条主机记录

> <edit for="edit-host" file="/etc/hosts"></edit>

3.6 参考代码

参考代码是包含 <example> 指令的代码块,提供更多的能力:

  1. 参考代码会指明期望用户会创建或修改的文件的所在路径
  2. 用户打开相应的文件后,可以和参考代码进行对比
  3. 用户可以在文件浏览器相应的目录右击快速创建或编辑所有在当前步骤所有参考代码对应的文件

图片

<example> 指令

/// <example file="PATH" verb="create|edit" language="LANGUAGE" />

<example> 指令要写在代码块的首行才会生效,前面以三个斜杠开头。

参数 说明
file 目标文件路径
verb 期望用户对文件进行的动作,指定 create 期望用户创建新文件,指定 edit 期望用户修改现有文件
language 文件的语言类型,会根据该值进行代码高亮

使用示例

图片

提示:可以使用工具栏上的插入示例图标来快速插入示例代码

组合文件定位使用

参考代码指明了目标文件的路径,但是这个路径用户是看不见的。我们可以通过文件定位来告知用户目标文件的位置。

图片

3.7 环境变量

我们可以在大部分的正文内容里插入环境变量,在实验运行的时候回替换成环境相关的实际值。

图片

变量 含义
${runtime.vars.cvmIpAddress} 当前使用的云主机的 IP 地址
${runtime.vars.cvmLoginUser} 当前使用的云主机的登录用户名
${runtime.vars.cvmLoginPassword} 当前使用的云主机的登录密码
${runtime.vars.cvmOsType} 当前使用的云主机操作系统类型
${runtime.vars.allocatedPassword} 根据云主机 IP 和实验用户分配的随机密码,可用于提供给实验用户设置密码

4. 建议和反馈

感谢您的耐心阅读!

如果在投稿过程中遇到问题,可以在开发者问答社区进行提问,或者发送邮件到 `DevLabs@tencent.com` 反馈内容。