mdld-parse 0.9.9 → 1.0.0
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 +242 -330
- package/dist/index.js +1793 -1336
- package/package.json +4 -4
- package/dist/.nojekyll +0 -0
- package/dist/CNAME +0 -1
- package/dist/README.md +0 -500
- package/dist/docs/API.md +0 -435
- package/dist/docs/Architecture.md +0 -190
- package/dist/docs/Guide.md +0 -816
- package/dist/docs/LLM-MDLD-Inducer.md +0 -550
- package/dist/docs/LiterateRDF.md +0 -472
- package/dist/docs/Parser.md +0 -720
- package/dist/docs/Performance.md +0 -238
- package/dist/docs/Spec-render.md +0 -1439
- package/dist/docs/Subject.md +0 -180
- package/dist/docs/Syntax.md +0 -463
- package/dist/docs/TodoList.md +0 -215
- package/dist/docs/Use-Cases.md +0 -354
- package/dist/docs/guide-m.md +0 -56
- package/dist/docs/index.html +0 -108
- package/dist/docs/index.md +0 -56
- package/dist/docs/one-page.md +0 -322
- package/dist/docs/origin.md +0 -460
- package/dist/docs/polarity.md +0 -586
- package/dist/docs/primary-subject.md +0 -326
- package/dist/docs/statements.md +0 -226
- package/dist/docs/tokenization-performance-report.md +0 -164
- package/dist/examples/Cookbook.md +0 -32
- package/dist/examples/Status-SHACL.md +0 -31
- package/dist/examples/demo/index.md +0 -35
- package/dist/examples/demo/journal.md +0 -58
- package/dist/examples/demo/minimal.md +0 -23
- package/dist/examples/demo/project.md +0 -84
- package/dist/examples/demo/prov.md +0 -107
- package/dist/examples/demo/rdf.md +0 -69
- package/dist/examples/demo/recipe.md +0 -50
- package/dist/examples/demo/research.md +0 -84
- package/dist/examples/demo/shacl.md +0 -161
- package/dist/examples/demo/space-mission.md +0 -58
- package/dist/examples/demo/tasks.md +0 -175
- package/dist/examples/demo/xsd.md +0 -91
- package/dist/examples/dogfood.md +0 -288
- package/dist/examples/few-shot.md +0 -309
- package/dist/examples/graph/rdf-graph.html +0 -473
- package/dist/examples/graph/rdf_force_graph_web_component.html +0 -506
- package/dist/examples/index.md +0 -45
- package/dist/examples/llm-time-workflow.md +0 -173
- package/dist/examples/statements.md +0 -43
- package/dist/examples/workflow.md +0 -150
- package/dist/index.html +0 -3049
- package/dist/logo.svg +0 -7
- package/dist/spec/Spec-compact.md +0 -368
- package/dist/spec/Spec-ultra.md +0 -232
- package/dist/spec/Spec.md +0 -1116
- package/dist/spec/index.md +0 -46
package/dist/docs/Spec-render.md
DELETED
|
@@ -1,1439 +0,0 @@
|
|
|
1
|
-
# MD-LD Render Specification
|
|
2
|
-
|
|
3
|
-
**HTML+RDFa Rendering for MD-LD Documents**
|
|
4
|
-
|
|
5
|
-
A deterministic, streaming-friendly renderer that transforms valid MD-LD text into semantically meaningful HTML+RDFa markup ready for browser rendering while maintaining complete provenance and supporting interactive agent experiences.
|
|
6
|
-
|
|
7
|
-
---
|
|
8
|
-
|
|
9
|
-
## 1. Design Philosophy
|
|
10
|
-
|
|
11
|
-
### Core Principles
|
|
12
|
-
|
|
13
|
-
The MD-LD Render follows the same engineering principles as the parser:
|
|
14
|
-
|
|
15
|
-
- **Streaming-first** — Single-pass rendering, O(n) complexity
|
|
16
|
-
- **Zero dependencies** — Pure JavaScript implementation
|
|
17
|
-
- **Semantic fidelity** — Preserves all RDF semantics in HTML+RDFa
|
|
18
|
-
- **Agent empowerment** — Enables interactive knowledge graph authoring
|
|
19
|
-
- **Provenance preservation** — Maintains complete source tracking
|
|
20
|
-
- **Round-trip safety** — HTML ↔ MD-LD ↔ RDF transformation chain
|
|
21
|
-
|
|
22
|
-
### Architecture Alignment
|
|
23
|
-
|
|
24
|
-
The render mirrors the parser's architecture:
|
|
25
|
-
|
|
26
|
-
1. **Parser Output** → Render State (single-pass transformation)
|
|
27
|
-
2. **Token Processing** → Block Rendering (deterministic mapping)
|
|
28
|
-
3. **Semantic Blocks** → RDFa Attributes (semantic preservation)
|
|
29
|
-
4. **Origin Tracking** → Interactive Features (agent enablement)
|
|
30
|
-
|
|
31
|
-
---
|
|
32
|
-
|
|
33
|
-
## 2. Rendering Pipeline
|
|
34
|
-
|
|
35
|
-
### Phase 1: Parse Integration
|
|
36
|
-
|
|
37
|
-
```javascript
|
|
38
|
-
// Reuse parser output for consistency
|
|
39
|
-
const parsed = parse({ text: mdld, context: options.context || {} });
|
|
40
|
-
```
|
|
41
|
-
|
|
42
|
-
**Input:** Valid MD-LD text
|
|
43
|
-
**Output:** Parser result with quads, origin, context, statements
|
|
44
|
-
|
|
45
|
-
**Key Integration Points:**
|
|
46
|
-
- Use parser's resolved context for IRI expansion
|
|
47
|
-
- Leverage origin tracking for interactive features
|
|
48
|
-
- Preserve quad structure for semantic validation
|
|
49
|
-
- Maintain statement extraction for elevated patterns
|
|
50
|
-
|
|
51
|
-
### Phase 2: Render State Construction
|
|
52
|
-
|
|
53
|
-
```javascript
|
|
54
|
-
const state = {
|
|
55
|
-
ctx: parsed.context, // Resolved prefix context
|
|
56
|
-
df: DataFactory, // RDF/JS DataFactory
|
|
57
|
-
baseIRI: options.baseIRI, // Base IRI for resolution
|
|
58
|
-
sourceText: mdld, // Original text for extraction
|
|
59
|
-
output: [], // Accumulated HTML output
|
|
60
|
-
currentSubject: null, // Subject context tracking
|
|
61
|
-
documentSubject: null, // Document-level subject
|
|
62
|
-
blockStack: [], // Nested block context
|
|
63
|
-
carrierStack: [] // Inline carrier context
|
|
64
|
-
};
|
|
65
|
-
```
|
|
66
|
-
|
|
67
|
-
**State Characteristics:**
|
|
68
|
-
- **Minimal footprint** — Only essential rendering state
|
|
69
|
-
- **Context preservation** — Parser context fully available
|
|
70
|
-
- **Streaming compatible** — Can process incrementally
|
|
71
|
-
- **Interactive ready** — State supports agent interactions
|
|
72
|
-
|
|
73
|
-
### Phase 3: Block Processing Pipeline
|
|
74
|
-
|
|
75
|
-
```javascript
|
|
76
|
-
// Sort blocks by source position (deterministic)
|
|
77
|
-
const sortedBlocks = Array.from(parsed.origin.blocks.values())
|
|
78
|
-
.sort((a, b) => a.range.start - b.range.start);
|
|
79
|
-
|
|
80
|
-
// Process blocks by type
|
|
81
|
-
sortedBlocks.forEach(block => renderBlock(block, state));
|
|
82
|
-
```
|
|
83
|
-
|
|
84
|
-
**Processing Strategy:**
|
|
85
|
-
- **Positional ordering** — Maintains document structure
|
|
86
|
-
- **Type-specific rendering** — Optimized for each carrier type
|
|
87
|
-
- **Context propagation** — Maintains semantic relationships
|
|
88
|
-
- **RDFa enrichment** — Adds semantic markup to HTML
|
|
89
|
-
|
|
90
|
-
### Phase 4: RDFa Context Wrapping
|
|
91
|
-
|
|
92
|
-
```javascript
|
|
93
|
-
const wrapped = wrapWithRDFaContext(html, state.ctx);
|
|
94
|
-
```
|
|
95
|
-
|
|
96
|
-
**Final Output Structure:**
|
|
97
|
-
```html
|
|
98
|
-
<div prefix="schema: http://schema.org/ ex: http://example.org/"
|
|
99
|
-
vocab="http://www.w3.org/2000/01/rdf-schema#">
|
|
100
|
-
<!-- Rendered content with RDFa attributes -->
|
|
101
|
-
</div>
|
|
102
|
-
```
|
|
103
|
-
|
|
104
|
-
---
|
|
105
|
-
|
|
106
|
-
## 3. Block Rendering System
|
|
107
|
-
|
|
108
|
-
### 3.1 Carrier Types and Rendering Strategy
|
|
109
|
-
|
|
110
|
-
#### Block-Level Carriers
|
|
111
|
-
|
|
112
|
-
| Carrier Type | Markdown Syntax | HTML Element | RDFa Strategy | Example |
|
|
113
|
-
|--------------|----------------|--------------|---------------|---------|
|
|
114
|
-
| **heading** | `# Heading {...}` | `<h1>`-`<h6>` | `about`, `typeof`, `property` | `# Title {=ex:title .schema:Thing label}` |
|
|
115
|
-
| **paragraph** | `Text {...}` | `<p>` | `about`, `property`, `rel` | `Content {ex:description}` |
|
|
116
|
-
| **list** | `- Item {...}` | `<ul>`/`<li>` | Hierarchical RDFa | `- Item {=ex:item .schema:ListItem name}` |
|
|
117
|
-
| **blockquote** | `> Quote {...}` | `<blockquote>` | `about`, `property` | `> "Quote" {ex:quote}` |
|
|
118
|
-
| **code** | ````code {...}```` | `<pre><code>` | `about`, `typeof` | ````js {=ex:code .ex:SoftwareSourceCode}```` |
|
|
119
|
-
| **standalone** | `{=subject}` | `<div>` | `about`, `typeof` | `{=ex:subject .ex:Type}` |
|
|
120
|
-
|
|
121
|
-
#### Inline Carriers
|
|
122
|
-
|
|
123
|
-
| Carrier Type | Markdown Syntax | HTML Element | RDFa Strategy | Subject Resolution | Example |
|
|
124
|
-
|--------------|----------------|--------------|---------------|------------------|---------|
|
|
125
|
-
| **emphasis** | `*text* {...}` | `<em>` | `property`, `rel` | Current subject | `*important* {ex:emphasis}` |
|
|
126
|
-
| **strong** | `**text** {...}` | `<strong>` | `property`, `rel` | Current subject | `**warning** {ex:alert}` |
|
|
127
|
-
| **code span** | `` `code` {...} `` | `<code>` | `property`, `rel` | Current subject | `` `console.log()` {ex:code}`` |
|
|
128
|
-
| **link** | `[text](url) {...}` | `<a href="url">` | `about`, `property`, `rel` | URL becomes subject | `[NASA](https://nasa.gov) {.schema:Organization label}` |
|
|
129
|
-
| **image** | ` {...}` | `<img src="url" alt="alt">` | `about`, `property`, `rel` | URL becomes subject | ` {ex:logo}` |
|
|
130
|
-
| **angle link** | `<url> {...}` | `<a href="url">` | `about`, `property`, `rel` | URL becomes subject | `<https://example.com> {ex:reference}` |
|
|
131
|
-
|
|
132
|
-
#### Link Carrier Special Handling
|
|
133
|
-
|
|
134
|
-
**Markdown Link Syntax `[text](url)`:**
|
|
135
|
-
|
|
136
|
-
1. **Subject Resolution Priority:**
|
|
137
|
-
- Explicit subject (`{=iri}`) > URL > Current subject
|
|
138
|
-
- When explicit subject present: URL becomes object resource
|
|
139
|
-
- When no explicit subject: URL becomes subject
|
|
140
|
-
|
|
141
|
-
2. **RDFa Attribute Generation:**
|
|
142
|
-
```javascript
|
|
143
|
-
// Case 1: Explicit subject with URL
|
|
144
|
-
[Link](https://example.com) {=ex:subject .Type label}
|
|
145
|
-
// Output: <a href="https://example.com" about="ex:subject" typeof="ex:Type" property="rdfs:label">Link</a>
|
|
146
|
-
|
|
147
|
-
// Case 2: URL as subject (no explicit subject)
|
|
148
|
-
[Link](https://example.com) {.Type label}
|
|
149
|
-
// Output: <a href="https://example.com" about="https://example.com" typeof="ex:Type" property="rdfs:label">Link</a>
|
|
150
|
-
|
|
151
|
-
// Case 3: Object property with explicit subject
|
|
152
|
-
[Link](https://example.com) {=ex:subject ?references}
|
|
153
|
-
// Output: <a href="https://example.com" about="ex:subject" rel="ex:references">Link</a>
|
|
154
|
-
```
|
|
155
|
-
|
|
156
|
-
3. **Content Extraction:**
|
|
157
|
-
- Link text becomes literal value for `property` predicates
|
|
158
|
-
- URL becomes `href` attribute and potential `about` subject
|
|
159
|
-
- Alt text used for image carriers
|
|
160
|
-
|
|
161
|
-
4. **RDFa Attribute Mapping:**
|
|
162
|
-
| MD-LD Construct | Subject | RDFa Output |
|
|
163
|
-
|-----------------|---------|-------------|
|
|
164
|
-
| `[text](url) {property}` | Current subject | `property="ex:property"` on `<a>` |
|
|
165
|
-
| `[text](url) {?object}` | Current subject | `rel="ex:object"` on `<a>` |
|
|
166
|
-
| `[text](url) {=subject}` | URL | `about="url"` on `<a>` |
|
|
167
|
-
| `[text](url) {=subject .Type}` | URL | `about="url" typeof="ex:Type"` on `<a>` |
|
|
168
|
-
|
|
169
|
-
### 3.2 RDFa Attribute Generation
|
|
170
|
-
|
|
171
|
-
#### Subject Resolution
|
|
172
|
-
|
|
173
|
-
```javascript
|
|
174
|
-
function buildRDFaAttrsFromBlock(block, ctx) {
|
|
175
|
-
const attrs = [];
|
|
176
|
-
|
|
177
|
-
// Subject (about)
|
|
178
|
-
if (block.subject && isValidSubject(block.subject)) {
|
|
179
|
-
const expanded = expandIRI(block.subject, ctx);
|
|
180
|
-
const shortened = shortenIRI(expanded, ctx);
|
|
181
|
-
attrs.push(`about="${escapeHtml(shortened)}"`);
|
|
182
|
-
}
|
|
183
|
-
|
|
184
|
-
// Types (typeof)
|
|
185
|
-
if (block.types?.length > 0) {
|
|
186
|
-
const types = block.types.map(t =>
|
|
187
|
-
shortenIRI(expandIRI(typeof t === 'string' ? t : t.iri, ctx), ctx)
|
|
188
|
-
).join(' ');
|
|
189
|
-
attrs.push(`typeof="${escapeHtml(types)}"`);
|
|
190
|
-
}
|
|
191
|
-
|
|
192
|
-
// Predicates (property/rel/rev)
|
|
193
|
-
if (block.predicates?.length > 0) {
|
|
194
|
-
const { literalProps, objectProps, reverseProps } = categorizePredicates(block.predicates);
|
|
195
|
-
|
|
196
|
-
if (literalProps.length > 0) attrs.push(`property="${literalProps.join(' ')}"`);
|
|
197
|
-
if (objectProps.length > 0) attrs.push(`rel="${objectProps.join(' ')}"`);
|
|
198
|
-
if (reverseProps.length > 0) attrs.push(`rev="${reverseProps.join(' ')}"`);
|
|
199
|
-
}
|
|
200
|
-
|
|
201
|
-
return attrs.length > 0 ? ` ${attrs.join(' ')}` : '';
|
|
202
|
-
}
|
|
203
|
-
```
|
|
204
|
-
|
|
205
|
-
#### Predicate Categorization
|
|
206
|
-
|
|
207
|
-
| Predicate Form | RDFa Attribute | Direction | Example |
|
|
208
|
-
|----------------|----------------|-----------|---------|
|
|
209
|
-
| `p` (literal) | `property` | Subject → Literal | `property="rdfs:label"` |
|
|
210
|
-
| `?p` (object) | `rel` | Subject → Object | `rel="schema:knows"` |
|
|
211
|
-
| `!p` (reverse) | `rev` | Object → Subject | `rev="schema:member"` |
|
|
212
|
-
|
|
213
|
-
### 3.3 Content Extraction Strategy
|
|
214
|
-
|
|
215
|
-
#### Source Text Preservation
|
|
216
|
-
|
|
217
|
-
```javascript
|
|
218
|
-
function renderBlockContent(block, state) {
|
|
219
|
-
if (block.range && state.sourceText) {
|
|
220
|
-
let text = state.sourceText.substring(block.range.start, block.range.end);
|
|
221
|
-
|
|
222
|
-
// Remove MD-LD annotations, preserve content
|
|
223
|
-
if (block.attrsRange) {
|
|
224
|
-
const beforeAttrs = text.substring(0, block.attrsRange.start - block.range.start);
|
|
225
|
-
const afterAttrs = text.substring(block.attrsRange.end - block.range.start);
|
|
226
|
-
text = beforeAttrs + afterAttrs;
|
|
227
|
-
}
|
|
228
|
-
|
|
229
|
-
// Type-specific content cleaning
|
|
230
|
-
text = cleanContentByType(text, block.carrierType);
|
|
231
|
-
|
|
232
|
-
state.output.push(escapeHtml(text.trim()));
|
|
233
|
-
}
|
|
234
|
-
}
|
|
235
|
-
```
|
|
236
|
-
|
|
237
|
-
#### Content Cleaning Rules
|
|
238
|
-
|
|
239
|
-
| Carrier Type | Cleaning Strategy | Input → Output |
|
|
240
|
-
|--------------|------------------|----------------|
|
|
241
|
-
| **heading** | Remove leading `#` markers and trim | `# Title {props}` → `Title` |
|
|
242
|
-
| **paragraph** | Remove annotations only, preserve text | `Text {prop}` → `Text` |
|
|
243
|
-
| **list** | Remove list markers (`-`, `*`, `+`, `1.`) | `- Item {prop}` → `Item` |
|
|
244
|
-
| **blockquote** | Remove leading `>` marker | `> Quote {prop}` → `Quote` |
|
|
245
|
-
| **code** | Preserve code content exactly | ```code {prop}```` → `code` |
|
|
246
|
-
| **emphasis** | Remove emphasis markers | `*text* {prop}` → `text` |
|
|
247
|
-
| **strong** | Remove strong markers | `**text** {prop}` → `text` |
|
|
248
|
-
| **code span** | Remove backticks | `` `code` {prop}` `` → `code` |
|
|
249
|
-
| **link** | Preserve link text, remove URL from content | `[Text](url) {prop}` → `Text` |
|
|
250
|
-
| **image** | Use alt text, remove URL from content | ` {prop}` → `Alt` |
|
|
251
|
-
| **angle link** | Use URL as both href and content | `<url> {prop}` → `url` |
|
|
252
|
-
|
|
253
|
-
#### Comprehensive Carrier Reference
|
|
254
|
-
|
|
255
|
-
**Block-Level Carriers (structural elements):**
|
|
256
|
-
|
|
257
|
-
1. **Headings** - `#` through `######` prefix
|
|
258
|
-
- Syntax: `# Heading Text {=ex:subject .Type property}`
|
|
259
|
-
- HTML: `<h1>` to `<h6>`
|
|
260
|
-
- Content: Text after `#` markers
|
|
261
|
-
|
|
262
|
-
2. **Paragraphs** - Text blocks with annotations
|
|
263
|
-
- Syntax: `Paragraph content {ex:property}`
|
|
264
|
-
- HTML: `<p>`
|
|
265
|
-
- Content: Full text minus annotations
|
|
266
|
-
|
|
267
|
-
3. **List Items** - Markdown list markers
|
|
268
|
-
- Syntax: `- Item {=ex:item .Type name}`
|
|
269
|
-
- HTML: `<ul><li>`
|
|
270
|
-
- Content: Text after list marker
|
|
271
|
-
|
|
272
|
-
4. **Blockquotes** - Lines starting with `>`
|
|
273
|
-
- Syntax: `> Quote text {ex:quote}`
|
|
274
|
-
- HTML: `<blockquote>`
|
|
275
|
-
- Content: Text after `>` marker
|
|
276
|
-
|
|
277
|
-
5. **Code Blocks** - Fenced code blocks
|
|
278
|
-
- Syntax: ````language {=ex:code .Type}````
|
|
279
|
-
- HTML: `<pre><code class="language-X">`
|
|
280
|
-
- Content: Entire code block content
|
|
281
|
-
|
|
282
|
-
6. **Standalone Subjects** - Subject declarations
|
|
283
|
-
- Syntax: `{=ex:subject .Type}` (on separate line)
|
|
284
|
-
- HTML: `<div>`
|
|
285
|
-
- Content: Empty (subject declaration only)
|
|
286
|
-
|
|
287
|
-
**Inline Carriers (within blocks):**
|
|
288
|
-
|
|
289
|
-
1. **Emphasis** - `*text*` or `_text_`
|
|
290
|
-
- Syntax: `*emphasized* {ex:property}`
|
|
291
|
-
- HTML: `<em>`
|
|
292
|
-
- Content: Text within emphasis markers
|
|
293
|
-
|
|
294
|
-
2. **Strong** - `**text**` or `__text__`
|
|
295
|
-
- Syntax: `**strong** {ex:property}`
|
|
296
|
-
- HTML: `<strong>`
|
|
297
|
-
- Content: Text within strong markers
|
|
298
|
-
|
|
299
|
-
3. **Code Spans** - Backtick-enclosed code
|
|
300
|
-
- Syntax: `` `code` {ex:property} ``
|
|
301
|
-
- HTML: `<code>`
|
|
302
|
-
- Content: Text within backticks
|
|
303
|
-
|
|
304
|
-
4. **Links** - `[text](url)` syntax
|
|
305
|
-
- Syntax: `[Link Text](https://example.com) {ex:property}`
|
|
306
|
-
- HTML: `<a href="https://example.com">`
|
|
307
|
-
- Content: Link text (between brackets)
|
|
308
|
-
- Subject Resolution: URL becomes subject unless explicit subject provided
|
|
309
|
-
|
|
310
|
-
5. **Images** - `` syntax
|
|
311
|
-
- Syntax: ` {ex:property}`
|
|
312
|
-
- HTML: `<img src="image.png" alt="Alt Text">`
|
|
313
|
-
- Content: Alt text (after `!`)
|
|
314
|
-
- Subject Resolution: Image URL becomes subject unless explicit subject
|
|
315
|
-
|
|
316
|
-
6. **Angle Links** - `<url>` syntax
|
|
317
|
-
- Syntax: `<https://example.com> {ex:property}`
|
|
318
|
-
- HTML: `<a href="https://example.com">`
|
|
319
|
-
- Content: URL itself
|
|
320
|
-
- Subject Resolution: URL becomes subject
|
|
321
|
-
|
|
322
|
-
**Carrier Detection Priority:**
|
|
323
|
-
|
|
324
|
-
1. **Block carriers** are detected first during tokenization
|
|
325
|
-
2. **Inline carriers** are extracted within block content
|
|
326
|
-
3. **Links and images** have special subject resolution rules
|
|
327
|
-
4. **Annotations** attach to the nearest valid carrier
|
|
328
|
-
5. **Invalid carriers** generate no RDF output (graceful failure)
|
|
329
|
-
|
|
330
|
-
---
|
|
331
|
-
|
|
332
|
-
## 4. List Rendering System
|
|
333
|
-
|
|
334
|
-
### 4.1 The Nested List Challenge
|
|
335
|
-
|
|
336
|
-
**The Core Problem:**
|
|
337
|
-
CommonMark nested lists require hierarchical HTML structure (`<ul><li><ul><li>...`) but streaming single-pass processing makes this challenging because:
|
|
338
|
-
|
|
339
|
-
1. **Forward Context Needed** - To know when to close `<ul>` tags, we need to see future lines
|
|
340
|
-
2. **Indentation Tracking** - Must maintain stack of nesting levels across the entire document
|
|
341
|
-
3. **RDFa Preservation** - Each list item needs its semantic attributes preserved
|
|
342
|
-
|
|
343
|
-
**Streaming-Compatible Solution:**
|
|
344
|
-
|
|
345
|
-
We can preserve visual nesting while maintaining single-pass rendering through **level tracking with deferred closing**:
|
|
346
|
-
|
|
347
|
-
### 4.2 Streaming List Processing Strategy
|
|
348
|
-
|
|
349
|
-
```javascript
|
|
350
|
-
function processListItemsStreaming(listBlocks, state) {
|
|
351
|
-
let html = '';
|
|
352
|
-
let currentLevel = 0;
|
|
353
|
-
let openTags = []; // Track open <ul> and <li> tags
|
|
354
|
-
|
|
355
|
-
// Process blocks in order (single pass)
|
|
356
|
-
for (const block of listBlocks) {
|
|
357
|
-
const indent = getIndentLevel(block, state.sourceText);
|
|
358
|
-
const targetLevel = Math.floor(indent / 2); // 2 spaces per level
|
|
359
|
-
|
|
360
|
-
// Close tags when going up the hierarchy
|
|
361
|
-
while (currentLevel > targetLevel) {
|
|
362
|
-
if (openTags.pop() === 'li') {
|
|
363
|
-
html += '</li>';
|
|
364
|
-
} else {
|
|
365
|
-
html += '</ul>';
|
|
366
|
-
}
|
|
367
|
-
currentLevel--;
|
|
368
|
-
}
|
|
369
|
-
|
|
370
|
-
// Open tags when going down the hierarchy
|
|
371
|
-
while (currentLevel < targetLevel) {
|
|
372
|
-
html += '<ul>';
|
|
373
|
-
openTags.push('ul');
|
|
374
|
-
currentLevel++;
|
|
375
|
-
}
|
|
376
|
-
|
|
377
|
-
// Close previous li if we're at same level
|
|
378
|
-
if (openTags[openTags.length - 1] === 'li') {
|
|
379
|
-
html += '</li>';
|
|
380
|
-
openTags.pop();
|
|
381
|
-
}
|
|
382
|
-
|
|
383
|
-
// Render current list item
|
|
384
|
-
const attrs = buildRDFaAttrsFromBlock(block, state.ctx);
|
|
385
|
-
const content = extractListContent(block, state.sourceText);
|
|
386
|
-
html += `<li${attrs}>${escapeHtml(content)}`;
|
|
387
|
-
openTags.push('li');
|
|
388
|
-
}
|
|
389
|
-
|
|
390
|
-
// Close all remaining tags
|
|
391
|
-
while (openTags.length > 0) {
|
|
392
|
-
const tag = openTags.pop();
|
|
393
|
-
html += `</${tag}>`;
|
|
394
|
-
}
|
|
395
|
-
|
|
396
|
-
return html;
|
|
397
|
-
}
|
|
398
|
-
```
|
|
399
|
-
|
|
400
|
-
### 4.3 Indentation-Based Level Detection
|
|
401
|
-
|
|
402
|
-
```javascript
|
|
403
|
-
function getIndentLevel(block, sourceText) {
|
|
404
|
-
if (!block.range || !sourceText) return 0;
|
|
405
|
-
|
|
406
|
-
const text = sourceText.substring(block.range.start, block.range.end);
|
|
407
|
-
const indentMatch = text.match(/^(\s*)/);
|
|
408
|
-
const indentSpaces = indentMatch ? indentMatch[1].length : 0;
|
|
409
|
-
|
|
410
|
-
// CommonMark: 4 spaces or 1 tab = one level
|
|
411
|
-
// We'll use 2 spaces for better readability (configurable)
|
|
412
|
-
return Math.floor(indentSpaces / 2);
|
|
413
|
-
}
|
|
414
|
-
```
|
|
415
|
-
|
|
416
|
-
### 4.4 Content Extraction with Nesting Preservation
|
|
417
|
-
|
|
418
|
-
```javascript
|
|
419
|
-
function extractListContent(block, sourceText) {
|
|
420
|
-
if (!block.range || !sourceText) return '';
|
|
421
|
-
|
|
422
|
-
let text = sourceText.substring(block.range.start, block.range.end);
|
|
423
|
-
|
|
424
|
-
// Remove list marker (-, *, +, or 1. 2. etc.)
|
|
425
|
-
text = text.replace(/^(\s*[-*+]|\s*\d+\.)\s+/, '');
|
|
426
|
-
|
|
427
|
-
// Remove MD-LD annotations
|
|
428
|
-
if (block.attrsRange) {
|
|
429
|
-
const beforeAttrs = text.substring(0, block.attrsRange.start - block.range.start);
|
|
430
|
-
const afterAttrs = text.substring(block.attrsRange.end - block.range.start);
|
|
431
|
-
text = beforeAttrs + afterAttrs;
|
|
432
|
-
}
|
|
433
|
-
|
|
434
|
-
return text.trim();
|
|
435
|
-
}
|
|
436
|
-
```
|
|
437
|
-
|
|
438
|
-
### 4.5 Complete List Rendering Pipeline
|
|
439
|
-
|
|
440
|
-
```javascript
|
|
441
|
-
function renderListsWithRDFa(listBlocks, state) {
|
|
442
|
-
// Group consecutive list blocks (maintains document structure)
|
|
443
|
-
const listGroups = groupConsecutiveListBlocks(listBlocks, state.sourceText);
|
|
444
|
-
|
|
445
|
-
let html = '';
|
|
446
|
-
|
|
447
|
-
for (const group of listGroups) {
|
|
448
|
-
// Extract list anchor text (paragraph before list)
|
|
449
|
-
const anchorText = extractListAnchorText(group.blocks[0], state.sourceText);
|
|
450
|
-
if (anchorText) {
|
|
451
|
-
html += `<p>${escapeHtml(anchorText)}</p>`;
|
|
452
|
-
}
|
|
453
|
-
|
|
454
|
-
// Process list items with streaming-compatible nesting
|
|
455
|
-
html += processListItemsStreaming(group.blocks, state);
|
|
456
|
-
}
|
|
457
|
-
|
|
458
|
-
return html;
|
|
459
|
-
}
|
|
460
|
-
|
|
461
|
-
function groupConsecutiveListBlocks(listBlocks, sourceText) {
|
|
462
|
-
const groups = [];
|
|
463
|
-
let currentGroup = null;
|
|
464
|
-
let lastPosition = -1;
|
|
465
|
-
|
|
466
|
-
for (const block of listBlocks) {
|
|
467
|
-
if (!block.range) continue;
|
|
468
|
-
|
|
469
|
-
// Check if this is consecutive with previous block
|
|
470
|
-
const isConsecutive = lastPosition >= 0 &&
|
|
471
|
-
(block.range.start - lastPosition) <= (sourceText.substring(lastPosition, block.range.start).match(/\n/g) || []).length * 2 + 10;
|
|
472
|
-
|
|
473
|
-
if (!isConsecutive || !currentGroup) {
|
|
474
|
-
if (currentGroup) groups.push(currentGroup);
|
|
475
|
-
currentGroup = { blocks: [block] };
|
|
476
|
-
} else {
|
|
477
|
-
currentGroup.blocks.push(block);
|
|
478
|
-
}
|
|
479
|
-
|
|
480
|
-
lastPosition = block.range.end;
|
|
481
|
-
}
|
|
482
|
-
|
|
483
|
-
if (currentGroup) groups.push(currentGroup);
|
|
484
|
-
return groups;
|
|
485
|
-
}
|
|
486
|
-
```
|
|
487
|
-
|
|
488
|
-
### 4.6 Streaming Complexity Analysis
|
|
489
|
-
|
|
490
|
-
| Operation | Complexity | Streaming Compatible |
|
|
491
|
-
|-----------|-------------|-------------------|
|
|
492
|
-
| **Indentation Detection** | O(1) per block | ✅ Yes |
|
|
493
|
-
| **Level Tracking** | O(1) per block | ✅ Yes |
|
|
494
|
-
| **Tag Stack Management** | O(1) per block | ✅ Yes |
|
|
495
|
-
| **Content Extraction** | O(1) per block | ✅ Yes |
|
|
496
|
-
| **Deferred Closing** | O(1) per block | ✅ Yes |
|
|
497
|
-
|
|
498
|
-
**Key Insight:** We never need to look ahead - we maintain a stack of open tags and close them when indentation decreases, which is detectable in the current line.
|
|
499
|
-
|
|
500
|
-
### 4.7 Example: Nested List Processing
|
|
501
|
-
|
|
502
|
-
**Input MD-LD:**
|
|
503
|
-
```md
|
|
504
|
-
Items {=ex:items .ex:Collection}
|
|
505
|
-
- Top Level 1 {=ex:item1 .ex:Item name}
|
|
506
|
-
- Top Level 2 {=ex:item2 .ex:Item name}
|
|
507
|
-
- Nested 1 {=ex:nested1 .ex:Item name ?hasPart}
|
|
508
|
-
- Nested 2 {=ex:nested2 .ex:Item name ?hasPart}
|
|
509
|
-
- Deep Nested {=ex:deep .ex:Item name ?hasPart}
|
|
510
|
-
- Top Level 3 {=ex:item3 .ex:Item name}
|
|
511
|
-
```
|
|
512
|
-
|
|
513
|
-
**Streaming Processing Steps:**
|
|
514
|
-
```javascript
|
|
515
|
-
// Block 1: "Top Level 1" (indent 0, level 0)
|
|
516
|
-
currentLevel = 0, targetLevel = 0
|
|
517
|
-
html += '<li about="ex:item1" typeof="ex:Item" property="rdfs:label">Top Level 1</li>'
|
|
518
|
-
|
|
519
|
-
// Block 2: "Top Level 2" (indent 0, level 0)
|
|
520
|
-
currentLevel = 0, targetLevel = 0
|
|
521
|
-
html += '</li><li about="ex:item2" typeof="ex:Item" property="rdfs:label">Top Level 2</li>'
|
|
522
|
-
|
|
523
|
-
// Block 3: "Nested 1" (indent 2, level 1)
|
|
524
|
-
currentLevel = 0, targetLevel = 1
|
|
525
|
-
html += '<ul><li about="ex:nested1" typeof="ex:Item" property="rdfs:label" rel="ex:hasPart">Nested 1</li>'
|
|
526
|
-
|
|
527
|
-
// Block 4: "Nested 2" (indent 2, level 1)
|
|
528
|
-
currentLevel = 1, targetLevel = 1
|
|
529
|
-
html += '</li><li about="ex:nested2" typeof="ex:Item" property="rdfs:label" rel="ex:hasPart">Nested 2</li>'
|
|
530
|
-
|
|
531
|
-
// Block 5: "Deep Nested" (indent 4, level 2)
|
|
532
|
-
currentLevel = 1, targetLevel = 2
|
|
533
|
-
html += '<ul><li about="ex:deep" typeof="ex:Item" property="rdfs:label" rel="ex:hasPart">Deep Nested</li>'
|
|
534
|
-
|
|
535
|
-
// Block 6: "Top Level 3" (indent 0, level 0)
|
|
536
|
-
currentLevel = 2, targetLevel = 0
|
|
537
|
-
html += '</li></ul></ul></li><li about="ex:item3" typeof="ex:Item" property="rdfs:label">Top Level 3</li>'
|
|
538
|
-
```
|
|
539
|
-
|
|
540
|
-
**Final HTML Output:**
|
|
541
|
-
```html
|
|
542
|
-
<p>Items</p>
|
|
543
|
-
<ul>
|
|
544
|
-
<li about="ex:item1" typeof="ex:Item" property="rdfs:label">Top Level 1</li>
|
|
545
|
-
<li about="ex:item2" typeof="ex:Item" property="rdfs:label">Top Level 2
|
|
546
|
-
<ul>
|
|
547
|
-
<li about="ex:nested1" typeof="ex:Item" property="rdfs:label" rel="ex:hasPart">Nested 1</li>
|
|
548
|
-
<li about="ex:nested2" typeof="ex:Item" property="rdfs:label" rel="ex:hasPart">Nested 2
|
|
549
|
-
<ul>
|
|
550
|
-
<li about="ex:deep" typeof="ex:Item" property="rdfs:label" rel="ex:hasPart">Deep Nested</li>
|
|
551
|
-
</ul>
|
|
552
|
-
</li>
|
|
553
|
-
</ul>
|
|
554
|
-
</li>
|
|
555
|
-
<li about="ex:item3" typeof="ex:Item" property="rdfs:label">Top Level 3</li>
|
|
556
|
-
</ul>
|
|
557
|
-
```
|
|
558
|
-
|
|
559
|
-
### 4.8 Advantages of This Approach
|
|
560
|
-
|
|
561
|
-
1. **True Single-Pass** - No look-ahead needed, stack-based closing
|
|
562
|
-
2. **Memory Efficient** - Only track current open tags, not entire document structure
|
|
563
|
-
3. **Semantic Preservation** - All RDFa attributes maintained correctly
|
|
564
|
-
4. **CommonMark Compliant** - Proper nesting structure preserved
|
|
565
|
-
5. **Streaming Ready** - Can process large lists incrementally
|
|
566
|
-
|
|
567
|
-
### 4.9 Edge Cases Handled
|
|
568
|
-
|
|
569
|
-
- **Mixed Indentation** - Tabs and spaces handled uniformly
|
|
570
|
-
- **Inconsistent Nesting** - Graceful handling of malformed lists
|
|
571
|
-
- **Empty List Items** - Proper `<li></li>` generation
|
|
572
|
-
- **Deep Nesting** - No limit on nesting depth (stack-based)
|
|
573
|
-
- **Interspersed Non-List** - List groups properly separated
|
|
574
|
-
|
|
575
|
-
This approach achieves the perfect balance: preserving CommonMark's visual nesting while maintaining the streaming single-pass constraint that's core to MD-LD's architecture.
|
|
576
|
-
|
|
577
|
-
### 4.10 Advanced List Processing
|
|
578
|
-
|
|
579
|
-
To achieve full CommonMark compliance, the renderer must handle sophisticated list behaviors while maintaining streaming compatibility.
|
|
580
|
-
|
|
581
|
-
#### 4.10.1 Tight vs Loose Lists
|
|
582
|
-
|
|
583
|
-
**CommonMark Rules:**
|
|
584
|
-
- **Tight List**: No blank lines between list items → `<p>` tags omitted
|
|
585
|
-
- **Loose List**: Blank lines between list items → `<p>` tags included
|
|
586
|
-
|
|
587
|
-
**Streaming Detection Strategy:**
|
|
588
|
-
```javascript
|
|
589
|
-
function detectListTightness(listBlocks, sourceText) {
|
|
590
|
-
let isTight = true;
|
|
591
|
-
let lastEnd = -1;
|
|
592
|
-
|
|
593
|
-
for (let i = 0; i < listBlocks.length; i++) {
|
|
594
|
-
const block = listBlocks[i];
|
|
595
|
-
if (!block.range) continue;
|
|
596
|
-
|
|
597
|
-
if (lastEnd >= 0) {
|
|
598
|
-
// Check for blank line between items
|
|
599
|
-
const between = sourceText.substring(lastEnd, block.range.start);
|
|
600
|
-
const blankLineCount = (between.match(/\n\s*\n/g) || []).length;
|
|
601
|
-
|
|
602
|
-
if (blankLineCount > 0) {
|
|
603
|
-
isTight = false;
|
|
604
|
-
break; // Once loose, always loose
|
|
605
|
-
}
|
|
606
|
-
}
|
|
607
|
-
|
|
608
|
-
lastEnd = block.range.end;
|
|
609
|
-
}
|
|
610
|
-
|
|
611
|
-
return isTight;
|
|
612
|
-
}
|
|
613
|
-
```
|
|
614
|
-
|
|
615
|
-
**Rendering Implementation:**
|
|
616
|
-
```javascript
|
|
617
|
-
function renderListItemContent(block, isTight, state) {
|
|
618
|
-
const content = extractListContent(block, state.sourceText);
|
|
619
|
-
const attrs = buildRDFaAttrsFromBlock(block, state.ctx);
|
|
620
|
-
|
|
621
|
-
if (isTight) {
|
|
622
|
-
// Tight: no paragraph wrapper
|
|
623
|
-
return `<li${attrs}>${escapeHtml(content)}</li>`;
|
|
624
|
-
} else {
|
|
625
|
-
// Loose: wrap in paragraph
|
|
626
|
-
return `<li${attrs}><p>${escapeHtml(content)}</p></li>`;
|
|
627
|
-
}
|
|
628
|
-
}
|
|
629
|
-
```
|
|
630
|
-
|
|
631
|
-
#### 4.10.2 List Interruption
|
|
632
|
-
|
|
633
|
-
**CommonMark Rule:** Lists can interrupt paragraphs without blank lines when:
|
|
634
|
-
1. List item starts at the same indentation level as paragraph text
|
|
635
|
-
2. List item marker is followed by required whitespace
|
|
636
|
-
|
|
637
|
-
**Streaming Detection:**
|
|
638
|
-
```javascript
|
|
639
|
-
function detectListInterruption(block, precedingBlock, sourceText) {
|
|
640
|
-
if (!precedingBlock || precedingBlock.type !== 'para') return false;
|
|
641
|
-
|
|
642
|
-
// Check if list item immediately follows paragraph
|
|
643
|
-
const between = sourceText.substring(precedingBlock.range.end, block.range.start);
|
|
644
|
-
const hasBlankLine = between.match(/\n\s*\n/);
|
|
645
|
-
|
|
646
|
-
if (hasBlankLine) return false; // Not an interruption
|
|
647
|
-
|
|
648
|
-
// Check indentation alignment
|
|
649
|
-
const paragraphIndent = getTextIndent(precedingBlock, sourceText);
|
|
650
|
-
const listIndent = getIndentLevel(block, sourceText);
|
|
651
|
-
|
|
652
|
-
return listIndent <= paragraphIndent + 4; // Within 4 spaces = interruption
|
|
653
|
-
}
|
|
654
|
-
```
|
|
655
|
-
|
|
656
|
-
**Rendering Strategy:**
|
|
657
|
-
```javascript
|
|
658
|
-
function renderInterruptedList(listBlocks, precedingBlock, state) {
|
|
659
|
-
let html = '';
|
|
660
|
-
|
|
661
|
-
// Handle paragraph continuation after list
|
|
662
|
-
if (precedingBlock && precedingBlock.type === 'para') {
|
|
663
|
-
// Render paragraph content up to interruption point
|
|
664
|
-
const interruptionPoint = findInterruptionPoint(precedingBlock, listBlocks[0], state.sourceText);
|
|
665
|
-
const beforeContent = state.sourceText.substring(precedingBlock.range.start, interruptionPoint);
|
|
666
|
-
|
|
667
|
-
html += `<p>${escapeHtml(beforeContent)}</p>`;
|
|
668
|
-
html += processListItemsStreaming(listBlocks, state);
|
|
669
|
-
|
|
670
|
-
// Check for paragraph continuation after list
|
|
671
|
-
const afterContent = extractParagraphAfterList(precedingBlock, listBlocks, state.sourceText);
|
|
672
|
-
if (afterContent) {
|
|
673
|
-
html += `<p>${escapeHtml(afterContent)}</p>`;
|
|
674
|
-
}
|
|
675
|
-
}
|
|
676
|
-
|
|
677
|
-
return html;
|
|
678
|
-
}
|
|
679
|
-
```
|
|
680
|
-
|
|
681
|
-
#### 4.10.3 Mixed List Markers
|
|
682
|
-
|
|
683
|
-
**CommonMark Rules:**
|
|
684
|
-
- Changing bullet types (-, +, *) starts new list
|
|
685
|
-
- Changing ordered delimiters (1., 1.) starts new list
|
|
686
|
-
- Same marker type continues current list
|
|
687
|
-
|
|
688
|
-
**Streaming Detection:**
|
|
689
|
-
```javascript
|
|
690
|
-
function getListMarker(block, sourceText) {
|
|
691
|
-
if (!block.range) return null;
|
|
692
|
-
|
|
693
|
-
const text = sourceText.substring(block.range.start, block.range.end);
|
|
694
|
-
const markerMatch = text.match(/^(\s*)([-*+]|\d+\[\.|\])\s+/);
|
|
695
|
-
|
|
696
|
-
if (!markerMatch) return null;
|
|
697
|
-
|
|
698
|
-
return {
|
|
699
|
-
type: markerMatch[2].startsWith('-') ? 'dash' :
|
|
700
|
-
markerMatch[2].startsWith('*') ? 'asterisk' :
|
|
701
|
-
markerMatch[2].startsWith('+') ? 'plus' : 'ordered',
|
|
702
|
-
marker: markerMatch[2],
|
|
703
|
-
indent: markerMatch[1].length
|
|
704
|
-
};
|
|
705
|
-
}
|
|
706
|
-
|
|
707
|
-
function shouldStartNewList(currentMarker, previousMarker) {
|
|
708
|
-
if (!previousMarker) return false;
|
|
709
|
-
|
|
710
|
-
// Different marker types = new list
|
|
711
|
-
if (currentMarker.type !== previousMarker.type) return true;
|
|
712
|
-
|
|
713
|
-
// Ordered markers with different delimiters = new list
|
|
714
|
-
if (currentMarker.type === 'ordered' &&
|
|
715
|
-
currentMarker.marker !== previousMarker.marker) return true;
|
|
716
|
-
|
|
717
|
-
return false;
|
|
718
|
-
}
|
|
719
|
-
```
|
|
720
|
-
|
|
721
|
-
**Grouping Strategy:**
|
|
722
|
-
```javascript
|
|
723
|
-
function groupByMarkerType(listBlocks, sourceText) {
|
|
724
|
-
const groups = [];
|
|
725
|
-
let currentGroup = null;
|
|
726
|
-
let lastMarker = null;
|
|
727
|
-
|
|
728
|
-
for (const block of listBlocks) {
|
|
729
|
-
const marker = getListMarker(block, sourceText);
|
|
730
|
-
|
|
731
|
-
if (!marker || shouldStartNewList(marker, lastMarker)) {
|
|
732
|
-
if (currentGroup) groups.push(currentGroup);
|
|
733
|
-
currentGroup = {
|
|
734
|
-
blocks: [block],
|
|
735
|
-
markerType: marker?.type || 'unknown',
|
|
736
|
-
marker: marker?.marker
|
|
737
|
-
};
|
|
738
|
-
} else {
|
|
739
|
-
currentGroup.blocks.push(block);
|
|
740
|
-
}
|
|
741
|
-
|
|
742
|
-
lastMarker = marker;
|
|
743
|
-
}
|
|
744
|
-
|
|
745
|
-
if (currentGroup) groups.push(currentGroup);
|
|
746
|
-
return groups;
|
|
747
|
-
}
|
|
748
|
-
```
|
|
749
|
-
|
|
750
|
-
#### 4.10.4 Lazy Continuation
|
|
751
|
-
|
|
752
|
-
**CommonMark Rule:** List items can span multiple lines with:
|
|
753
|
-
- At least one space indentation for continuation
|
|
754
|
-
- Content aligned with first non-whitespace character of first line
|
|
755
|
-
|
|
756
|
-
**Streaming Detection:**
|
|
757
|
-
```javascript
|
|
758
|
-
function detectLazyContinuation(listBlocks, sourceText) {
|
|
759
|
-
const continuationBlocks = [];
|
|
760
|
-
|
|
761
|
-
for (let i = 0; i < listBlocks.length; i++) {
|
|
762
|
-
const block = listBlocks[i];
|
|
763
|
-
const nextBlock = listBlocks[i + 1];
|
|
764
|
-
|
|
765
|
-
if (!nextBlock) break;
|
|
766
|
-
|
|
767
|
-
// Check if next block is a continuation
|
|
768
|
-
const currentIndent = getIndentLevel(block, sourceText);
|
|
769
|
-
const nextIndent = getIndentLevel(nextBlock, sourceText);
|
|
770
|
-
|
|
771
|
-
// Continuation: indented but not enough to be nested
|
|
772
|
-
if (nextIndent > currentIndent && nextIndent <= currentIndent + 3) {
|
|
773
|
-
continuationBlocks.push({
|
|
774
|
-
parent: block,
|
|
775
|
-
continuation: nextBlock,
|
|
776
|
-
level: currentIndent
|
|
777
|
-
});
|
|
778
|
-
}
|
|
779
|
-
}
|
|
780
|
-
|
|
781
|
-
return continuationBlocks;
|
|
782
|
-
}
|
|
783
|
-
```
|
|
784
|
-
|
|
785
|
-
**Rendering Implementation:**
|
|
786
|
-
```javascript
|
|
787
|
-
function renderListWithContinuations(listBlocks, state) {
|
|
788
|
-
const continuations = detectLazyContinuation(listBlocks, state.sourceText);
|
|
789
|
-
const processedBlocks = new Set();
|
|
790
|
-
|
|
791
|
-
let html = '';
|
|
792
|
-
|
|
793
|
-
for (const block of listBlocks) {
|
|
794
|
-
if (processedBlocks.has(block)) continue;
|
|
795
|
-
|
|
796
|
-
// Find all continuations for this block
|
|
797
|
-
const blockContinuations = continuations
|
|
798
|
-
.filter(c => c.parent === block)
|
|
799
|
-
.map(c => c.continuation);
|
|
800
|
-
|
|
801
|
-
// Combine content from main block and continuations
|
|
802
|
-
let combinedContent = extractListContent(block, state.sourceText);
|
|
803
|
-
for (const continuation of blockContinuations) {
|
|
804
|
-
combinedContent += ' ' + extractListContent(continuation, state.sourceText);
|
|
805
|
-
processedBlocks.add(continuation);
|
|
806
|
-
}
|
|
807
|
-
|
|
808
|
-
const attrs = buildRDFaAttrsFromBlock(block, state.ctx);
|
|
809
|
-
html += `<li${attrs}><p>${escapeHtml(combinedContent)}</p></li>`;
|
|
810
|
-
processedBlocks.add(block);
|
|
811
|
-
}
|
|
812
|
-
|
|
813
|
-
return html;
|
|
814
|
-
}
|
|
815
|
-
```
|
|
816
|
-
|
|
817
|
-
#### 4.10.5 Complete Advanced List Pipeline
|
|
818
|
-
|
|
819
|
-
```javascript
|
|
820
|
-
function renderAdvancedListsWithRDFa(listBlocks, state) {
|
|
821
|
-
// Step 1: Group by marker type
|
|
822
|
-
const markerGroups = groupByMarkerType(listBlocks, state.sourceText);
|
|
823
|
-
|
|
824
|
-
let html = '';
|
|
825
|
-
|
|
826
|
-
for (const group of markerGroups) {
|
|
827
|
-
// Step 2: Detect tight vs loose
|
|
828
|
-
const isTight = detectListTightness(group.blocks, state.sourceText);
|
|
829
|
-
|
|
830
|
-
// Step 3: Detect and handle continuations
|
|
831
|
-
const hasContinuations = detectLazyContinuation(group.blocks, state.sourceText).length > 0;
|
|
832
|
-
|
|
833
|
-
// Step 4: Render with appropriate strategy
|
|
834
|
-
if (hasContinuations) {
|
|
835
|
-
html += renderListWithContinuations(group.blocks, state);
|
|
836
|
-
} else {
|
|
837
|
-
html += processListItemsStreaming(group.blocks, state, isTight);
|
|
838
|
-
}
|
|
839
|
-
}
|
|
840
|
-
|
|
841
|
-
return html;
|
|
842
|
-
}
|
|
843
|
-
```
|
|
844
|
-
|
|
845
|
-
#### 4.10.6 Streaming Complexity Analysis
|
|
846
|
-
|
|
847
|
-
| Feature | Complexity | Streaming Compatible | Memory Impact |
|
|
848
|
-
|---------|-------------|-------------------|---------------|
|
|
849
|
-
| **Tight/Loose Detection** | O(n) | ✅ Yes | O(1) |
|
|
850
|
-
| **List Interruption** | O(1) per block | ✅ Yes | O(1) |
|
|
851
|
-
| **Mixed Markers** | O(1) per block | ✅ Yes | O(1) |
|
|
852
|
-
| **Lazy Continuation** | O(n) per group | ✅ Yes | O(k) where k = continuations |
|
|
853
|
-
| **Combined Pipeline** | O(n) total | ✅ Yes | O(n) minimal |
|
|
854
|
-
|
|
855
|
-
#### 4.10.7 Example: Advanced List Processing
|
|
856
|
-
|
|
857
|
-
**Input MD-LD:**
|
|
858
|
-
```md
|
|
859
|
-
Paragraph that gets interrupted by a list.
|
|
860
|
-
|
|
861
|
-
- First item {=ex:item1}
|
|
862
|
-
- Second item {=ex:item2}
|
|
863
|
-
with lazy continuation {ex:continuation}
|
|
864
|
-
|
|
865
|
-
* Different marker starts new list {=ex:other1}
|
|
866
|
-
* Another item {=ex:other2}
|
|
867
|
-
|
|
868
|
-
Back to paragraph content.
|
|
869
|
-
```
|
|
870
|
-
|
|
871
|
-
**Processing Steps:**
|
|
872
|
-
1. **Detect interruption** - List immediately follows paragraph
|
|
873
|
-
2. **Group by markers** - `-` items separate from `*` items
|
|
874
|
-
3. **Detect tightness** - No blank lines = tight list
|
|
875
|
-
4. **Detect continuations** - "with lazy continuation" spans lines
|
|
876
|
-
5. **Render with proper structure** - Maintain semantic attributes
|
|
877
|
-
|
|
878
|
-
**HTML Output:**
|
|
879
|
-
```html
|
|
880
|
-
<p>Paragraph that gets interrupted by a list.</p>
|
|
881
|
-
<ul>
|
|
882
|
-
<li about="ex:item1" property="rdfs:label">First item</li>
|
|
883
|
-
<li about="ex:item2" property="rdfs:label"><p>Second item with lazy continuation</p></li>
|
|
884
|
-
</ul>
|
|
885
|
-
<ul>
|
|
886
|
-
<li about="ex:other1" property="rdfs:label">Different marker starts new list</li>
|
|
887
|
-
<li about="ex:other2" property="rdfs:label">Another item</li>
|
|
888
|
-
</ul>
|
|
889
|
-
<p>Back to paragraph content.</p>
|
|
890
|
-
```
|
|
891
|
-
|
|
892
|
-
These advanced features ensure full CommonMark compliance while maintaining the streaming single-pass architecture that makes MD-LD efficient and predictable.
|
|
893
|
-
|
|
894
|
-
---
|
|
895
|
-
|
|
896
|
-
## 5. Context Management
|
|
897
|
-
|
|
898
|
-
### 5.1 Prefix Declaration Generation
|
|
899
|
-
|
|
900
|
-
```javascript
|
|
901
|
-
function generatePrefixDeclarations(ctx) {
|
|
902
|
-
const prefixes = [];
|
|
903
|
-
|
|
904
|
-
for (const [prefix, iri] of Object.entries(ctx)) {
|
|
905
|
-
if (prefix !== '@vocab') {
|
|
906
|
-
prefixes.push(`${prefix}: ${iri}`);
|
|
907
|
-
}
|
|
908
|
-
}
|
|
909
|
-
|
|
910
|
-
return prefixes.length > 0 ? ` prefix="${prefixes.join(' ')}"` : '';
|
|
911
|
-
}
|
|
912
|
-
```
|
|
913
|
-
|
|
914
|
-
### 5.2 Vocabulary Declaration
|
|
915
|
-
|
|
916
|
-
```javascript
|
|
917
|
-
function generateVocabDeclaration(ctx) {
|
|
918
|
-
return ctx['@vocab'] ? ` vocab="${ctx['@vocab']}"` : '';
|
|
919
|
-
}
|
|
920
|
-
```
|
|
921
|
-
|
|
922
|
-
### 5.3 RDFa Context Wrapper
|
|
923
|
-
|
|
924
|
-
```javascript
|
|
925
|
-
function wrapWithRDFaContext(html, ctx) {
|
|
926
|
-
const prefixDecl = generatePrefixDeclarations(ctx);
|
|
927
|
-
const vocabDecl = generateVocabDeclaration(ctx);
|
|
928
|
-
|
|
929
|
-
return `<div${prefixDecl}${vocabDecl}>${html}</div>`;
|
|
930
|
-
}
|
|
931
|
-
```
|
|
932
|
-
|
|
933
|
-
---
|
|
934
|
-
|
|
935
|
-
## 6. Interactive Features
|
|
936
|
-
|
|
937
|
-
### 6.1 Data Attributes for Agent Interaction
|
|
938
|
-
|
|
939
|
-
```javascript
|
|
940
|
-
function buildDataAttributes(block) {
|
|
941
|
-
const attrs = [];
|
|
942
|
-
|
|
943
|
-
// Block identification
|
|
944
|
-
if (block.id) attrs.push(`data-block-id="${block.id}"`);
|
|
945
|
-
|
|
946
|
-
// Source tracking
|
|
947
|
-
if (block.range) {
|
|
948
|
-
attrs.push(`data-range-start="${block.range.start}"`);
|
|
949
|
-
attrs.push(`data-range-end="${block.range.end}"`);
|
|
950
|
-
}
|
|
951
|
-
|
|
952
|
-
// Semantic metadata
|
|
953
|
-
if (block.subject) attrs.push(`data-subject="${block.subject}"`);
|
|
954
|
-
if (block.types?.length) attrs.push(`data-types="${block.types.join(',')}"`);
|
|
955
|
-
|
|
956
|
-
return attrs.length > 0 ? ` ${attrs.join(' ')}` : '';
|
|
957
|
-
}
|
|
958
|
-
```
|
|
959
|
-
|
|
960
|
-
### 6.2 Hover and Click Targets
|
|
961
|
-
|
|
962
|
-
```javascript
|
|
963
|
-
// Enhanced block rendering with interaction support
|
|
964
|
-
function renderInteractiveBlock(block, state) {
|
|
965
|
-
const rdfaAttrs = buildRDFaAttrsFromBlock(block, state.ctx);
|
|
966
|
-
const dataAttrs = buildDataAttributes(block);
|
|
967
|
-
|
|
968
|
-
state.output.push(`<${tag}${rdfaAttrs}${dataAttrs}>`);
|
|
969
|
-
renderBlockContent(block, state);
|
|
970
|
-
state.output.push(`</${tag}>`);
|
|
971
|
-
}
|
|
972
|
-
```
|
|
973
|
-
|
|
974
|
-
### 6.3 Provenance Preservation
|
|
975
|
-
|
|
976
|
-
```javascript
|
|
977
|
-
// Origin tracking in rendered output
|
|
978
|
-
function addOriginMetadata(block, state) {
|
|
979
|
-
if (block.id && state.origin.quadIndex) {
|
|
980
|
-
const relatedQuads = Array.from(state.origin.quadIndex.entries())
|
|
981
|
-
.filter(([key, entry]) => entry.blockId === block.id);
|
|
982
|
-
|
|
983
|
-
if (relatedQuads.length > 0) {
|
|
984
|
-
state.output.push(`<!-- Origin: ${block.id}, Quads: ${relatedQuads.length} -->`);
|
|
985
|
-
}
|
|
986
|
-
}
|
|
987
|
-
}
|
|
988
|
-
```
|
|
989
|
-
|
|
990
|
-
---
|
|
991
|
-
|
|
992
|
-
## 7. Performance Characteristics
|
|
993
|
-
|
|
994
|
-
### 7.1 Complexity Analysis
|
|
995
|
-
|
|
996
|
-
| Operation | Complexity | Description |
|
|
997
|
-
|-----------|-------------|-------------|
|
|
998
|
-
| **Parse Integration** | O(1) | Direct reuse of parser output |
|
|
999
|
-
| **Block Sorting** | O(n log n) | One-time sort by position |
|
|
1000
|
-
| **Block Rendering** | O(n) | Single pass through blocks |
|
|
1001
|
-
| **List Processing** | O(n) | Linear scan of list items |
|
|
1002
|
-
| **Context Generation** | O(p) | p = number of prefixes |
|
|
1003
|
-
|
|
1004
|
-
### 7.2 Memory Usage
|
|
1005
|
-
|
|
1006
|
-
| Component | Memory Pattern | Cleanup Strategy |
|
|
1007
|
-
|-----------|----------------|------------------|
|
|
1008
|
-
| **Render State** | Fixed overhead | Automatic GC |
|
|
1009
|
-
| **Block Array** | O(n) growth | Released after render |
|
|
1010
|
-
| **Output Buffer** | O(n) growth | Converted to string |
|
|
1011
|
-
| **Context Cache** | Reused from parser | No additional allocation |
|
|
1012
|
-
|
|
1013
|
-
### 7.3 Streaming Compatibility
|
|
1014
|
-
|
|
1015
|
-
```javascript
|
|
1016
|
-
// Future streaming interface design
|
|
1017
|
-
function renderStream(mdldStream, options) {
|
|
1018
|
-
return new TransformStream({
|
|
1019
|
-
transform(chunk, controller) {
|
|
1020
|
-
const parsed = parse(chunk.toString(), options);
|
|
1021
|
-
const rendered = renderBlocks(parsed.origin.blocks, buildState(parsed, options));
|
|
1022
|
-
controller.enqueue(wrapWithRDFaContext(rendered, parsed.context));
|
|
1023
|
-
}
|
|
1024
|
-
});
|
|
1025
|
-
}
|
|
1026
|
-
```
|
|
1027
|
-
|
|
1028
|
-
---
|
|
1029
|
-
|
|
1030
|
-
## 8. Error Handling
|
|
1031
|
-
|
|
1032
|
-
### 8.1 Graceful Degradation
|
|
1033
|
-
|
|
1034
|
-
```javascript
|
|
1035
|
-
function safeRenderBlock(block, state) {
|
|
1036
|
-
try {
|
|
1037
|
-
renderBlock(block, state);
|
|
1038
|
-
} catch (error) {
|
|
1039
|
-
// Fallback rendering
|
|
1040
|
-
state.output.push(`<div class="mdld-error">`);
|
|
1041
|
-
state.output.push(escapeHtml(state.sourceText.substring(
|
|
1042
|
-
block.range.start, block.range.end
|
|
1043
|
-
)));
|
|
1044
|
-
state.output.push(`</div>`);
|
|
1045
|
-
|
|
1046
|
-
// Log error for debugging
|
|
1047
|
-
console.warn('Render error:', error, block);
|
|
1048
|
-
}
|
|
1049
|
-
}
|
|
1050
|
-
```
|
|
1051
|
-
|
|
1052
|
-
### 8.2 Validation Strategy
|
|
1053
|
-
|
|
1054
|
-
```javascript
|
|
1055
|
-
function validateRenderInput(parsed) {
|
|
1056
|
-
const errors = [];
|
|
1057
|
-
|
|
1058
|
-
if (!parsed.quads) errors.push('Missing quads array');
|
|
1059
|
-
if (!parsed.origin) errors.push('Missing origin data');
|
|
1060
|
-
if (!parsed.context) errors.push('Missing context object');
|
|
1061
|
-
|
|
1062
|
-
return {
|
|
1063
|
-
valid: errors.length === 0,
|
|
1064
|
-
errors
|
|
1065
|
-
};
|
|
1066
|
-
}
|
|
1067
|
-
```
|
|
1068
|
-
|
|
1069
|
-
---
|
|
1070
|
-
|
|
1071
|
-
## 9. Output Specification
|
|
1072
|
-
|
|
1073
|
-
### 9.1 HTML Structure
|
|
1074
|
-
|
|
1075
|
-
```html
|
|
1076
|
-
<!DOCTYPE html>
|
|
1077
|
-
<html>
|
|
1078
|
-
<head>
|
|
1079
|
-
<title>MD-LD Rendered Document</title>
|
|
1080
|
-
</head>
|
|
1081
|
-
<body>
|
|
1082
|
-
<div prefix="schema: http://schema.org/ ex: http://example.org/"
|
|
1083
|
-
vocab="http://www.w3.org/2000/01/rdf-schema#">
|
|
1084
|
-
|
|
1085
|
-
<!-- Rendered content with RDFa markup -->
|
|
1086
|
-
<h1 about="ex:document" typeof="schema:Article" property="rdfs:label">
|
|
1087
|
-
Document Title
|
|
1088
|
-
</h1>
|
|
1089
|
-
|
|
1090
|
-
<p about="ex:document">
|
|
1091
|
-
Content with <span about="ex:entity" typeof="schema:Person"
|
|
1092
|
-
property="rdfs:label">linked entities</span>.
|
|
1093
|
-
</p>
|
|
1094
|
-
|
|
1095
|
-
<ul>
|
|
1096
|
-
<li about="ex:item1" typeof="schema:ListItem" property="rdfs:label">
|
|
1097
|
-
List Item 1
|
|
1098
|
-
</li>
|
|
1099
|
-
<li about="ex:item2" typeof="schema:ListItem" property="rdfs:label">
|
|
1100
|
-
List Item 2
|
|
1101
|
-
</li>
|
|
1102
|
-
</ul>
|
|
1103
|
-
|
|
1104
|
-
</div>
|
|
1105
|
-
</body>
|
|
1106
|
-
</html>
|
|
1107
|
-
```
|
|
1108
|
-
|
|
1109
|
-
### 9.2 RDFa Attribute Mapping
|
|
1110
|
-
|
|
1111
|
-
| MD-LD Construct | RDFa Output | Example |
|
|
1112
|
-
|-----------------|-------------|---------|
|
|
1113
|
-
| `{=ex:subject}` | `about="ex:subject"` | Subject declaration |
|
|
1114
|
-
| `{.Type}` | `typeof="ex:Type"` | Type assertion |
|
|
1115
|
-
| `{property}` | `property="ex:property"` | Literal property |
|
|
1116
|
-
| `{?object}` | `rel="ex:object"` | Object property |
|
|
1117
|
-
| `{!reverse}` | `rev="ex:reverse"` | Reverse property |
|
|
1118
|
-
|
|
1119
|
-
### 9.3 Return Value Structure
|
|
1120
|
-
|
|
1121
|
-
```javascript
|
|
1122
|
-
const renderResult = {
|
|
1123
|
-
html: '<div prefix="...">...</div>', // Complete HTML output
|
|
1124
|
-
context: { // Final resolved context
|
|
1125
|
-
'@vocab': 'http://www.w3.org/2000/01/rdf-schema#',
|
|
1126
|
-
'schema': 'http://schema.org/',
|
|
1127
|
-
'ex': 'http://example.org/'
|
|
1128
|
-
},
|
|
1129
|
-
metadata: {
|
|
1130
|
-
blockCount: 42, // Number of rendered blocks
|
|
1131
|
-
quadCount: 156, // Number of RDF triples
|
|
1132
|
-
renderTime: 1672531200000, // Render timestamp
|
|
1133
|
-
listGroups: 3, // Number of list groups
|
|
1134
|
-
interactiveBlocks: 28 // Blocks with data attributes
|
|
1135
|
-
},
|
|
1136
|
-
origin: parsed.origin, // Complete provenance data
|
|
1137
|
-
statements: parsed.statements // Elevated statements
|
|
1138
|
-
};
|
|
1139
|
-
```
|
|
1140
|
-
|
|
1141
|
-
---
|
|
1142
|
-
|
|
1143
|
-
## 10. Extensibility Points
|
|
1144
|
-
|
|
1145
|
-
### 10.1 Custom Block Renderers
|
|
1146
|
-
|
|
1147
|
-
```javascript
|
|
1148
|
-
const CUSTOM_RENDERERS = {
|
|
1149
|
-
'custom-block': (block, state) => {
|
|
1150
|
-
const attrs = buildRDFaAttrsFromBlock(block, state.ctx);
|
|
1151
|
-
state.output.push(`<section${attrs}>`);
|
|
1152
|
-
renderBlockContent(block, state);
|
|
1153
|
-
state.output.push(`</section>`);
|
|
1154
|
-
}
|
|
1155
|
-
};
|
|
1156
|
-
```
|
|
1157
|
-
|
|
1158
|
-
### 10.2 Attribute Transformers
|
|
1159
|
-
|
|
1160
|
-
```javascript
|
|
1161
|
-
const ATTR_TRANSFORMERS = {
|
|
1162
|
-
'custom-attr': (value, block, ctx) => {
|
|
1163
|
-
// Custom attribute transformation logic
|
|
1164
|
-
return transformValue(value, ctx);
|
|
1165
|
-
}
|
|
1166
|
-
};
|
|
1167
|
-
```
|
|
1168
|
-
|
|
1169
|
-
### 10.3 Content Processors
|
|
1170
|
-
|
|
1171
|
-
```javascript
|
|
1172
|
-
const CONTENT_PROCESSORS = {
|
|
1173
|
-
'custom-content': (text, block, state) => {
|
|
1174
|
-
// Custom content processing (e.g., markdown parsing)
|
|
1175
|
-
return processMarkdown(text);
|
|
1176
|
-
}
|
|
1177
|
-
};
|
|
1178
|
-
```
|
|
1179
|
-
|
|
1180
|
-
---
|
|
1181
|
-
|
|
1182
|
-
## 11. Browser Compatibility
|
|
1183
|
-
|
|
1184
|
-
### 11.1 Modern Browser Support
|
|
1185
|
-
|
|
1186
|
-
- **ES6+ Modules** — `import/export` syntax
|
|
1187
|
-
- **Map/Set** — Efficient data structures
|
|
1188
|
-
- **Template Literals** — String interpolation
|
|
1189
|
-
- **Arrow Functions** — Concise syntax
|
|
1190
|
-
- **Destructuring** — Object/array unpacking
|
|
1191
|
-
|
|
1192
|
-
### 11.2 CDN Usage
|
|
1193
|
-
|
|
1194
|
-
```html
|
|
1195
|
-
<!-- Direct browser usage -->
|
|
1196
|
-
<script type="module">
|
|
1197
|
-
import { render } from 'https://cdn.jsdelivr.net/npm/mdld-parse/render.js';
|
|
1198
|
-
|
|
1199
|
-
const mdld = '# Title {=ex:title .schema:Thing label}';
|
|
1200
|
-
const result = render(mdld);
|
|
1201
|
-
document.body.innerHTML = result.html;
|
|
1202
|
-
</script>
|
|
1203
|
-
```
|
|
1204
|
-
|
|
1205
|
-
---
|
|
1206
|
-
|
|
1207
|
-
## 12. Security Considerations
|
|
1208
|
-
|
|
1209
|
-
### 12.1 Input Sanitization
|
|
1210
|
-
|
|
1211
|
-
```javascript
|
|
1212
|
-
function sanitizeRenderInput(mdld) {
|
|
1213
|
-
// Remove potentially dangerous content
|
|
1214
|
-
return mdld
|
|
1215
|
-
.replace(/<script\b[^<]*(?:(?!<\/script>)<[^<]*)*<\/script>/gi, '')
|
|
1216
|
-
.replace(/javascript:/gi, '')
|
|
1217
|
-
.replace(/on\w+\s*=/gi, '');
|
|
1218
|
-
}
|
|
1219
|
-
```
|
|
1220
|
-
|
|
1221
|
-
### 12.2 Output Escaping
|
|
1222
|
-
|
|
1223
|
-
```javascript
|
|
1224
|
-
function escapeHtml(text) {
|
|
1225
|
-
const map = {
|
|
1226
|
-
'&': '&',
|
|
1227
|
-
'<': '<',
|
|
1228
|
-
'>': '>',
|
|
1229
|
-
'"': '"',
|
|
1230
|
-
"'": ''',
|
|
1231
|
-
'/': '/'
|
|
1232
|
-
};
|
|
1233
|
-
return String(text || '').replace(/[&<>"'/]/g, m => map[m]);
|
|
1234
|
-
}
|
|
1235
|
-
```
|
|
1236
|
-
|
|
1237
|
-
### 12.3 IRI Validation
|
|
1238
|
-
|
|
1239
|
-
```javascript
|
|
1240
|
-
function validateIRI(iri) {
|
|
1241
|
-
// Basic IRI validation
|
|
1242
|
-
return iri &&
|
|
1243
|
-
typeof iri === 'string' &&
|
|
1244
|
-
!iri.includes('javascript:') &&
|
|
1245
|
-
!iri.includes('data:') &&
|
|
1246
|
-
/^[a-zA-Z][a-zA-Z0-9+.-]*:/.test(iri);
|
|
1247
|
-
}
|
|
1248
|
-
```
|
|
1249
|
-
|
|
1250
|
-
---
|
|
1251
|
-
|
|
1252
|
-
## 13. Testing Strategy
|
|
1253
|
-
|
|
1254
|
-
### 13.1 Unit Test Coverage
|
|
1255
|
-
|
|
1256
|
-
```javascript
|
|
1257
|
-
describe('MD-LD Render', () => {
|
|
1258
|
-
test('renders heading with RDFa', () => {
|
|
1259
|
-
const mdld = '# Title {=ex:title .schema:Thing label}';
|
|
1260
|
-
const result = render(mdld);
|
|
1261
|
-
|
|
1262
|
-
expect(result.html).toContain('<h1 about="ex:title" typeof="schema:Thing" property="rdfs:label">');
|
|
1263
|
-
expect(result.html).toContain('Title');
|
|
1264
|
-
expect(result.html).toContain('</h1>');
|
|
1265
|
-
});
|
|
1266
|
-
|
|
1267
|
-
test('preserves list hierarchy', () => {
|
|
1268
|
-
const mdld = `- Item 1 {=ex:item1}\n - Subitem {=ex:sub}`;
|
|
1269
|
-
const result = render(mdld);
|
|
1270
|
-
|
|
1271
|
-
expect(result.html).toContain('<ul>');
|
|
1272
|
-
expect(result.html).toContain('<li about="ex:item1">');
|
|
1273
|
-
expect(result.html).toContain('<ul>');
|
|
1274
|
-
expect(result.html).toContain('<li about="ex:sub">');
|
|
1275
|
-
});
|
|
1276
|
-
});
|
|
1277
|
-
```
|
|
1278
|
-
|
|
1279
|
-
### 13.2 Integration Tests
|
|
1280
|
-
|
|
1281
|
-
```javascript
|
|
1282
|
-
test('round-trip preservation', () => {
|
|
1283
|
-
const mdld = '# Test {=tag:me@example.org,2026:test .prov:Entity label}';
|
|
1284
|
-
const parsed = parse({text: mdld});
|
|
1285
|
-
const rendered = render(mdld);
|
|
1286
|
-
|
|
1287
|
-
// Verify RDF semantics preserved
|
|
1288
|
-
expect(parsed.quads).toHaveLength(2); // type + label
|
|
1289
|
-
expect(rendered.html).toContain('about="ex:test"');
|
|
1290
|
-
expect(rendered.html).toContain('typeof="ex:Type"');
|
|
1291
|
-
expect(rendered.html).toContain('property="rdfs:label"');
|
|
1292
|
-
});
|
|
1293
|
-
```
|
|
1294
|
-
|
|
1295
|
-
### 13.3 Performance Tests
|
|
1296
|
-
|
|
1297
|
-
```javascript
|
|
1298
|
-
test('rendering performance', () => {
|
|
1299
|
-
const largeMdld = generateLargeDocument(10000); // 10K tokens
|
|
1300
|
-
const start = performance.now();
|
|
1301
|
-
|
|
1302
|
-
const result = render(largeMdld);
|
|
1303
|
-
|
|
1304
|
-
const duration = performance.now() - start;
|
|
1305
|
-
expect(duration).toBeLessThan(1000); // < 1 second
|
|
1306
|
-
expect(result.html).toBeDefined();
|
|
1307
|
-
});
|
|
1308
|
-
```
|
|
1309
|
-
|
|
1310
|
-
---
|
|
1311
|
-
|
|
1312
|
-
## 14. Conformance Requirements
|
|
1313
|
-
|
|
1314
|
-
### 14.1 Required Behaviors
|
|
1315
|
-
|
|
1316
|
-
A conformant MD-LD renderer MUST:
|
|
1317
|
-
|
|
1318
|
-
1. **Preserve All Semantics** — Every RDF triple must be represented in HTML+RDFa
|
|
1319
|
-
2. **Maintain Document Structure** — HTML structure must reflect Markdown hierarchy
|
|
1320
|
-
3. **Generate Valid RDFa** — All RDFa attributes must be syntactically correct
|
|
1321
|
-
4. **Handle All Carrier Types** — Support every MD-LD value carrier
|
|
1322
|
-
5. **Preserve Provenance** — Maintain complete origin tracking information
|
|
1323
|
-
6. **Support Interactive Features** — Enable agent interaction through data attributes
|
|
1324
|
-
|
|
1325
|
-
### 14.2 Optional Features
|
|
1326
|
-
|
|
1327
|
-
These features are RECOMMENDED but not required:
|
|
1328
|
-
|
|
1329
|
-
1. **Syntax Highlighting** — Enhanced code block rendering
|
|
1330
|
-
2. **Markdown Extensions** — Tables, footnotes, etc.
|
|
1331
|
-
3. **Custom Themes** — CSS class generation
|
|
1332
|
-
4. **Progressive Enhancement** — Graceful degradation without JavaScript
|
|
1333
|
-
5. **Server-Side Rendering** — Node.js compatibility
|
|
1334
|
-
|
|
1335
|
-
### 14.3 Validation Criteria
|
|
1336
|
-
|
|
1337
|
-
```javascript
|
|
1338
|
-
function validateConformance(renderResult, originalParsed) {
|
|
1339
|
-
const errors = [];
|
|
1340
|
-
|
|
1341
|
-
// Check semantic preservation
|
|
1342
|
-
if (renderResult.metadata.quadCount !== originalParsed.quads.length) {
|
|
1343
|
-
errors.push('Quad count mismatch');
|
|
1344
|
-
}
|
|
1345
|
-
|
|
1346
|
-
// Check RDFa validity
|
|
1347
|
-
if (!isValidRDFa(renderResult.html)) {
|
|
1348
|
-
errors.push('Invalid RDFa markup');
|
|
1349
|
-
}
|
|
1350
|
-
|
|
1351
|
-
// Check structure preservation
|
|
1352
|
-
if (!hasValidHTMLStructure(renderResult.html)) {
|
|
1353
|
-
errors.push('Invalid HTML structure');
|
|
1354
|
-
}
|
|
1355
|
-
|
|
1356
|
-
return {
|
|
1357
|
-
conformant: errors.length === 0,
|
|
1358
|
-
errors
|
|
1359
|
-
};
|
|
1360
|
-
}
|
|
1361
|
-
```
|
|
1362
|
-
|
|
1363
|
-
---
|
|
1364
|
-
|
|
1365
|
-
## 15. Implementation Guidelines
|
|
1366
|
-
|
|
1367
|
-
### 15.1 Performance Optimization
|
|
1368
|
-
|
|
1369
|
-
1. **Reuse Parser Output** — Leverage existing parsing work
|
|
1370
|
-
2. **Minimize String Operations** — Use efficient concatenation
|
|
1371
|
-
3. **Cache IRI Expansions** — Avoid repeated resolution
|
|
1372
|
-
4. **Batch Attribute Generation** — Group RDFa attribute creation
|
|
1373
|
-
5. **Optimize List Processing** — Single pass through list items
|
|
1374
|
-
|
|
1375
|
-
### 15.2 Code Organization
|
|
1376
|
-
|
|
1377
|
-
```javascript
|
|
1378
|
-
// Main render function
|
|
1379
|
-
export function render(mdld, options) { /* ... */ }
|
|
1380
|
-
|
|
1381
|
-
// Core rendering pipeline
|
|
1382
|
-
function buildRenderState(parsed, options, mdld) { /* ... */ }
|
|
1383
|
-
function renderBlocks(blocks, state) { /* ... */ }
|
|
1384
|
-
function renderBlock(block, state) { /* ... */ }
|
|
1385
|
-
|
|
1386
|
-
// Specialized renderers
|
|
1387
|
-
function renderListsWithRDFa(listBlocks, state) { /* ... */ }
|
|
1388
|
-
function renderInteractiveBlock(block, state) { /* ... */ }
|
|
1389
|
-
|
|
1390
|
-
// Utilities
|
|
1391
|
-
function buildRDFaAttrsFromBlock(block, ctx) { /* ... */ }
|
|
1392
|
-
function wrapWithRDFaContext(html, ctx) { /* ... */ }
|
|
1393
|
-
function escapeHtml(text) { /* ... */ }
|
|
1394
|
-
```
|
|
1395
|
-
|
|
1396
|
-
### 15.3 Development Workflow
|
|
1397
|
-
|
|
1398
|
-
1. **Parser Integration** — Start with parser output
|
|
1399
|
-
2. **Basic Rendering** — Implement core block types
|
|
1400
|
-
3. **RDFa Generation** — Add semantic attributes
|
|
1401
|
-
4. **List Processing** — Handle hierarchical lists
|
|
1402
|
-
5. **Interactive Features** — Add data attributes
|
|
1403
|
-
6. **Performance Optimization** — Profile and optimize
|
|
1404
|
-
7. **Testing** — Comprehensive test coverage
|
|
1405
|
-
8. **Documentation** — Maintain this specification
|
|
1406
|
-
|
|
1407
|
-
---
|
|
1408
|
-
|
|
1409
|
-
## 16. Future Enhancements
|
|
1410
|
-
|
|
1411
|
-
### 16.2 Component-Based Rendering
|
|
1412
|
-
|
|
1413
|
-
```javascript
|
|
1414
|
-
// Future: Custom render components
|
|
1415
|
-
const components = {
|
|
1416
|
-
'timeline': renderTimeline,
|
|
1417
|
-
'graph': renderGraph,
|
|
1418
|
-
'table': renderTable
|
|
1419
|
-
};
|
|
1420
|
-
|
|
1421
|
-
function renderWithComponents(mdld, options) {
|
|
1422
|
-
// Component-based rendering system
|
|
1423
|
-
}
|
|
1424
|
-
```
|
|
1425
|
-
|
|
1426
|
-
### 16.3 Enhanced Interactivity
|
|
1427
|
-
|
|
1428
|
-
```javascript
|
|
1429
|
-
// Future: Advanced agent features
|
|
1430
|
-
function addAgentFeatures(html, parsed) {
|
|
1431
|
-
// Hover tooltips, click-to-edit, drag-drop
|
|
1432
|
-
// Real-time collaboration features
|
|
1433
|
-
// Visual graph overlays
|
|
1434
|
-
}
|
|
1435
|
-
```
|
|
1436
|
-
|
|
1437
|
-
---
|
|
1438
|
-
|
|
1439
|
-
This specification provides a comprehensive foundation for implementing the MD-LD Render function that maintains the same engineering excellence as the parser while enabling powerful interactive knowledge graph authoring experiences in the browser.
|