mdld-parse 0.9.1 → 0.9.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 (59) hide show
  1. package/README.md +34 -1
  2. package/dist/.nojekyll +0 -0
  3. package/dist/CNAME +1 -0
  4. package/dist/README.md +425 -0
  5. package/dist/docs/API.md +397 -0
  6. package/dist/docs/Architecture.md +190 -0
  7. package/dist/docs/Guide.md +322 -0
  8. package/dist/docs/LLM-MDLD-Inducer.md +550 -0
  9. package/dist/docs/Parser.md +654 -0
  10. package/dist/docs/Performance.md +238 -0
  11. package/dist/docs/Spec-render.md +1439 -0
  12. package/dist/docs/Subject.md +180 -0
  13. package/dist/docs/Syntax.md +463 -0
  14. package/dist/docs/TodoList.md +215 -0
  15. package/dist/docs/Use-Cases.md +354 -0
  16. package/dist/docs/index.html +108 -0
  17. package/dist/docs/index.md +56 -0
  18. package/dist/docs/origin.md +459 -0
  19. package/dist/docs/polarity.md +586 -0
  20. package/dist/docs/primary-subject.md +199 -0
  21. package/dist/docs/statements.md +226 -0
  22. package/dist/docs/tokenization-performance-report.md +164 -0
  23. package/dist/examples/Cookbook.md +32 -0
  24. package/dist/examples/Status-SHACL.md +33 -0
  25. package/dist/examples/demo/index.md +35 -0
  26. package/dist/examples/demo/journal.md +18 -0
  27. package/dist/examples/demo/minimal.md +11 -0
  28. package/dist/examples/demo/project.md +15 -0
  29. package/dist/examples/demo/recipe.md +31 -0
  30. package/dist/examples/demo/research.md +46 -0
  31. package/dist/examples/demo/space-mission.md +48 -0
  32. package/dist/examples/dogfood.md +288 -0
  33. package/dist/examples/few-shot.md +309 -0
  34. package/dist/examples/graph/rdf-graph.html +473 -0
  35. package/dist/examples/graph/rdf_force_graph_web_component.html +506 -0
  36. package/dist/examples/index.md +45 -0
  37. package/dist/examples/llm-time-workflow.md +173 -0
  38. package/dist/examples/prov-o.md +2367 -0
  39. package/dist/examples/rdf.md +827 -0
  40. package/dist/examples/shacl.md +3399 -0
  41. package/dist/examples/statements.md +43 -0
  42. package/dist/examples/workflow.md +150 -0
  43. package/dist/index.html +2827 -0
  44. package/dist/index.js +1548 -0
  45. package/dist/logo.svg +7 -0
  46. package/dist/spec/Spec-compact.md +363 -0
  47. package/dist/spec/Spec-ultra.md +221 -0
  48. package/dist/spec/Spec.md +1068 -0
  49. package/dist/spec/index.md +46 -0
  50. package/package.json +13 -8
  51. package/src/constants.js +0 -31
  52. package/src/generate.js +0 -245
  53. package/src/index.js +0 -13
  54. package/src/locate.js +0 -23
  55. package/src/merge.js +0 -157
  56. package/src/parse.js +0 -765
  57. package/src/render.js +0 -576
  58. package/src/shared.js +0 -577
  59. package/src/utils.js +0 -430
