文档还能这么写？GreptimePlay 邀你免费玩！

在 GreptimeDB 近期的版本中，我们集成了最新的 Dashboard，其中有一个新的模块，我们称之为 GreptimePlay，这篇文章我们来给大家介绍一下这个新模块。

GreptimePlay 首先是一个文档展示平台，同时也是一个代码的 playground，用户可以在这里快速的体验官方的示例代码，也可以自行编写代码运行。

直接点击官网右上角按钮，或者访问 https://greptime.com/playground 即可试用。

其实这个模块的技术方案并不复杂，在聊技术方案之前，我们不妨先聊聊为什么要做这个功能。

产品设计

对于大多数面向开发者的项目来说，文档是十分重要的，它既是学习指南，也是工具手册。尤其是对于新人来说，入门引导的作用非常的重要。记得很多年前我第一次想要使用 React 的时候，被当时它的 Tutorial 完全搞懵了，光是配环境就花了好久，又有很多新的概念，特殊的语法，总之就是一头雾水。

所以对于一个新手来说，什么样的文档才是好的入门文档呢？在我看来，首先要让用户尽快看到效果，知道它是做什么的，这个效果能否符合我的预期。其次是要尽量少的出现新的概念，这样可以以最低的代价帮用户建立一个初始的知识体系锚点。然后围绕这个锚点，再一点点的让用户接收新的知识，直到建立新的完整的知识体系。

按照这种思路，我们应该提供一个直接可运行的环境，这样不需要用户在看到结果前先做一大堆繁琐的环境配置工作。接下来用户可以对照说明文档动手操作，这个文档和可操作的区域越近越好，最好就是结合在一起的。

在这个过程中，新的术语和概念应该尽量缓慢的出现，用户在使用过程中自然的了解和接受，从而习得新的知识。知识应该从普遍性的规律浓缩成概念，而不是首先凭空定义，再去花篇幅去解释，所以，实践最好放在概念之前。

把这几个想法结合在一起，自然就想到了这种产品形态。它看起来有点像 Jupyter Notebook，但我们希望重点放在文档上，着重优化读者的体验。当然，对于文档作者来说，也会注重易用性，在尽可能兼容 Markdown 语法的同时，做一些扩展。所有的优化目标都是为了让文档和实际应用更好的结合。

所以对于 GreptimePlay 来说，精心设计的文档也是产品的一部分，我们会随着 GreptimeDB 的开发，不断更新和增加文档，以帮助用户更好的了解如何使用时序数据，以及如何更好地使用 GreptimeDB。

技术实现

我们希望尽量降低交互式文档的开发成本，所以在数据上选择了和 markdown 兼容的格式，可以保证文档在使用标准 markdown 渲染的时候仍然可读。

实现的技术并不复杂，markdown 渲染使用了 markdown-it，同时使用了 vite-plugin-markdown 插件，这样可以在引用 md 文件的同时加载插件。通过自定义的插件，把 SQL 代码块指定给 vue 组件去渲染。

import type MarkdownIt from 'markdown-it'
export default function customCode(md: MarkdownIt) {  const fence = md.renderer.rules.fence!  md.renderer.rules.fence = (...args) => {    const rawCode = fence(...args)
    const res = rawCode.replace(      /<pre><code class="language-(\w*?)">([\s\S]*)<\/code><\/pre>/,      function ($1: string, $2: string) {        if ($2.toLowerCase() === 'sql') {          return <code-editor lang="${$2}">${$1}</code-editor>        } else {          return <code-editor lang="${$2}" disabled>${$1}</code-editor>        }      }    )    return ${res}  }}

这种基于 markdown 格式的好处就是语法简单，而且有很好的扩展性，可以通过扩展语法，支持更多的语言和交互方式。比如 vitepress 自定的组件使用了自定义的语法格式，可以用来展示信息块。

关于 markdown-it 插件编写，官方的 issue 中提到：大家可以自己去看源码，非常简单，但其实还是有一定门槛的。很神奇的是，我发现中文社区反而有一些不错的文章解释了 markdown-it 插件的原理，比如这篇文章就是很不错的新手入门。

后续计划

• 目前 GreptimePlay 只支持 SQL，后续会支持 PromQL，以及直接通过服务器运行 python 脚本等。

• 我们希望用户能够通过 GreptimePlay 编辑自己的文档，这样可以更好的说明数据的用法，甚至可以把文档当作简单的工作台来使用。

• 虽然名字叫做 GreptimePlay，但是我们希望它不仅是一个玩具，而是能够成为真正的生产力工具。传统的文档有很大的改进空间，我们也会不断探索优化的方向，希望 GreptimePlay 可以持续给大家带来轻松愉快的使用体验。

入口：Greptime 官网首页右上方

关于 Greptime

Greptime 格睿科技于 2022 年创立，目前正在完善和打造时序数据库 GreptimeDB 和格睿云 GreptimeCloud 这两款产品。

GreptimeDB 是款用 Rust 语言编写的时序数据库。具有分布式，开源，云原生，兼容性强等特点，帮助企业实时读写、处理和分析时序数据的同时，降低长期存储的成本。

GreptimeCloud 基于开源的 GreptimeDB，为用户提供全托管的 DBaaS，以及与可观测性、物联网等领域结合的应用产品。利用云提供软件和服务，可以达到快速的自助开通和交付，标准化的运维支持，和更好的资源弹性。GreptimeCloud 已正式开放内测，欢迎关注公众号或官网了解最新动态！

官网：https://greptime.com/

公众号：GreptimeDB

GitHub: https://github.com/GreptimeTeam/greptimedb

文档：https://docs.greptime.com/

Twitter: https://twitter.com/Greptime

Slack: https://greptime.com/slack

LinkedIn: https://www.linkedin.com/company/greptime/