mdld-parse 1.0.1 → 1.0.3
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 +172 -61
- package/dist/index.js +1 -1
- package/package.json +2 -2
package/README.md
CHANGED
|
@@ -6,7 +6,16 @@ Write semantic data in natural Markdown, parse to RDF quads, build deterministic
|
|
|
6
6
|
|
|
7
7
|
[](https://www.npmjs.com/package/mdld-parse)
|
|
8
8
|
|
|
9
|
-
[
|
|
9
|
+
[Homepage](https://mdld.js.org) | [Repository](https://github.com/davay42/mdld-parse)
|
|
10
|
+
|
|
11
|
+
|
|
12
|
+
## 📚 Documentation Hub
|
|
13
|
+
|
|
14
|
+
- **📋 [Specification](./spec/index.md)** — Formal specification and test suite
|
|
15
|
+
- **📖 [Documentation](./docs/index.md)** — Complete documentation with guides and references
|
|
16
|
+
- **🎯 [Examples](./examples/index.md)** — Real-world MD-LD examples and use cases
|
|
17
|
+
- **📚 [Grammar](./grammar/index.md)** — EBNF grammar specification
|
|
18
|
+
- **🧩 [Ontologies](./ontologies/index.md)** — W3C and related standard ontologies used in RDF
|
|
10
19
|
|
|
11
20
|
## 🎯 What is MD-LD?
|
|
12
21
|
|
|
@@ -25,16 +34,23 @@ Human text → Graph immediately
|
|
|
25
34
|
**Core value:** Author and maintain knowledge graphs as plain text with deterministic round-trip safety. No platforms, databases, or proprietary SaaS mediation required.
|
|
26
35
|
|
|
27
36
|
```markdown
|
|
28
|
-
[ex] <
|
|
37
|
+
[ex] <tag:alice@example.com,2026:>
|
|
38
|
+
|
|
39
|
+
# My Bookmarks {=ex:bookmarks .prov:Entity .Container label}
|
|
29
40
|
|
|
30
|
-
|
|
41
|
+
> This is my first MD-LD document - a Bookmarks Collection {comment}
|
|
31
42
|
|
|
32
|
-
[Alice] {
|
|
33
|
-
|
|
43
|
+
Created by [Alice] {+ex:alice ?ex:author .prov:Person label} at `2026-06-01T11:54:22.153Z` {prov:wasGeneratedAt ^^xsd:dateTime}.
|
|
44
|
+
|
|
45
|
+
## Main Sources
|
|
46
|
+
|
|
47
|
+
[MD-LD website](https://mdld.js.org/) {?member label}
|
|
48
|
+
[Temporal API](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal) {?member label}
|
|
34
49
|
```
|
|
35
50
|
|
|
36
51
|
**Generates RDF quads** that work with n3.js, rdflib, and any RDF/JS-compatible library.
|
|
37
52
|
|
|
53
|
+
|
|
38
54
|
## 🚀 Quick Start
|
|
39
55
|
|
|
40
56
|
```bash
|
|
@@ -74,6 +90,7 @@ Users cannot access the graph directly. Semantics are hidden. Data is locked in
|
|
|
74
90
|
MD-LD removes the intermediary. Writing becomes publishing. Publishing becomes graph construction.
|
|
75
91
|
|
|
76
92
|
**Key benefits:**
|
|
93
|
+
|
|
77
94
|
- **Graph sovereignty** — You own text, graph, provenance, execution, history
|
|
78
95
|
- **No central platform required** — Works offline, in browsers, on servers
|
|
79
96
|
- **Universal semantic substrate** — Agents can read, reason, write, execute, validate
|
|
@@ -87,47 +104,43 @@ MD-LD removes the intermediary. Writing becomes publishing. Publishing becomes g
|
|
|
87
104
|
```markdown
|
|
88
105
|
[alice] <tag:alice@example.com,2026:>
|
|
89
106
|
|
|
90
|
-
# Meeting Notes {=alice:meeting-2024-01-15 .alice:Meeting}
|
|
107
|
+
# Meeting Notes {=alice:meeting-2024-01-15 .alice:Meeting label}
|
|
91
108
|
|
|
92
109
|
Attendees:
|
|
93
|
-
|
|
94
|
-
|
|
110
|
+
**Alice** {+alice:alice ?alice:attendee label}
|
|
111
|
+
**Bob** {+alice:bob ?alice:attendee label}
|
|
95
112
|
|
|
96
113
|
Action items:
|
|
97
|
-
|
|
114
|
+
**Review proposal** {+alice:task-1 ?alice:actionItem label}
|
|
98
115
|
```
|
|
99
116
|
|
|
100
117
|
#### Developer Documentation
|
|
101
118
|
```markdown
|
|
102
|
-
|
|
119
|
+
[api] <tag:brian@example.org,2026:app/api/>
|
|
120
|
+
# Get User by ID {=api:/users/:id .api:Endpoint label}
|
|
103
121
|
|
|
104
|
-
[GET] {api:method}
|
|
105
|
-
[/users/:id] {api:path}
|
|
122
|
+
Method: [GET] {+api:methods/GET ?api:method}
|
|
123
|
+
Path: [/users/:id] {api:path}
|
|
124
|
+
Status: [OK] {api:status}
|
|
106
125
|
```
|
|
107
126
|
|
|
108
127
|
#### Academic Research
|
|
109
128
|
```markdown
|
|
110
|
-
|
|
129
|
+
[alice] <tag:alice@example.org,2026:>
|
|
130
|
+
# Semantic Web {=alice:research/paper-semantic-markdown .alice:ScholarlyArticle label}
|
|
131
|
+
Is part of [semantic research] {+alice:research/semantic !member}
|
|
111
132
|
|
|
112
|
-
[
|
|
113
|
-
[Alice Johnson] {=alice:alice-johnson ?alice:author}
|
|
114
|
-
[2024-01] {alice:datePublished ^^xsd:gYear}
|
|
133
|
+
Authored by [Alice Johnson] {+alice:alice-johnson ?alice:author} on [2026-08-12] {alice:datePublished ^^xsd:date}.
|
|
115
134
|
```
|
|
116
135
|
|
|
117
136
|
#### Content Management
|
|
118
137
|
```markdown
|
|
119
|
-
|
|
138
|
+
[blog] <tag:justin@example.org,2026:>
|
|
139
|
+
# Understanding MD-LD {=blog:post-mdld .blog:Post label}
|
|
120
140
|
|
|
121
|
-
[MD-LD] {blog:emphasized
|
|
141
|
+
[MD-LD] {blog:emphasized} allows you to embed RDF directly in Markdown.
|
|
122
142
|
```
|
|
123
143
|
|
|
124
|
-
## 📚 Documentation Hub
|
|
125
|
-
|
|
126
|
-
- **📖 [Documentation](./docs/index.md)** — Complete documentation with guides and references
|
|
127
|
-
- **🎯 [Examples](./examples/index.md)** — Real-world MD-LD examples and use cases
|
|
128
|
-
- **📋 [Specification](./spec/index.md)** — Formal specification and test suite
|
|
129
|
-
- **🔄 [Diff Generation](./docs/diff.md)** — Automatic diff document generation for CRDT workflows
|
|
130
|
-
|
|
131
144
|
## ✨ Core Features
|
|
132
145
|
|
|
133
146
|
- **🔗 Prefix folding** — Build hierarchical namespaces with CURIE-based IRI authoring
|
|
@@ -144,40 +157,92 @@ Action items:
|
|
|
144
157
|
- **🏷️ Primary metadata quartet** — Subject, type, label, comment for document identity
|
|
145
158
|
- **🔄 Round-trip safety** — Deterministic parse ↔ generate cycles
|
|
146
159
|
|
|
160
|
+
**Bundle size:** 86KB unminified, 20KB gzipped
|
|
161
|
+
|
|
147
162
|
## 📦 Installation
|
|
148
163
|
|
|
149
164
|
### Node.js
|
|
150
165
|
|
|
151
166
|
```bash
|
|
152
167
|
pnpm install mdld-parse
|
|
168
|
+
node -e "
|
|
169
|
+
import { parse } from 'mdld-parse';
|
|
170
|
+
console.log(parse({ text: '# Test {=tag:test@example.org,2026:index .prov:Entity label}' }));
|
|
171
|
+
"
|
|
153
172
|
```
|
|
154
173
|
|
|
155
|
-
|
|
156
|
-
import { parse, generate, merge } from 'mdld-parse';
|
|
157
|
-
|
|
158
|
-
const mdld = `[ex] <http://example.org/>
|
|
159
|
-
|
|
160
|
-
# Document {=ex:doc .Article label}
|
|
161
|
-
|
|
162
|
-
[Alice] {=ex:alice ?ex:author .prov:Person ex:firstName label}
|
|
163
|
-
[Smith] {ex:lastName}`;
|
|
164
|
-
|
|
165
|
-
const result = parse({ text: mdld });
|
|
166
|
-
console.log(result.quads); // RDF/JS quads
|
|
167
|
-
console.log(result.primary); // { subject, type, label, comment }
|
|
168
|
-
console.log(result.statements); // Elevated statements
|
|
169
|
-
```
|
|
170
|
-
|
|
171
|
-
### Browser (ES Modules)
|
|
174
|
+
### Browser ESM (importmap)
|
|
172
175
|
|
|
173
176
|
```html
|
|
177
|
+
<script type="importmap">
|
|
178
|
+
{
|
|
179
|
+
"imports": {
|
|
180
|
+
"mdld-parse": "https://cdn.jsdelivr.net/npm/mdld-parse/+esm",
|
|
181
|
+
}
|
|
182
|
+
}
|
|
183
|
+
</script>
|
|
174
184
|
<script type="module">
|
|
175
|
-
import { parse } from '
|
|
176
|
-
const result = parse('[ex] <
|
|
185
|
+
import { parse } from 'mdld-parse';
|
|
186
|
+
const result = parse('[ex] <tag:my@example.com,2026:test/>\n\n# Hello {=ex:init .prov:Activity label}');
|
|
177
187
|
</script>
|
|
178
188
|
```
|
|
179
189
|
|
|
180
|
-
|
|
190
|
+
### Example use in browser console
|
|
191
|
+
|
|
192
|
+
You can copy and paste this code into your browser console to see the list of tasks as an easy to render JSON object.
|
|
193
|
+
|
|
194
|
+
```javascript
|
|
195
|
+
const mdld = await import('https://cdn.jsdelivr.net/npm/mdld-parse/+esm')
|
|
196
|
+
|
|
197
|
+
const text = `[my] <tag:alice@example.org:>
|
|
198
|
+
|
|
199
|
+
# Tasks {=my:tasks .prov:Collection label}
|
|
200
|
+
|
|
201
|
+
## Task 1 {=my:tasks/1 .prov:Activity label}
|
|
202
|
+
One of my [urgent] {my:tasks/status} [tasks] {+my:tasks !prov:hadMember}
|
|
203
|
+
> Explore deeper the concept of a triple in RDF {comment}
|
|
204
|
+
|
|
205
|
+
## Task 2 {=my:tasks/2 .prov:Activity label}
|
|
206
|
+
One of my [tasks] {+my:tasks !prov:hadMember}
|
|
207
|
+
> Start building knowledge graphs {comment}
|
|
208
|
+
`;
|
|
209
|
+
|
|
210
|
+
const result = parse({ text });
|
|
211
|
+
|
|
212
|
+
function extractByType (quads, type) {
|
|
213
|
+
return Object.values(
|
|
214
|
+
quads.reduce((acc, q) => {
|
|
215
|
+
const s = q.subject.value;
|
|
216
|
+
const key = q.predicate.value.split(/[#/]/).pop();
|
|
217
|
+
|
|
218
|
+
(acc[s] ??= { iri: s })[key] = q.object.value;
|
|
219
|
+
|
|
220
|
+
return acc;
|
|
221
|
+
}, {})
|
|
222
|
+
)
|
|
223
|
+
.filter(x => x.type === type)
|
|
224
|
+
.map(({ type, ...x }) => x);
|
|
225
|
+
}
|
|
226
|
+
|
|
227
|
+
const tasks = extractByType(result.quads,"http://www.w3.org/ns/prov#Activity")
|
|
228
|
+
|
|
229
|
+
console.log(tasks);
|
|
230
|
+
/*
|
|
231
|
+
[
|
|
232
|
+
{
|
|
233
|
+
"iri": "tag:alice@example.org:tasks/1",
|
|
234
|
+
"label": "Task 1",
|
|
235
|
+
"status": "urgent",
|
|
236
|
+
"comment": "Explore deeper the concept of a triple in RDF"
|
|
237
|
+
},
|
|
238
|
+
{
|
|
239
|
+
"iri": "tag:alice@example.org:tasks/2",
|
|
240
|
+
"label": "Task 2",
|
|
241
|
+
"comment": "Start building knowledge graphs"
|
|
242
|
+
}
|
|
243
|
+
]
|
|
244
|
+
*/
|
|
245
|
+
```
|
|
181
246
|
|
|
182
247
|
## 🧠 Semantic Model
|
|
183
248
|
|
|
@@ -200,20 +265,29 @@ Each predicate form determines the graph edge:
|
|
|
200
265
|
## 🎨 Syntax Quick Reference
|
|
201
266
|
|
|
202
267
|
### Subject Declaration
|
|
268
|
+
|
|
203
269
|
Set current subject (emits no quads):
|
|
270
|
+
|
|
204
271
|
```markdown
|
|
272
|
+
[ex] <tag:nasa@example.org,2026:>
|
|
205
273
|
## Apollo 11 {=ex:apollo11}
|
|
206
274
|
```
|
|
207
275
|
|
|
208
276
|
### Type Declaration
|
|
277
|
+
|
|
209
278
|
Emit `rdf:type` triple:
|
|
279
|
+
|
|
210
280
|
```markdown
|
|
211
|
-
|
|
281
|
+
[ex] <tag:nasa@example.org,2026:>
|
|
282
|
+
## Apollo 11 {=ex:apollo11 .ex:SpaceMission .prov:Entity}
|
|
212
283
|
```
|
|
213
284
|
|
|
214
285
|
### Literal Properties
|
|
286
|
+
|
|
215
287
|
Inline value carriers emit literal properties:
|
|
288
|
+
|
|
216
289
|
```markdown
|
|
290
|
+
[ex] <tag:nasa@example.org,2026:>
|
|
217
291
|
# Mission {=ex:apollo11}
|
|
218
292
|
[Neil Armstrong] {ex:commander}
|
|
219
293
|
[1969] {ex:year ^^xsd:gYear}
|
|
@@ -221,32 +295,53 @@ Inline value carriers emit literal properties:
|
|
|
221
295
|
```
|
|
222
296
|
|
|
223
297
|
### Object Properties
|
|
298
|
+
|
|
224
299
|
Links create relationships (use `?` prefix):
|
|
300
|
+
|
|
225
301
|
```markdown
|
|
302
|
+
[ex] <tag:nasa@example.org,2026:>
|
|
226
303
|
# Mission {=ex:apollo11}
|
|
227
304
|
[NASA] {=ex:nasa ?ex:organizer}
|
|
228
305
|
```
|
|
229
306
|
|
|
230
307
|
### Resource Declaration
|
|
308
|
+
|
|
231
309
|
Declare resources inline with `{+iri}`:
|
|
310
|
+
|
|
232
311
|
```markdown
|
|
312
|
+
[ex] <tag:nasa@example.org,2026:>
|
|
233
313
|
# Mission {=ex:apollo11}
|
|
234
314
|
[Neil Armstrong] {+ex:armstrong ?ex:commander .Person}
|
|
235
315
|
```
|
|
236
316
|
|
|
237
317
|
### Diff Authoring (Polarity)
|
|
318
|
+
|
|
238
319
|
Use `+` and `-` for retractions:
|
|
320
|
+
|
|
321
|
+
```markdown
|
|
322
|
+
[ex] <tag:carol@example.org,2026:>
|
|
323
|
+
|
|
324
|
+
New student [Alice] {=ex:new-student .prov:Person ex:name} is our [class] {+ex:my-class !member}. I think she might know [Bob] {+ex:bob ?ex:knows}.
|
|
325
|
+
|
|
326
|
+
**Correction:** [Her] {=ex:new-student} name is not [Alice] {-ex:name}, it's [Ellie] {ex:name}.
|
|
327
|
+
|
|
328
|
+
**Correction:** I asked her directly - no, she doesn't know [him] {+ex:bob -?ex:knows}.
|
|
329
|
+
|
|
330
|
+
**IRI replacement:** Let's create a proper [Class] {=ex:my-class} record for [Ellie] {+ex:Ellie .prov:Person ex:name label ?member} instead of temporary [Ellie] {+ex:new-student -.prov:Person -ex:name -?member} record created earlier.
|
|
331
|
+
```
|
|
332
|
+
|
|
333
|
+
After `generate(parse({text}))` would look like this:
|
|
239
334
|
```markdown
|
|
240
|
-
|
|
241
|
-
|
|
242
|
-
|
|
243
|
-
[
|
|
244
|
-
|
|
245
|
-
#
|
|
246
|
-
[
|
|
247
|
-
[Alice] {-ex:friend}
|
|
335
|
+
[ex] <tag:carol@example.org,2026:>
|
|
336
|
+
|
|
337
|
+
# Ellie {=ex:Ellie .prov:Person label}
|
|
338
|
+
[Ellie] {ex:name}
|
|
339
|
+
|
|
340
|
+
# my-class {=ex:my-class}
|
|
341
|
+
[ex:Ellie] {+ex:Ellie ?member}
|
|
248
342
|
```
|
|
249
343
|
|
|
344
|
+
|
|
250
345
|
## 🔧 API Reference
|
|
251
346
|
|
|
252
347
|
### `parse({ text, context, dataFactory, graph })`
|
|
@@ -372,7 +467,7 @@ import {
|
|
|
372
467
|
## 🏗️ Architecture
|
|
373
468
|
|
|
374
469
|
### Design Principles
|
|
375
|
-
- **Zero dependencies** — Pure JavaScript,
|
|
470
|
+
- **Zero dependencies** — Pure JavaScript, 85KB unminified (20KB gzipped)
|
|
376
471
|
- **Streaming-first** — Single-pass parsing, O(n) complexity
|
|
377
472
|
- **Character-based tokenization** — 20-28% faster than regex-based approaches
|
|
378
473
|
- **Standards-compliant** — RDF/JS data model, W3C CURIE 1.0 syntax
|
|
@@ -428,10 +523,26 @@ Comprehensive test suite covering:
|
|
|
428
523
|
- Round-trip parse/generate cycles
|
|
429
524
|
- Origin tracking and provenance
|
|
430
525
|
|
|
431
|
-
##
|
|
526
|
+
## Governance
|
|
527
|
+
|
|
528
|
+
MD-LD is a craft project. Its coherence comes from a single evolving understanding of how semantic text should work — not from consensus, but from sustained attention to the same problem over time.
|
|
529
|
+
|
|
530
|
+
This means:
|
|
531
|
+
|
|
532
|
+
- Decisions are made by the steward, informed by discussion and use
|
|
533
|
+
- The project prioritizes conceptual integrity over inclusiveness
|
|
534
|
+
- Contributions that align with the model are welcomed and incorporated
|
|
535
|
+
- Contributions that expand scope without deepening coherence are respectfully declined
|
|
536
|
+
- The spec will not grow features to attract users — it will grow depth to serve understanding
|
|
537
|
+
|
|
538
|
+
## Licensing
|
|
539
|
+
|
|
540
|
+
MD-LD is published as copyrighted source material. No open-source license applies.
|
|
541
|
+
|
|
542
|
+
Governance and licensing are determined by the author as the project evolves.
|
|
543
|
+
|
|
544
|
+
Individuals and small groups are welcome to study, use, and build with MD-LD.
|
|
545
|
+
|
|
546
|
+
Organizations that need a formal license grant are invited to contact the author.
|
|
432
547
|
|
|
433
|
-
|
|
434
|
-
- **[Specification](./spec/index.md)** — Formal specification
|
|
435
|
-
- **[Examples](./examples/index.md)** — Real-world examples
|
|
436
|
-
- **[Grammar](./grammar/mdld.ebnf)** — EBNF grammar specification
|
|
437
|
-
- **[VS Code Extension](https://marketplace.visualstudio.com/)** — Syntax highlighting (coming soon)
|
|
548
|
+
All rights remain reserved.
|
package/dist/index.js
CHANGED
|
@@ -972,7 +972,7 @@ function generateLiteralText(quad, context) {
|
|
|
972
972
|
var generateObjectText = (quad, context, labelLookup = null, filteredGroups = null, renderedQuads = null, compactInline = true, compactStats = null) => {
|
|
973
973
|
const objShort = shortenIRI(quad.object.value, context);
|
|
974
974
|
const predShort = shortenIRI(quad.predicate.value, context);
|
|
975
|
-
const displayText = labelLookup && labelLookup.has(quad.object.value) ? labelLookup.get(quad.object.value) : objShort;
|
|
975
|
+
const displayText = labelLookup && labelLookup.has(quad.object.value) ? labelLookup.get(quad.object.value).value : objShort;
|
|
976
976
|
let inlineAnnotation = "";
|
|
977
977
|
if (compactInline && filteredGroups && labelLookup && renderedQuads) {
|
|
978
978
|
const filtered = filteredGroups.get(quad.object.value);
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "mdld-parse",
|
|
3
|
-
"version": "1.0.
|
|
3
|
+
"version": "1.0.3",
|
|
4
4
|
"description": "A standards-compliant parser for **MD-LD (Markdown-Linked Data)** — a human-friendly RDF authoring format that extends Markdown with semantic annotations.",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"packageManager": "pnpm@10.33.4+sha512.1c67b3b359b2d408119ba1ed289f34b8fc3c6873412bec6fd264fbdc82489e510fcbecb9ce9d22dae7f3b76269d8441046014bdca53b9979cd7a561ad631b800",
|
|
@@ -14,7 +14,7 @@
|
|
|
14
14
|
"scripts": {
|
|
15
15
|
"test": "node tests/index.js",
|
|
16
16
|
"dev": "vite dev",
|
|
17
|
-
"build": "vite build && vite build --config vite.config.lib.js && cp -r docs/ dist/docs/ && cp -r examples/ dist/examples/ && cp -r grammar/ dist/grammar/ && cp -r ontologies/ dist/ontologies/ && cp -r spec/ dist/spec/ && cp -r README.md dist/README.md"
|
|
17
|
+
"build": "vite build && vite build --config vite.config.lib.js && cp -r docs/ dist/docs/ && cp -r examples/ dist/examples/ && cp -r grammar/ dist/grammar/ && cp -r ontologies/ dist/ontologies/ && cp -r spec/ dist/spec/ && cp -r README.md dist/README.md && cp -r docs.html dist/docs.html && cp -r demo/ dist/demo/"
|
|
18
18
|
},
|
|
19
19
|
"keywords": [
|
|
20
20
|
"mdld",
|