我们在新学习一个项目时，会读项目的文档。有些项目的网页/文档里会嵌入代码，点击运行就能看到效果，学习体验非常好。
如何把自己的项目文档做成这种效果呢？本文介绍下相关技术。
0. 前端教程
很多前端项目的教程都是这种效果，原理很简单，让用户写的 html,css,js 在浏览器中直接执行，不需要后端服务器。
例如 vue tutorials:
https://vuejs.org/tutorial/#step-1
但是支持的语言有限，只适合前端。
1. 在浏览器中“运行” 脚本 + 后端执行
对于其他语言，需要自己搭建后端服务器
- jupyter notebook
示例: https://jupyter.org/try-jupyter/retro/notebooks/?path=notebooks/Intro.ipynb
image.png
需要自己搭建后端服务器，用户在浏览器里操作、运行 js/ipython，但实际上代码是在后端 kernel 里执行的。
所以本质上是webshell (web IDE 原理也是这样）
一些介绍文章:
http://wwj718.github.io/post/%E6%9E%B6%E6%9E%84/jupyter-notebook-architecture/
https://zhuanlan.zhihu.com/p/33105153
https://www.bilibili.com/video/BV1Q4411H7fJ?p=2&spm_id_from=pageDriver
简而言之，Jupyter Notebook是以网页的形式打开，可以在网页页面中直接编写代码和运行代码，代码的运行结果也会直接在代码块下显示的程序。如在编程过程中需要编写说明文档，可在同一个页面中直接编写，便于作及时的说明和解释。
一个有趣的扩展案例是美团拿来对接spark 等大数据平台：
https://www.infoq.cn/article/f32x6fc88r5rext8ulqz
有一些Jupyter的云托管服务，比如 google colab
https://www.ikkaro.com/zh-TW/%E8%B0%B7%E6%AD%8C%E5%90%88%E4%BD%9C%E5%AF%A6%E9%A9%97%E5%AE%A4%E6%88%96%E8%B0%B7%E6%AD%8C%E5%90%88%E4%BD%9C%E5%AF%A6%E9%A9%97%E5%AE%A4/
2. 浏览器浏览文档/教程+ 云端托管服务执行
给用户一个在浏览器里操作的虚拟机 + 教程文档，文档里的脚本点一下就能在虚拟机里执行。
2.1. 国内
shiyanlou
收费
2.2. 国外
Katacoda
https://developer.aliyun.com/article/752183
相比于 shiyanlou 更open 些，能自己写教程
但是，已停运：
https://mp.weixin.qq.com/s/oT9qch7OUjH6oYjLsxxcIQ
Killercoda
https://killercoda.com/
示例: https://killercoda.com/mosn-tutorial/course/layotto/layotto-with-istio
支持从 Katacoda 迁移
K8s 社区也迁移到了 Killercoda
Katacoda to Killercoda Migration Guidedoc
https://killercoda.com/creatorsForeground Background Scripts
https://killercoda.com/examples/scenario/foreground-background-scripts
It's possible to run commands or scripts once a user opens a scenario. This allows to setup whatever is needed before the user starts problem solving or learning.
When using foreground scripts, all commands will be shown to the user in the terminal. When using background scripts, the user won't see the executed commands.
- assets
把自己的东西挂载进文件系统里
https://killercoda.com/examples/scenario/upload-assets
https://github.com/killercoda/scenario-examples/tree/main/upload-assets
CloudYuga
https://cloudyuga.guru/
课程比 killercoda 多；但没找到从 katacoda的迁移教程
Google colab
colab全称为Colaboratory,是免费的Jupyter运行环境,并且完全在云端运行。最重要的是免费，而且不需要你自己去装深度学习的环境
支持GPU，而且是免费使用
地址
https://colab.research.google.com/教程
https://zhuanlan.zhihu.com/p/54389036
https://zhuanlan.zhihu.com/p/367893594
https://www.jianshu.com/p/a42d69568966案例
很多 AI 模型的 demo 会放到 colab，用户打开 web 即可体验模型。
例如 2d 图片转 3d 的demo
https://www.bilibili.com/video/BV11r4y1D7Wk/
https://colab.research.google.com/drive/1706ToQrkIZshRSJSHvZ1RuCiM__YX3Bz
例如启动 Avatarify 服务器
https://colab.research.google.com/github/alievk/avatarify/blob/master/avatarify.ipynb
2.3. 缺点
国内的收费，国外的要魔法上网，敲命令延迟高。
白嫖体验不好，本质上是因为要消耗服务器资源，服务器要花钱。
3. 在浏览器中通过 wasm 运行 server 端
在浏览器中通过 wasm 运行 server 端的好处是：不用再消耗服务器资源
浏览器中运行 tidb
体验地址： TiDB Playground (pingcap.com)
https://pingcap.com/zh/blog/tidb-in-the-browser-running-a-golang-database-on-wasm
https://en.pingcap.com/blog/tidb-in-the-browser-running-a-golang-database-on-webassembly/
浏览器中运行 Postgresql
Postgresql playground:
https://www.bilibili.com/video/BV1bg411r7Fg/?spm_id_from=333.788&vd_source=0771a43f57c2ba3078c77e780c9c5e2f
https://www.crunchydata.com/blog/learn-postgres-at-the-playground
后来开源了 postgresql wasm，见 https://supabase.com/blog/postgres-wasm
浏览器中运行 SQLite
SQLite can be compiled with emscripten without any modifications, and the sql.js library is a thin JS wrapper around the wasm code.
数据量太大，浏览器放不下怎么办?
有了上述技术，我们自然会想到一个idea：如果只做静态网站，可以不花钱租服务器、只用 github pages 等免费托管服务做部署!
技术上，可以把 SQLite 编译成 wasm 运行在浏览器里，每次前端查询db、画图时，其实是在调内存里的 SQLite。这种方案在小数据量的情况下还好，但如果数据库里数据量太大，每次打开页面要下载全量数据，太慢了。怎么办？
有人做了个虚拟文件系统，对 SQLite 提供 page 的抽象，当 SQLite 访问某个 page 时，虚拟文件系统会通过 HTTP Range 请求访问远端的静态文件, 做到按需取数据，减少下载量。作者甚至做了"预取"等利用"局部性原理"的优化。
打开链接即可体验
https://phiresky.github.io/blog/2021/hosting-sqlite-databases-on-github-pages/
https://github.com/phiresky/sql.js-httpvfs
JupyterLite
体验地址(有bug的话可以挂梯子）:
https://jupyterlite.readthedocs.io/en/latest/_static/lab/
介绍:
https://blog.jupyter.org/jupyterlite-jupyter-%EF%B8%8F-webassembly-%EF%B8%8F-python-f6e2e41ab3fa
https://github.com/jupyterlite/demo
原理是把jupyter后端的python服务器跑在wasm里。支持很多解释型语言：
浏览器中运行 Streamlit
https://www.bilibili.com/video/BV14G4y1H7VM/?spm_id_from=333.1007.tianma.2-2-4.click&vd_source=0771a43f57c2ba3078c77e780c9c5e2f&t=74.8
https://edit.share.stlite.net/
4. 运行markdown中的脚本
很多技术文档是 markdown 文件，如果能直接运行 md 文件中的脚本，会让阅读体验好很多。
4.1. 在网页里渲染 markdown、运行其中的 js
https://www.cnblogs.com/guoxiaoming/p/9550075.html
https://guoxiaoming.com/react-code-view/
只适合前端
4.2. IDE/编辑器 里执行
IDE装插件即可
https://hxyxyz.top/index.php/%E6%8A%80%E6%9C%AF/335.html
https://marketplace.visualstudio.com/items?itemName=Sycl.markdown-command-runner
或者用 Rmarkdown
https://sspai.com/post/42841
4.3. 在jupyter中运行markdown格式脚本
https://zhuanlan.zhihu.com/p/39481175
5. 不只是教程: 你的下一个测试用例，何必是代码？
想解决的问题:
https://mosn.io/layotto/#/zh/development/test-quickstart
Quickstart 是项目的门面，如果新用户进入仓库后，发现 Quickstart 文档跑不起来，可能会失望的走掉。
所以我们要经常性的测试 Quickstart, 保证能正常运行。
但是…… 定期手动测试 Quickstart、修复文档中的异常，这个过程实在太花时间了：
5.1. 在命令行中运行 markdown 中的 shell
希望能断言返回状态是不是异常
- mdx
自己写的
https://github.com/seeflood/mdx
todo:
扫描指定目录所有md文件，按顺序执行其中的脚本，支持写断言块
基于 mdsh 这个项目
https://seeflood.github.io/layotto/#/zh/development/test-quickstart
https://github.com/bashup/mdsh
https://gist.github.com/pjeby/c137ace4d91e61e8f1f80e92d84e8b70
- Rmarkdown有命令行工具么?
没找到
5.2. 自动测试你的文档
https://mosn.io/layotto/#/zh/start/
5.3. 用文档测试你的项目. Doc as tests
https://github.com/mosn/layotto/pull/669#issuecomment-1175729841
chore: use start --config parameters in some demos by seeflood · Pull Request #698 · mosn/layotto (github.com)
https://github.com/mosn/layotto/pull/669#issuecomment-1177224860
chore: layotto start without -c or --config by seeflood · Pull Request #3 · MichaelDeSteven/layotto (github.com)
6. Future work
记录一些idea:
文档组件化
文档模板引擎
文档中引用代码片段、代码注释
Online lab using wasm
可以侧边栏打开一个 terminal, wasm运行一个 os，可以预先安装一些软件，例如docker.
点击命令，右边terminal会自动执行online lab using docker desktop
同上，但是点击后通过本地docker desktop执行mdx 和 https://github.com/charmbracelet/vhs 集成
generate gif automatically · Issue #3 · seeflood/mdx (github.com)