@deot/docs-markdown 1.0.10 → 1.1.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +50 -10
- package/dist/index.cjs +770 -316
- package/dist/index.d.ts +35 -2
- package/dist/index.js +767 -318
- package/dist/index.style.css +1 -1
- package/package.json +4 -4
package/README.md
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# @deot/docs-markdown
|
|
2
2
|
|
|
3
|
-
`@deot/docs-markdown` 提供 Vue 3 Markdown 渲染组件，内置文档指示器、标题锚点、链接识别、tip/warning
|
|
3
|
+
`@deot/docs-markdown` 提供 Vue 3 Markdown 渲染组件，内置文档指示器、标题锚点、链接识别、tip/warning 容器、tabs 分栏、代码高亮预览和按需加载的 Playground 容器。
|
|
4
4
|
|
|
5
5
|
## 安装
|
|
6
6
|
|
|
@@ -27,19 +27,24 @@ const source = ref('# Hello @deot/docs');
|
|
|
27
27
|
|
|
28
28
|
组件接受 `modelValue` 或 `value` 字符串。当前组件负责渲染，不会修改传入的 Markdown 内容。
|
|
29
29
|
`locale` 可显式传入 `Language`；未传入时优先使用上层 `provideLocale()`，否则回退到 `en-US`。
|
|
30
|
+
`theme` 控制排版皮肤（`'default' | 'traditional'`），与站点 light/dark 正交。
|
|
31
|
+
`playground` 可传入站点级 Playground 默认 props；`:::playground` 块内 JSON5 配置会浅合并覆盖这些默认值。
|
|
30
32
|
|
|
31
33
|
## 文档指示器
|
|
32
34
|
|
|
33
|
-
|
|
35
|
+
指示器默认开启。它是贴在正文一侧的**小地图**（空间 scrubber），不是第二份目录：刻度与文档壳大纲使用同一份标题（有章节标题时不含页面 h1），按标题在正文中的纵向比例铺在固定高度条上，并用可视窗口标出当前主滚动范围。支持悬停预览、点击定位和拖动浏览，**只滚动、不改 hash**。章节名称导航仍由文档壳右侧大纲负责。
|
|
36
|
+
|
|
37
|
+
定位与文档壳大纲一致：`sticky` 贴顶，高度按正文与主滚动可视区域封顶，轨道上下 padding 为 `40px / 96px`。
|
|
34
38
|
|
|
35
39
|
```vue
|
|
36
40
|
<Markdown
|
|
37
41
|
:value="source"
|
|
38
42
|
:indicator="{
|
|
39
|
-
position: '
|
|
43
|
+
position: 'left',
|
|
40
44
|
preview: true,
|
|
41
45
|
draggable: true,
|
|
42
|
-
|
|
46
|
+
top: 0,
|
|
47
|
+
height: 480
|
|
43
48
|
}"
|
|
44
49
|
/>
|
|
45
50
|
```
|
|
@@ -49,10 +54,10 @@ const source = ref('# Hello @deot/docs');
|
|
|
49
54
|
| 参数 | 类型 | 默认值 | 说明 |
|
|
50
55
|
| --- | --- | --- | --- |
|
|
51
56
|
| `preview` | `boolean` | `true` | 是否展示悬停摘要。 |
|
|
52
|
-
| `draggable` | `boolean` | `true` |
|
|
53
|
-
| `position` | `'left' \| 'right'` | `'
|
|
54
|
-
| `top` | `number \| string` | `0` |
|
|
55
|
-
| `height` | `number \| string` |
|
|
57
|
+
| `draggable` | `boolean` | `true` | 是否允许拖动快速浏览。关闭后仍可点击轨道定位。 |
|
|
58
|
+
| `position` | `'left' \| 'right'` | `'left'` | 指示器所在侧。文档壳中有斜纹轨时靠近 `rail--start` 右侧或 `rail--end` 左侧，并留 8px 间距。 |
|
|
59
|
+
| `top` | `number \| string` | `0` | sticky 贴顶偏移，数字按 px 处理。 |
|
|
60
|
+
| `height` | `number \| string` | 按正文/视口封顶 | 小地图总高度（含上下 padding）。数字会与封顶值取较小值；未配置时使用封顶后的 px。 |
|
|
56
61
|
|
|
57
62
|
## Markdown 扩展
|
|
58
63
|
|
|
@@ -68,6 +73,37 @@ const source = ref('# Hello @deot/docs');
|
|
|
68
73
|
:::
|
|
69
74
|
````
|
|
70
75
|
|
|
76
|
+
### Tabs 分栏
|
|
77
|
+
|
|
78
|
+
每一栏用 **4 个反引号** 的 fence（info 为 `markdown <标题>`），这样栏内还能写普通 ` ``` ` 代码块。切换时写入 `?tab=<id>`（标题小写、空白变 `-`；非 ASCII 与标题锚点一致做 `encodeURIComponent`）。
|
|
79
|
+
|
|
80
|
+
`````markdown
|
|
81
|
+
:::tabs
|
|
82
|
+
````markdown Linux
|
|
83
|
+
Linux 安装步骤，可含普通代码块：
|
|
84
|
+
|
|
85
|
+
```ts
|
|
86
|
+
const value = 1;
|
|
87
|
+
```
|
|
88
|
+
````
|
|
89
|
+
````markdown Android
|
|
90
|
+
Android 安装步骤。
|
|
91
|
+
````
|
|
92
|
+
:::
|
|
93
|
+
`````
|
|
94
|
+
|
|
95
|
+
栏内若再嵌套 `:::tip` / `:::playground` / `:::warning`，外层必须加长冒号（`::::tabs` … `::::`）。`markdown-it-container` 会按「足够长的纯 `:::` 行」闭合外层，内层结束标记会提前关掉 `:::tabs`。
|
|
96
|
+
|
|
97
|
+
``````markdown
|
|
98
|
+
::::tabs
|
|
99
|
+
````markdown Demo
|
|
100
|
+
:::tip
|
|
101
|
+
嵌套提示。
|
|
102
|
+
:::
|
|
103
|
+
````
|
|
104
|
+
::::
|
|
105
|
+
``````
|
|
106
|
+
|
|
71
107
|
### 单文件 Playground
|
|
72
108
|
|
|
73
109
|
````markdown
|
|
@@ -90,6 +126,7 @@ const source = ref('# Hello @deot/docs');
|
|
|
90
126
|
<config lang="json5">
|
|
91
127
|
{
|
|
92
128
|
entry: 'main.js',
|
|
129
|
+
title: '多文件示例',
|
|
93
130
|
views: ['runtime', 'files'],
|
|
94
131
|
viewport: 375,
|
|
95
132
|
viewportOptions: ['auto', 375, [375, 667]]
|
|
@@ -111,7 +148,8 @@ createApp(App).mount('#app');
|
|
|
111
148
|
````
|
|
112
149
|
|
|
113
150
|
支持的 `views` 值为 `runtime` 和 `files`。`viewport` 可为 `auto`、正数宽度或 `[width, height]`。
|
|
114
|
-
`
|
|
151
|
+
`title` 为可选字符串，显示在运行时顶栏左侧；空串或不传不渲染。有标题时会生成锚点 id（可用 `#...` 跳转），规则与 markdown heading 一致；也可用 `id` 显式覆盖。
|
|
152
|
+
`expandable` 为可选：`true` 展开到剩余视口，正数为展开目标高度（px）；未配置时不显示展开控件。
|
|
115
153
|
|
|
116
154
|
Playground 会在浏览器里编译 Vue SFC 的 `<style lang="scss">` 以及独立 `.scss` / `.sass` 文件。下划线 partial（如 `_variables.scss`）只作为 `@use` 依赖，不会单独注入预览。
|
|
117
155
|
|
|
@@ -123,8 +161,10 @@ Playground 只在页面出现 fence 或 `:::playground` 时动态加载。使用
|
|
|
123
161
|
| --- | --- |
|
|
124
162
|
| `Markdown` | Vue Markdown 渲染组件。 |
|
|
125
163
|
| `parseMarkdownSearchSections(content)` | 使用渲染器相同的标题锚点规则提取文档标题、正文和小节，供搜索索引使用。 |
|
|
164
|
+
| `toMarkdownTabId(title)` | 将 Tab 标题转为 `?tab=` id。 |
|
|
165
|
+
| `markdownTabQueryKey` / `createHistoryTabQueryAdapter` | 文档壳可 `provide` Router 版适配器；独立预览回退 history。 |
|
|
126
166
|
|
|
127
|
-
类型：`MarkdownSearchDocument`、`MarkdownSearchSection`、`MarkdownIndicatorConfig`、`MarkdownIndicatorOptions`、`MarkdownPlaygroundConfig`、`MarkdownPlaygroundMountProps`。
|
|
167
|
+
类型：`MarkdownSearchDocument`、`MarkdownSearchSection`、`MarkdownIndicatorConfig`、`MarkdownIndicatorOptions`、`MarkdownPlaygroundConfig`、`MarkdownPlaygroundMountProps`、`MarkdownTabQueryAdapter`。
|
|
128
168
|
|
|
129
169
|
底层 markdown-it 实例和内部指令不是包入口的公共导出。搜索解析结果不会包含代码围栏和 HTML 内容。
|
|
130
170
|
|