文档还能这么写？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[1]中提到：大家可以自己去看源码，非常简单 ，但其实还是有一定门槛的。很神奇的是，我发现中文社区反而有一些不错的文章解释了 markdown-it 插件的原理，比如这篇文章[2]就是很不错的新手入门。
后续计划
目前 GreptimePlay 只支持 SQL，后续会支持 PromQL，以及直接通过服务器运行 python 脚本等。
我们希望用户能够通过 GreptimePlay 编辑自己的文档，这样可以更好地说明数据的用法，甚至可以把文档当作简单的工作台来使用。
虽然名字叫做 GreptimePlay，但是我们希望它不仅是一个玩具，而是能够成为真正的生产力工具。传统的文档有很大的改进空间，我们也会不断探索优化的方向，希望 GreptimePlay 可以持续给大家带来轻松愉快的使用体验。
入口：Greptime 官网首页右上方，
欢迎试用：https://greptime.com/playground
参考
[1] https://github.com/markdown-it/markdown-it/issues/10
[2] https://zhuanlan.zhihu.com/p/400036665
关于 Greptime
Greptime 格睿科技于 2022 年创立，目前正在完善和打造时序数据库 GreptimeDB 和格睿云 GreptimeCloud 这两款产品。
GreptimeDB 是款用 Rust 语言编写的时序数据库。具有分布式，开源，云原生，兼容性强等特点，帮助企业实时读写、处理和分析时序数据的同时，降低长期存储的成本。
GreptimeCloud 基于开源的 GreptimeDB，为用户提供全托管的 DBaaS，以及与可观测性、物联网等领域结合的应用产品。利用云提供软件和服务，可以达到快速的自助开通和交付，标准化的运维支持，和更好的资源弹性。GreptimeCloud 已正式开放内测，欢迎关注公众号或官网了解最新动态！
官网：https://greptime.com/
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/
往期精彩文章：
👇 点击下方阅读原文，立刻前往 GitHub 下载体验开源的时序数据库 GreptimeDB