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.
Files changed (3) hide show
  1. package/README.md +172 -61
  2. package/dist/index.js +1 -1
  3. 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
  [![NPM](https://img.shields.io/npm/v/mdld-parse)](https://www.npmjs.com/package/mdld-parse)
8
8
 
9
- [Demo](https://mdld.js.org) | [Repository](https://github.com/davay42/mdld-parse)
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] <http://example.org/>
37
+ [ex] <tag:alice@example.com,2026:>
38
+
39
+ # My Bookmarks {=ex:bookmarks .prov:Entity .Container label}
29
40
 
30
- # Document {=ex:doc .Article label}
41
+ > This is my first MD-LD document - a Bookmarks Collection {comment}
31
42
 
32
- [Alice] {=ex:alice ?ex:author .prov:Person ex:firstName label}
33
- [Smith] {ex:lastName}
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
- - **Alice** {+alice:alice ?alice:attendee label}
94
- - **Bob** {+alice:bob ?alice:attendee label}
110
+ **Alice** {+alice:alice ?alice:attendee label}
111
+ **Bob** {+alice:bob ?alice:attendee label}
95
112
 
96
113
  Action items:
97
- - **Review proposal** {+alice:task-1 ?alice:actionItem label}
114
+ **Review proposal** {+alice:task-1 ?alice:actionItem label}
98
115
  ```
99
116
 
100
117
  #### Developer Documentation
101
118
  ```markdown
102
- # API Endpoint {=api:/users/:id .api:Endpoint}
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
- # Paper {=alice:paper-semantic-markdown .alice:ScholarlyArticle}
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
- [Semantic Web] {label}
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
- # Understanding MD-LD {=blog:post-mdld .blog:Post}
138
+ [blog] <tag:justin@example.org,2026:>
139
+ # Understanding MD-LD {=blog:post-mdld .blog:Post label}
120
140
 
121
- [MD-LD] {blog:emphasized label} allows you to embed RDF directly in Markdown.
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
- ```javascript
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 'https://cdn.jsdelivr.net/npm/mdld-parse/+esm';
176
- const result = parse('[ex] <http://example.org/>\n\n# Hello {=ex:hello label}');
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
- **Bundle size:** 84KB unminified, 19KB gzipped
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
- ## Apollo 11 {=ex:apollo11 .SpaceMission .Event}
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
- # Update value
241
- [Person] {=ex:person}
242
- [Alice] {-ex:name}
243
- [Bob] {ex:name}
244
-
245
- # Remove triple
246
- [Person] {=ex:person}
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, 84KB unminified (19KB gzipped)
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
- ## 📚 Additional Resources
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
- - **[Documentation](./docs/index.md)** — Complete guides and references
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.1",
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",