mdld-parse 0.9.2 → 0.9.4

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 (64) hide show
  1. package/dist/.nojekyll +0 -0
  2. package/dist/CNAME +1 -0
  3. package/dist/README.md +425 -0
  4. package/dist/docs/API.md +397 -0
  5. package/dist/docs/Architecture.md +190 -0
  6. package/dist/docs/Guide.md +816 -0
  7. package/dist/docs/LLM-MDLD-Inducer.md +550 -0
  8. package/dist/docs/Parser.md +654 -0
  9. package/dist/docs/Performance.md +238 -0
  10. package/dist/docs/Spec-render.md +1439 -0
  11. package/dist/docs/Subject.md +180 -0
  12. package/dist/docs/Syntax.md +463 -0
  13. package/dist/docs/TodoList.md +215 -0
  14. package/dist/docs/Use-Cases.md +354 -0
  15. package/dist/docs/guide-m.md +56 -0
  16. package/dist/docs/index.html +108 -0
  17. package/dist/docs/index.md +56 -0
  18. package/dist/docs/one-page.md +322 -0
  19. package/dist/docs/origin.md +459 -0
  20. package/dist/docs/polarity.md +586 -0
  21. package/dist/docs/primary-subject.md +199 -0
  22. package/dist/docs/statements.md +226 -0
  23. package/dist/docs/tokenization-performance-report.md +164 -0
  24. package/dist/examples/Cookbook.md +32 -0
  25. package/dist/examples/Status-SHACL.md +31 -0
  26. package/dist/examples/demo/index.md +35 -0
  27. package/dist/examples/demo/journal.md +119 -0
  28. package/dist/examples/demo/minimal.md +23 -0
  29. package/dist/examples/demo/project.md +98 -0
  30. package/dist/examples/demo/prov.md +107 -0
  31. package/dist/examples/demo/rdf.md +69 -0
  32. package/dist/examples/demo/recipe.md +95 -0
  33. package/dist/examples/demo/research.md +126 -0
  34. package/dist/examples/demo/shacl.md +161 -0
  35. package/dist/examples/demo/space-mission.md +129 -0
  36. package/dist/examples/demo/tasks.md +175 -0
  37. package/dist/examples/demo/xsd.md +91 -0
  38. package/dist/examples/dogfood.md +288 -0
  39. package/dist/examples/few-shot.md +309 -0
  40. package/dist/examples/graph/rdf-graph.html +473 -0
  41. package/dist/examples/graph/rdf_force_graph_web_component.html +506 -0
  42. package/dist/examples/index.md +45 -0
  43. package/dist/examples/llm-time-workflow.md +173 -0
  44. package/dist/examples/statements.md +43 -0
  45. package/dist/examples/workflow.md +150 -0
  46. package/dist/index.html +3253 -0
  47. package/dist/index.js +1770 -0
  48. package/dist/logo.svg +7 -0
  49. package/dist/spec/Spec-compact.md +363 -0
  50. package/dist/spec/Spec-ultra.md +221 -0
  51. package/dist/spec/Spec.md +1068 -0
  52. package/dist/spec/index.md +46 -0
  53. package/package.json +7 -8
  54. package/src/constants.js +0 -31
  55. package/src/generate.js +0 -245
  56. package/src/highlight.js +0 -362
  57. package/src/index.js +0 -13
  58. package/src/locate.js +0 -23
  59. package/src/merge.js +0 -157
  60. package/src/parse.js +0 -711
  61. package/src/render.js +0 -576
  62. package/src/shared.js +0 -577
  63. package/src/tokenizers.js +0 -594
  64. package/src/utils.js +0 -430
