# htmd

**Repository Path**: wavef/htmd

## Basic Information

- **Project Name**: htmd
- **Description**: htmd 是一款提供在HTML里利用<htmd-view>标签渲染Markdown的轻量 JavaScript 库。当下 Markdown 早已承载了大量背离其设计初衷的冗余功能 (https://bgslabs.org/blog/why-are-we-using-markdown)，htmd 正是为此而生：让 markdown 回归简洁，让AI把复杂的东西放到 HTML。
- **Primary Language**: JavaScript
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-11
- **Last Updated**: 2026-05-13

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# htmd

A Markdown web component with Shadow DOM isolation, built-in sanitization, and a small styling surface.

默认标签是：

```html
<htmd-view></htmd-view>
```

主要能力：

- 自定义元素和 `render()` 两种用法
- 默认开启 HTML sanitization，可显式关闭
- 内置 `light`、`dark`、`auto` 三种主题
- 支持 CSS 变量和 `::part(...)` 覆写
- 支持 `src` 加载外部 Markdown
- 暴露渲染、加载、错误事件

## 安装

```bash
npm install htmd
```

## 快速开始

```html
<script type="module">
  import 'htmd';
</script>

<htmd-view>
# Hello

这是 **htmd**。
</htmd-view>
```

如果你不想用默认注册名，也可以手动注册：

```ts
import { define } from 'htmd';

define('htmd-view');
```

## 组件用法

### 内联内容

```html
<htmd-view theme="light">
# Title
- Item 1
- Item 2
</htmd-view>
```

### 加载外部文件

```html
<htmd-view src="./doc.md" theme="dark"></htmd-view>
```

### 跟随系统主题

```html
<htmd-view theme="auto">
# Auto Theme
</htmd-view>
```

### 显式关闭 sanitization

```html
<htmd-view sanitize="false">
<img src="x" onerror="alert('unsafe')">
</htmd-view>
```

这个选项只适合完全可信的 Markdown / HTML 输入。

## JS API

### `render(content, options)`

```ts
import { render } from 'htmd';

const html = await render('# Hello', {
  gfm: true,
  breaks: true,
  sanitize: true,
});
```

可用选项：

- `gfm`
- `breaks`
- `sanitize`
- `sanitizeOptions`
- `marked`
- `transformHtml`

### `sanitizeHtml(html, options)`

```ts
import { sanitizeHtml } from 'htmd';

const safeHtml = sanitizeHtml('<img src=x onerror=alert(1)>');
```

### 元素实例 API

```ts
const el = document.querySelector('htmd-view');

await el.setContent('## Updated');
await el.refresh();

console.log(el.html);
```

实例方法和属性：

- `html`
- `refresh()`
- `setContent(markdown)`

## 属性

- `theme`: `light` | `dark` | `auto`
- `src`: 外部 Markdown 文件地址
- `content`: 内联 Markdown 内容
- `gfm`: 默认 `true`
- `breaks`: 默认 `true`
- `sanitize`: 默认 `true`

## 事件

- `htmd:renderstart`
- `htmd:loadstart`
- `htmd:loaded`
- `htmd:rendered`
- `htmd:error`

```ts
const el = document.querySelector('htmd-view');

el.addEventListener('htmd:error', (event) => {
  console.error(event.detail);
});
```

## 样式

### CSS Variables

```html
<htmd-view
  style="
    --htmd-color-bg: #fff7ed;
    --htmd-color-text: #431407;
    --htmd-color-link: #c2410c;
    --htmd-color-border: #fdba74;
  "
>
# Warm Theme
</htmd-view>
```

可覆写变量：

- `--htmd-color-text`
- `--htmd-color-bg`
- `--htmd-color-border`
- `--htmd-color-link`
- `--htmd-color-muted`
- `--htmd-color-code-inline-bg`
- `--htmd-color-code-block-bg`
- `--htmd-color-table-header-bg`
- `--htmd-font-size-base`
- `--htmd-line-height-base`
- `--htmd-space-content-padding`
- `--htmd-space-heading-top`
- `--htmd-space-block-gap`
- `--htmd-space-code-padding`
- `--htmd-radius-inline`
- `--htmd-radius-block`

### `::part(...)`

```html
<style>
  htmd-view::part(heading-1) {
    letter-spacing: 0.08em;
    text-transform: uppercase;
  }

  htmd-view::part(code-block) {
    border: 1px solid #f59e0b;
  }
</style>
```

可用 `part`：

- `content`
- `heading`, `heading-1`, `heading-2`, `heading-3`, `heading-4`
- `paragraph`
- `link`
- `blockquote`
- `code-block`
- `code`
- `code-inline`
- `table`
- `table-head-cell`
- `table-cell`
- `rule`
- `image`
- `list`, `list-unordered`, `list-ordered`
- `list-item`

## 开发

```bash
npm install
npm test
npm run build
npm run dev
```

示例页：

- `examples/index.html`

## 说明

- 浏览器环境下导入包时会自动注册 `<htmd-view>`
- 开启 sanitization 时需要有 DOM 环境
- 如果你要换标签名，传给 `define()` 的名字必须是带连字符的小写标签