提前锁票 InfoQ 最具价值感的视频栏目 | InfoQ 大咖说 了解详情
写点什么

MDJS:可将 JavaScript 添加到 Markdown,创建交互式文档

2020 年 4 月 27 日

MDJS:可将JavaScript添加到Markdown,创建交互式文档

Open Web Components(@OpenWc)创建者Thomas Allmer发布了MDJS,这是一种 Markdown 变体,支持在 Markdown 文档中包含可运行的 JavaScript 代码。MDJS 可以解释为常规的 Markdown 内容,也可以进一步升级为带有 Web 组件的交互式文档。


MDJS 通过三个新结构增强了 Markdown 的代码块语法:script、story、preview-story。


以下 Markdown 源代码:


​```js scriptimport './my-component.js';  ​```
# This is my component <my-component></my-component>
复制代码


将生成下面的 JavaScript 和 HTML 代码:


import './my-component.js';  
<h1>This is my component</h1><my-component></my-component>
复制代码


js代码块的script注解用来加载 Web 组件并在 Markdown 源代码中使用。


第二个注解 story 用法如下:


​```js script  import './demo-wc-card.js';  import { html } from 'lit-html';  ​```  
# This is my component
​```js story export const demo = () => html` <demo-wc-card header="HEADER"></demo-wc-card> `; ​```
复制代码


可编辑演示文档链接


上例中嵌入的 JavaScript 包含一个工厂函数,使用 lit-html 模板来生成 HTML。以上代码将生成以下 JavaScript 和 HTML:


import './demo-wc-card.js';import { html } from 'lit-html';
export const demo = () => html` <demo-wc-card></demo-wc-card>`;
<h1>This is my component</h1><mdjs-story mdjs-story-name="demo"> #shadow-root (open) <demo-wc-card></demo-wc-card></mdjs-story>
复制代码


可编辑演示文档链接


Web 组件是由 MDJS 提供的,它封装了用户提供的 Web 组件。preview-story 添加了与 story 类似的功能,不过组件会有边框,还会有一个按钮,用来显示/隐藏实际的源代码。


MDJS 读起来像标准的 Markdown,不需要修改就可以在 MDJS 上下文或场景之外使用。代码块将正常显示代码。不过,MDJS 增强了标准的 Markdown 行为(通过加载的 Web 组件所提供的额外交互性)和源代码预览功能。这样,开发人员就可以使用 Markdown、JavaScript 和 Web 组件创建交互式演示文档。举例来说,开发人员可以用它记录基于 Web 组件的系统设计过程。


到目前为止,MDJS 既可以通过 es-dev-server 在本地使用,也可以通过 Storybook 使用,还可以在 GitHub 页面(例如 README 页面或问题页面)或在webcomponents.dev IDE 中使用。


Allmer 将 MDJS 的用例总结如下:


MDJS 是一种可以以多种不同的方式显示的格式。

让漂亮的文档随处可见。

在本地、已发布的 Storybook、GitHub 或 npmjs 上,即使没有直接的支持,也没有问题,只要可能,它就可升级为交互式演示文档。


MDJS 提供了与 MDX 类似的功能,后者在 Markdown 中包含了JSX。JSX 是为了与 React 生态系统进行交互而开发的,而 MDJS 依赖于已在大多数浏览器中实现的标准 JavaScript 和 Web 组件。此外,MDJS 源代码可以在任何地方使用。


MDJS 的路线图包括改进样式,支持更多的渲染器,而不仅仅是 litt -html,高亮显示代码段,等等。开发人员可以点击这里查看官方文档。


原文链接:


New MDJS Markup Language Adds JavaScript to Markdown for Interactive Documentation


2020 年 4 月 27 日 09:001515

评论

发布
暂无评论
发现更多内容

Nginx-技术专题-技术介绍

李浩宇/Alex

SQL数据库:窗口函数

正向成长

窗口函数

【薪火计划】03 - 从错误中认识到管理

brave heart

管理

vue项目实战经验汇总

徐小夕

Java 面试 Vue 前端 Vue3

【活动回顾】WebRTC服务端工程实践和优化探索

ZEGO即构

WebRTC 服务端工程

什么是低代码(Low-Code)?

应用研发平台EMAS

工具 研发效能 低代码 开发 代码

科普干货|漫谈鸿蒙LiteOS-M与HUAWEI LiteOS内核的几大不同

华为云开发者社区

华为 鸿蒙 IoT

Dubbo 接口,导出 Markdown ,这些功能 DocView 现在都有了!

程序员小航

markdown idea插件 IntelliJ IDEA 文档生成 Doc View

Glide.with(view)挂在了谁的生命周期上

mengxn

生命周期 Glide Activity Fragment

MySQL中的锁机制

AI乔治

Java MySQL 架构 线程 锁机制

11.11 应对海量访问的网络基石 京东智联云自研交换机发展之路

京东科技开发者

运维 网络 交换机

CSS 排版与正常流 —— 重学CSS

三钻

CSS 排版

Jira停售Server版政策客观解读——如何最小化风险?

PingCode

项目管理 研发管理 Jira Atlassian

#不吐不快# 三观很正的Boss,你遇到过么?

架构精进之路

职场成长 奇葩的经历 不吐不快

一瞬间让我秒变“快男”!腾讯内部强推Java性能优化手册,快了不止一点点。

Java架构追梦

Java 架构 jdk 面试 性能优化

《网络是怎样连接的》PDF下载

计算机与AI

网络

Springboot过滤器和拦截器详解及使用场景

AI乔治

Java spring 架构 Spring Boot

#不吐不快# CV千千条,修改最重要。代码不规范,伙伴两行泪!

程序员小航

奇葩的经历 不吐不快

IoT企业物联网平台,从设备端到云端业务系统全链路开发实战

苏堤嘉木

阿里云 最佳实践 物联网 IoT

甲方日常53

句子

工作 随笔杂谈 日常

什么是云服务?

anyRTC开发者

音视频 WebRTC 云服务 RTC

注册中心原理剖析

石刻掌纹

MySQL从库维护经验分享

Simon

MySQL 主从复制

圆通快递回应内鬼泄露用户信息:严打数据倒卖灰色产业

石头IT视角

Redis 持久化之 RDB 与 AOF 详解

AI乔治

Java 架构 redis持久化 redia

前嗅教你大数据——什么是代理IP?

前嗅大数据

爬虫 数据采集 静态IP 代理IP 动态IP

DàYé的CTO姗姗学步路

曲水流觞TechRill

管理 CTO

交易所做市机器人,自动跑K线机器人,市值管理

WX13823153201

synchronized 到底该不该用

古时的风筝

Java synchronized

阿里P8以hashmap讲解如何学习jdk源码,还不学习

小Q

Java 学习 源码 jdk mybatis

面经手册 · 第18篇《AQS 共享锁,Semaphore、CountDownLatch,听说数据库连接池可以用到!》

小傅哥

Java 并发编程 共享锁 Semaphore 信号量

打造 VUCA 时代的 10 倍速 IT 团队

打造 VUCA 时代的 10 倍速 IT 团队

MDJS:可将JavaScript添加到Markdown,创建交互式文档-InfoQ