
CompMD 发布:用组件扩展 Markdown,纯文本仍可读
来源标题:Show HN: CompMD – Markdown with components that still reads as plain Markdown
CompMD 让 Markdown 文档可以嵌入盒子、网格、数据值和读者可交互的输入,同时文件本身仍保持纯文本可读。组件以 ::: 开头的独立行书写、参数放在花括号里,CompMD 处理器负责渲染,其他 Markdown 工具则显示为普通文字。该项目以 Show HN 形式发布,示例页面在站点构建时由处理器生成。
以下正文由 AI 翻译自 Hacker News 最新(原文版权归原站所有),可能存在偏差,重要内容请以原文为准。
以文本阅读,以页面呈现。盒子、网格、来自数据的值和读者可以更改的输入,都用仍然读起来像 Markdown 的行来书写。
Thursday Book Club We meet on the last Thursday of the month, at Ana's. Pick a cover to see what we made of it. Klara and the Sun, Kazuo Ishiguro. We're halfway through. Bring your questions on Thursday.
它有标题、列表和表格,但没法把两样东西并排放,没法展示数据中的数字,也没法让读者改变页面显示的内容。
MDX 把文档变成一个需要构建的程序,而模板把文本埋进标记里。无论哪种方式,文件都不再读起来像文本。
组件是单独的一行,::: box,参数放在花括号里。CompMD 处理器会渲染它;任何其他 Markdown 工具都会显示可读的文本。
每个示例都是一个文档及其渲染出的页面,由处理器在本站构建时生成。
在 CompMD 本身中定义一次组件:带类型的参数、一个主体,以及调用者填充的命名插槽。
params:
title: string
slots: [default, footer]
---
**{{title}}**
{{md.slot}}
{{md.slot.footer}}
::: card {title="Ship the beta"} Three small tasks left. :: #footer Due Friday. ::: /card
Ship the beta
从 frontmatter 读取 CSV、JSON 或 YAML,然后用表达式过滤、排序和求和。
md: data:
- from: ./books.csv as: books schema: {title: string, author: string, year: number, pages: number}
::: each {in=(md.sortBy(md.data.books, "year")) as=b join=list}
- {{b.title}}, {{b.author}} ({{b.year}}) ::: /each
:value[1,945 pages]{of=(md.number(md.sum(md.data.books.map(b, b.pages)), 0) + " pages")} in all.
Pride and Prejudice, Jane Austen (1813) A Gentleman in Moscow, Amor Towles (2016)
声明一个读者可以更改的值,把输入绑定到它,页面就会跟着变。试试看。
md: data:
- from: ./books.csv as: books schema: {title: string, author: string, year: number, pages: number} inputs: since: number = 1970
:: number-input[Published since: 1970] {bind=since}
::: each {in=(md.data.books.filter(b, b.year >= md.input.since)) as=b join=list}
- {{b.title}} ({{b.year}}) :: #empty No book is that recent. ::: /each
Published sinceA Gentleman in Moscow (2016)
网格、行和堆叠跟随它们所在盒子的宽度,而不是窗口。
::: grid {min=7rem gap=s} ::: box {padding=s background=subtle border-radius=m} Plan ::: /box ::: box {padding=s background=subtle border-radius=m} Build ::: /box ::: box {padding=s background=accent border-radius=m} Ship ::: /box ::: /grid
Plan
当 CompMD 不够用时,用 JSX、TSX、Svelte 或 JavaScript 编写组件。它在沙箱中运行,就像这个一样;无法运行它的渲染器会显示其回退内容。
params:
value: number
label: string
export default function Meter({ value, label }) {
return (
<label style={{ display: "grid", gap: 6 }}>
<span>{label}: <strong>{value}%</strong></span>
<progress max="100" value={value} style={{ width: "100%" }} />
</label>
);
:: meter[Docs: 72%] {label="Docs" value=72}
Docs: 72%
代码渲染器 组件可以绘制某种语言的代码块,比如 Mermaid 图表。文档保留一个普通的代码块,GitHub 和其他渲染器会像往常一样显示它。
md: import:
- from: ./minimermaid.js names: [minimermaid]
renders: mermaid
params:
theme: default | dark | neutral = default
graph TD; Draft --> Review --> Published
graph TD; Draft --> Review --> Published
表格单元格中的组件 内联组件可以出现在任何文本出现的地方,表格单元格也不例外:每个城市这一周的图表由文档旁边文件中的一个组件绘制。
md: import:
- from: ./spark.js names: [spark]
| City | This week | Today |
|---|---|---|
| Lisbon | :spark[16–22 °C]{values=[17, 19, 22, 21, 18, 16, 20]} | 20 °C |
| Oslo | :spark[3–9 °C]{values=[3, 5, 4, 7, 9, 6, 6]} | 6 °C |
| Cairo | :spark[24–31 °C]{values=[24, 27, 31, 30, 28, 29, 29]} | 29 °C |
params:
values: array
CityThis weekTodayLisbon16–22 °C20 °COslo3–9 °C6 °CCairo24–31 °C29 °C
可以安全打开 CompMD 文档可以来自任何人。打开它不会在你的页面中运行代码、访问你的数据或向外发送信息。
来自陌生人的文档,或它导入的包,如果试图在读者的页面中运行代码、读取读者的数据或会话、向外发送数据、无限运行,或以读者的名义行事。
规范的 section 15 规定了每个实现必须做什么。
CompMD 文件就是 Markdown 文件。在 GitHub 上、在编辑器的预览中或在任何 Markdown 渲染器中,它都读起来很顺畅:每个组件显示其回退文本,没有任何东西变成噪音。切换渲染器看看。
Team offsite
We meet in Lisbon on 12–13 June. Flights are booked, and the hotel is a short walk from the venue.
::: grid {min=12rem gap=m} Thursday. Arrive by noon, then the roadmap in the afternoon.
Friday. Workshops in the morning, and the afternoon is yours. ::: /grid
::: box {background=accent padding=m border-radius=m} Bring your laptop charger: the venue has none to lend. ::: /box
[!NOTE] Questions go to Maya.
Team offsite We meet in Lisbon on 12–13 June. Flights are booked, and the hotel is a short walk from the venue.
Thursday. Arrive by noon, then the roadmap in the afternoon.
Friday. Workshops in the morning, and the afternoon is yours.
Bring your laptop charger: the venue has none to lend.
一个没有任何组件的文档也是 CompMD 文档,并且会获得处理器和渲染器赋予任何文档的一切。
Trip checklist
- Book the train
- Pack the charger1
| Day | City |
|---|---|
| Mon | Lyon |
| Tue | Turin |
[!TIP] Check the strike calendar the night before.
Trip checklist Book the train
(原文较长,此处译出前 6000 字,完整内容请点「打开原文」。)
Footnotes
-
The long cable. ↩
正文由 探How 从来源站点 RSS 同步,内容未经改写;遇到排版缺失或需要图片、视频时请以原文为准。