@@ -0,0 +1,322 @@
1
+ # MD-LD One Page Guide
2
+
3
+ **Semantic Markdown, no guessing, no magic**
4
+
5
+ MD-LD lets you **add meaning without breaking Markdown**.
6
+ Add `{...}` → you get an RDF graph.
7
+ Delete `{...}` → plain Markdown remains.
8
+
9
+ Everything semantic is **explicit**, **local**, and **traceable**.
10
+
11
+ ---
12
+
13
+ ## 0. Mental model (read once)
14
+
15
+ MD-LD always writes **triples**:
16
+
17
+ ```
18
+ Subject ──predicate──▶ Object / Literal
19
+ ```
20
+
21
+ That’s it.
22
+
23
+ At any annotation `{...}`, there may be:
24
+
25
+ | Symbol | Meaning |
26
+ | ------ | ---------------------------------------------------- |
27
+ | **S** | current subject (IRI) |
28
+ | **O** | object IRI (from link, image, or `{+iri}`) |
29
+ | **L** | literal text (from the attached Markdown span/block) |
30
+
31
+ No subject → no triple
32
+ No guessing → no triple
33
+ No `{...}` → no semantics
34
+
35
+ ---
36
+
37
+ ## 1. Start with a document that *already is* a graph
38
+
39
+ Always declare a subject first.
40
+
41
+ ```md
42
+ [alice] <tag:alice@example.com,2026:>
43
+
44
+ # Walnut Bread {=alice:walnut-bread .Recipe name}
45
+ ```
46
+
47
+ This emits:
48
+
49
+ ```turtle
50
+ tag:alice@example.com,2026:walnut-bread
51
+ a schema:Recipe ;
52
+ schema:name "Walnut Bread" .
53
+ ```
54
+
55
+ **Why this matters**
56
+
57
+ * Your note is already an addressable node
58
+ * Everything that follows attaches to it
59
+ * This is how “casual notes” become “knowledge”
60
+
61
+ ---
62
+
63
+ ### 1.1. Prefix Folding: Build Your Namespace
64
+
65
+ Create hierarchical namespaces by referencing previous prefixes:
66
+
67
+ ```md
68
+ # Your domain authority
69
+ [my] <tag:mymail@domain.com,2026:>
70
+
71
+ # Build the hierarchy
72
+ [j] <my:journal:>
73
+ [p] <my:property:>
74
+ [c] <my:class:>
75
+
76
+ # Use in content
77
+ # 2026-01-27 {=j:2026-01-27 .c:Event p:date ^^xsd:date}
78
+ ```
79
+
80
+ **Resolves to:**
81
+ - `j:2026-01-27` → `tag:mymail@domain.com,2026:journal:2026-01-27`
82
+ - `c:Event` → `tag:mymail@domain.com,2026:class:Event`
83
+ - `p:date` → `tag:mymail@domain.com,2026:property:date`
84
+
85
+ Perfect for personal knowledge graphs without external dependencies.
86
+
87
+ ---
88
+
89
+ ## 2. Value carriers (what can hold meaning)
90
+
91
+ Only these Markdown forms can emit values:
92
+
93
+ **Inline**
94
+
95
+ * `[text] {...}`
96
+ * `*text* {...}`, `**text** {...}`
97
+ * `` `code` {...}``
98
+
99
+ **Block**
100
+
101
+ * Headings
102
+ * List items
103
+ * Blockquotes
104
+ * Code blocks (fence with `{...}`)
105
+
106
+ If `{...}` cannot clearly attach → **nothing is emitted**.
107
+
108
+ ---
109
+
110
+ ## 3. The three predicate forms (the whole algebra)
111
+
112
+ Every triple is written using **one of three predicate shapes**:
113
+
114
+ | Form | Emits |
115
+ | ----- | ------- |
116
+ | `p` | `S → L` |
117
+ | `?p` | `S → O` |
118
+ | `!p` | `O → S` |
119
+
120
+ Nothing else exists.
121
+
122
+ ### Example — all three at once
123
+
124
+ ```md
125
+ [alice] <tag:alice@example.com,2026:>
126
+
127
+ [Bread] {name}
128
+ [Walnut] {+alice:walnut ?hasIngredient}
129
+ [Recipe](https://en.wikipedia.org/wiki/Recipe) {!hasPart}
130
+ ```
131
+
132
+ Never use shortened CURIE in regular Markdown links. They must be valid URLs for the browser to navigate to.
133
+
134
+ ---
135
+
136
+ ## 4. Literals are always local
137
+
138
+ Text comes **only** from the attached carrier.
139
+
140
+ ```md
141
+ [2024] {published ^^xsd:gYear}
142
+ [Delicious bread] {description @en}
143
+ ```
144
+
145
+ No datatype or language is ever inferred.
146
+
147
+ ---
148
+
149
+ ## 5. Object IRIs (links or `{+iri}`)
150
+
151
+ Objects exist only if explicitly present.
152
+
153
+ ```md
154
+ [alice] <tag:alice@example.com,2026:>
155
+
156
+ [Walnuts](tag:alice@example.com,2026:walnut) {?ingredient}
157
+ ```
158
+
159
+ or
160
+
161
+ ```md
162
+ [Walnuts] {+alice:walnut ?ingredient}
163
+ ```
164
+
165
+ Same graph. Different ergonomics.
166
+
167
+ ---
168
+
169
+ ## 6. Lists = pure Markdown structure, explicit annotations only
170
+
171
+ Lists have **no semantic scope**. Each item must have explicit annotations.
172
+
173
+ ```md
174
+ [alice] <tag:alice@example.com,2026:>
175
+
176
+ Ingredients: {=alice:recipe .Container}
177
+
178
+ - Walnuts {+alice:walnut ?member .alice:Ingredient name}
179
+ - Flour {+alice:flour ?member .alice:Ingredient name}
180
+ - Water {+alice:water ?member .alice:Ingredient name}
181
+ ```
182
+
183
+ Result: clean, explicit graph. No implicit semantics.
184
+
185
+ ### List Item Requirements
186
+
187
+ **✅ DO - Items with explicit subjects emit semantics:**
188
+ ```md
189
+ - **Flour** {=alice:flour} # Clean subject
190
+ - **Walnuts** {=alice:walnuts} # Clean subject
191
+ ```
192
+
193
+
194
+ **Critical Rule**: **All list items must have explicit subject (`{=iri}` or `{+iri}`) to emit semantics.**
195
+
196
+ **Valid Alternatives for Additional Information:**
197
+
198
+ **✅ Nested Lists (Pure Structure)**
199
+ ```md
200
+ - **Flour** {=alice:flour}
201
+ Properties:
202
+ - **Organic** {+alice:organic ?alice:hasProperty .alice:Property label}
203
+ ```
204
+
205
+ **✅ Separate Sections**
206
+ ```md
207
+ - **Flour** {=alice:flour}
208
+
209
+ ## Flour Description {=alice:flour}
210
+ [*Important*] {priority .Important}
211
+ ```
212
+
213
+ **Why?** Lists are **pure Markdown structure**. This keeps them predictable and streaming-safe.
214
+
215
+ ---
216
+
217
+ ## 7. Fragments = structured documents
218
+
219
+ Fragments turn sections into addressable nodes.
220
+
221
+ ```md
222
+ [alice] <tag:alice@example.com,2026:>
223
+
224
+ ## Instructions {=#steps .HowTo}
225
+
226
+ ### Mixing {=#step-1 .HowToStep rdfs:label}
227
+
228
+ > Mix ingredients {text}
229
+
230
+ ### Baking {=#step-2 .HowToStep rdfs:label}
231
+
232
+ > Bake for 45 minutes {text}
233
+ ```
234
+
235
+ Emits:
236
+
237
+ ```turtle
238
+ tag:alice@example.com,2026:walnut-bread#steps a schema:HowTo .
239
+ tag:alice@example.com,2026:walnut-bread#step-1 a schema:HowToStep ; rdfs:label "Mixing" ; schema:text "Mix ingredients" .
240
+ tag:alice@example.com,2026:walnut-bread#step-2 a schema:HowToStep ; rdfs:label "Baking" ; schema:text "Bake for 45 minutes" .
241
+ ```
242
+
243
+ Fragments always attach to the **current subject base**.
244
+
245
+ ---
246
+
247
+ ## 8. Blockquotes = descriptions, abstracts, notes
248
+
249
+ ```md
250
+ > A dense, rustic bread with toasted walnuts. {description}
251
+ ```
252
+
253
+ Readable prose → structured data.
254
+
255
+ ---
256
+
257
+ ## 9. Code blocks are first-class values
258
+
259
+ ````md
260
+ [alice] <tag:alice@example.com,2026:>
261
+
262
+ ```txt {=alice:walnut-bread#formula .Recipe text}
263
+ 500g flour
264
+ 300ml water
265
+ ```
266
+ ````
267
+
268
+ Code content becomes a literal.
269
+ Language fences stay intact.
270
+
271
+ ---
272
+
273
+ ## 10. Reverse relations (write from either side)
274
+
275
+ ```md
276
+ [alice] <tag:alice@example.com,2026:>
277
+
278
+ Used in: {!hasIngredient}
279
+
280
+ - Salad {=alice:salad}
281
+ ````
282
+
283
+ Same graph. Different narrative flow.
284
+
285
+ ---
286
+
287
+ ## 11. What MD-LD never does
288
+
289
+ * ❌ No implicit meaning
290
+ * ❌ No blank nodes
291
+ * ❌ No inferred subjects
292
+ * ❌ No structural guessing
293
+ * ❌ No multi-pass parsing
294
+ * ❌ **No semantic list propagation**
295
+
296
+ Every triple is **authored**, not derived.
297
+
298
+ ---
299
+
300
+ ## 12. Why this scales (humans + agents)
301
+
302
+ Because MD-LD is:
303
+
304
+ * **Streaming-parseable**
305
+ * **Round-trip safe**
306
+ * **Text-preserving**
307
+ * **SPARQL-addressable**
308
+
309
+ Agents can:
310
+
311
+ * align facts via SPARQL
312
+ * add/remove triples
313
+ * serialize changes back into Markdown
314
+ without breaking prose, layout, or intent.
315
+
316
+ Your document becomes a **shared semantic surface**, not a data export.
317
+
318
+ ---
319
+
320
+ ## One sentence summary
321
+
322
+ > **MD-LD is RDF you can read, write, diff, query, and share—without ever leaving Markdown.**