@@ -0,0 +1,108 @@
1
+ <!DOCTYPE html>
2
+ <html lang="en">
3
+
4
+ <head>
5
+ <meta charset="UTF-8">
6
+ <title>MDLD Documentation Browser</title>
7
+ <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@unocss/reset/tailwind.min.css" />
8
+
9
+ <script src="https://cdn.jsdelivr.net/npm/@unocss/runtime/uno.global.js"></script>
10
+ <script type="importmap">
11
+ {
12
+ "imports": {
13
+ "vue": "https://esm.sh/vue@3.6.0-beta.10/dist/vue.esm-browser.prod.js",
14
+ "mdld-parse": "https://esm.sh/mdld-parse@0.9.0",
15
+ "n3": "https://esm.sh/n3@2.0.3",
16
+ "markdown-it": "https://esm.sh/markdown-it@14.1.0"
17
+ }
18
+ }
19
+ </script>
20
+
21
+ <style>
22
+ .prose {
23
+ max-width: 100%;
24
+
25
+ & a {
26
+ color: #2563eb;
27
+ text-decoration: none;
28
+
29
+ &:hover {
30
+ text-decoration: underline;
31
+ }
32
+ }
33
+ }
34
+
35
+ .prose h1 {
36
+ font-size: 2rem;
37
+ font-weight: bold;
38
+ }
39
+ </style>
40
+ </head>
41
+
42
+ <body>
43
+
44
+ <div id="app" class="min-h-screen bg-gray-50">
45
+ <header class="bg-white shadow-sm border-b">
46
+ <div class="max-w-4xl mx-auto px-6 py-4">
47
+ <h1 class="text-2xl font-bold text-gray-900">MDLD Documentation Browser</h1>
48
+ </div>
49
+ </header>
50
+
51
+ <main class="max-w-4xl mx-auto px-6 py-8">
52
+ <div v-if="loading" class="text-center py-8">
53
+ <p class="text-gray-600">Loading documentation...</p>
54
+ </div>
55
+
56
+ <div v-else-if="error" class="bg-red-50 border border-red-200 rounded-lg p-4">
57
+ <p class="text-red-800">{{ error }}</p>
58
+ </div>
59
+
60
+ <article v-else class="prose prose-gray max-w-none" v-html="renderedContent"></article>
61
+ </main>
62
+ </div>
63
+
64
+ <script type="module">
65
+ import { createApp, ref, onMounted } from 'vue'
66
+ import MarkdownIt from 'markdown-it'
67
+ import { parse, render } from 'mdld-parse'
68
+
69
+ createApp({
70
+ setup() {
71
+ const loading = ref(true)
72
+ const error = ref(null)
73
+ const content = ref('')
74
+ const md = new MarkdownIt()
75
+ const renderedContent = ref('')
76
+ const fetchDocumentation = async () => {
77
+ try {
78
+ loading.value = true
79
+ error.value = null
80
+ const response = await fetch('./index.md')
81
+ content.value = await response.text()
82
+ console.log(md.parse(content.value))
83
+ renderedContent.value = md.render(content.value)
84
+
85
+ } catch (err) {
86
+ error.value = err.message
87
+ console.error('Error loading documentation:', err)
88
+ } finally {
89
+ loading.value = false
90
+ }
91
+ }
92
+
93
+ onMounted(() => {
94
+ fetchDocumentation()
95
+ })
96
+
97
+ return {
98
+ loading,
99
+ error,
100
+ renderedContent
101
+ }
102
+ }
103
+ }).mount('#app')
104
+ </script>
105
+
106
+ </body>
107
+
108
+ </html>
@@ -0,0 +1,56 @@
1
+ # Documentation Hub
2
+
3
+ ## 🎯 Core Documentation
4
+
5
+ ### 🎯 [Elevated Statements](./statements.md)
6
+ Automatic rdf:Statement pattern detection for "golden graph" extraction
7
+
8
+ ### 📍 [Origin System](./origin.md)
9
+ Complete guide to lean origin tracking for UI navigation and provenance
10
+
11
+ ### ⚡ [Polarity & Retraction](./polarity.md)
12
+ Sophisticated diff authoring and document evolution with `+` and `-` prefixes
13
+
14
+ ### 📖 [API Reference](./API.md)
15
+ Complete API documentation with tested examples and usage patterns
16
+
17
+ ### 📝 [Syntax Reference](./Syntax.md)
18
+ Complete syntax reference with examples for all MD-LD constructs
19
+
20
+ ### 📖 [One Page Guide](./Guide.md)
21
+ Quick start guide with mental model and patterns
22
+
23
+ ### 🏷️ [Subject System](./Subject.md)
24
+ Subject declaration and context management
25
+
26
+ ## 🏗️ Architecture & Performance
27
+
28
+ ### 🏛️ [Architecture](./Architecture.md)
29
+ Design principles, processing pipeline, and performance characteristics
30
+
31
+ ### ⚙️ [Parser Architecture](./Parser.md)
32
+ Core parser structures, token processing, and implementation details
33
+
34
+ ### 🧪 [Testing](../tests/)
35
+ Comprehensive test suite with 109 tests covering all functionality
36
+
37
+ ## 🎯 Real-World Applications
38
+
39
+ ### 📋 [Use Cases](./Use-Cases.md)
40
+ Practical examples and applications across different domains:
41
+
42
+ - **Personal Knowledge Management** - Journal entries, project tracking
43
+ - **Developer Documentation** - API specs, schema documentation
44
+ - **Academic Research** - Papers, citations, provenance tracking
45
+ - **Content Management** - Blogs, product catalogs, documentation
46
+ - **Data Integration** - Database schemas, workflow automation
47
+ - **Business Processes** - Invoice processing, approval workflows
48
+
49
+ ## Key Features
50
+
51
+ - **🎯 Elevated statements** - Automatic rdf:Statement pattern detection for "golden graph" extraction
52
+ - **📍 Origin tracking** - Complete provenance with lean quad-to-source mapping
53
+ - **⚡ Polarity system** - Sophisticated diff authoring with `+` and `-` prefixes
54
+ - **📝 Rich syntax** - Multiple carrier types and predicate forms
55
+ - **🏷️ Context management** - Subject declarations and prefix folding
56
+ - **🔗 RDF/JS compatibility** - Works with n3.js, rdflib, and other RDF libraries
@@ -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.**