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,215 @@
1
+ # Tasks: MDLD-Powered Personal Knowledge Management
2
+
3
+ ## The Breakthrough We've Experienced
4
+
5
+ Working with MDLD has revealed something profound: **the gap between human-readable documents and machine-processable knowledge graphs can be bridged completely**. Our todo list demonstration isn't just a technical exerciseโ€”it's a glimpse into how personal knowledge management will actually work in the decentralized, semantic web era.
6
+
7
+ ## What MDLD Makes Possible
8
+
9
+ ### ๐Ÿ“ **Human-Centric Design**
10
+ - **Write-first, think-later**: Your document starts as plain Markdown, readable by anyone
11
+ - **Semantic opt-in**: Add `{...}` annotations only where meaning matters
12
+ - **No schema migration**: Your knowledge evolves naturally, not through database migrations
13
+ - **Text preservation**: Your prose, formatting, and structure remain intact forever
14
+
15
+ ### ๐Ÿ”„ **Append-Only Architecture**
16
+ - **Immutable history**: Every action is recorded, never overwritten
17
+ - **Complete audit trail**: Who did what, when, and why is preserved
18
+ - **State reconstruction**: Current state emerges from processing the entire log
19
+ - **No data loss**: Even parsing errors can't corrupt your history
20
+
21
+ ### ๐ŸŒ **Web-Native Benefits**
22
+ - **Streaming-friendly**: Process documents line-by-line, no full loading required
23
+ - **Queryable**: SPARQL across your entire knowledge history
24
+ - **Portable**: Single text file contains data + provenance
25
+ - **Version control friendly**: Works seamlessly with Git and other diff tools
26
+
27
+ ## The Everyday Revolution
28
+
29
+ ### ๐Ÿ  **Morning Routine Enhancement**
30
+ Imagine your daily task list evolving:
31
+
32
+ ```markdown
33
+ [my] <tag:alice@example.org,2026:daily:routine:>
34
+
35
+ # Morning Routine {=my:routine-2026-09-04 .prov:Entity label}
36
+
37
+ ## Coffee Setup {=my:activity-2026-09-04-1 .prov:Activity label}
38
+ [7:00 AM] {prov:startedAtTime ^^xsd:dateTime}
39
+ [7:05 AM] {prov:endedAtTime ^^xsd:dateTime}
40
+ [Auto-brew] {+my:coffee ?prov:used .prov:Entity label}
41
+
42
+ {=my:coffee}
43
+ [French press] {brew:method}
44
+ [Strong] {strength:level}
45
+ ```
46
+
47
+ ### ๐Ÿ“š **Reading List Evolution**
48
+ Your reading list becomes a semantic library:
49
+
50
+ ```markdown
51
+ [my] <tag:bob@example.org,2026:books:>
52
+
53
+ # Reading List {=my:books .prov:Collection label}
54
+
55
+ ## Sapiens {=my:book/sapiens .prov:Entity .Container label}
56
+ [Yuval Noah Harari] {+my:harari .prov:Person ?my:author label}
57
+ [Non-fiction] {my:genre}
58
+ [480] {my:pageCount ^^xsd:int}
59
+
60
+ ## Thinking Fast and Slow {=my:book/thinking-fast-and-slow .prov:Entity label}
61
+ [Daniel Kahneman] {+my:authors/kahneman .prov:Person ?my:author label}
62
+ [Psychology] {my:genre}
63
+ [432] {my:pageCount ^^xsd:int}
64
+ ```
65
+
66
+ ### ๐ŸŽฏ **Goal Achievement Tracking**
67
+ Your personal goals become first-class semantic objects:
68
+
69
+ ```markdown
70
+ # 2026 Goals {=my:goals .prov:Entity label}
71
+
72
+ ## Learn Spanish {=my:goals/fluent-spanish .prov:Entity label}
73
+ [Language learning] {my:category}
74
+ [Spanish] {my:language}
75
+ [Fluent conversation] {my:proficiency}
76
+
77
+ ## Build Side Project {=my:goals/build-side-project .prov:Entity label}
78
+ [Software development] {my:category}
79
+ [Web application] {my:domain}
80
+ [2026-09-01] {my:deadline ^^xsd:date}
81
+ ```
82
+
83
+ ## The Personal Knowledge Graph
84
+
85
+ ### ๐Ÿ•ธ๏ธ **Temporal Navigation**
86
+ - **Scroll back through time**: See what you were thinking on any date
87
+ - **Understand evolution**: Watch how your knowledge and priorities changed
88
+ - **Learn from patterns**: Identify recurring themes and decision patterns
89
+ - **Connect the dots**: Discover relationships between different areas of your life
90
+
91
+ ### ๐Ÿ” **Semantic Search**
92
+ - **Find by context**: "What books did I read about psychology?"
93
+ - **Cross-reference knowledge**: "Which tasks relate to my Spanish learning goal?"
94
+ - **Track influence**: "What ideas led to my side project decisions?"
95
+ - **Personal analytics**: Understand your own cognitive and behavioral patterns
96
+
97
+ ### ๐ŸŒฑ **Living Knowledge Base**
98
+ - **Grows with you**: Every new interest, book, or goal enriches your graph
99
+ - **Never becomes obsolete**: Old knowledge remains accessible and valuable
100
+ - **Interconnections emerge**: Your system discovers relationships you didn't explicitly create
101
+ - **Personal ontology**: Your unique way of organizing meaning becomes queryable
102
+
103
+ ## The Decentralized Knowledge Worker
104
+
105
+ ### ๐Ÿก **Self-Sovereignty**
106
+ - **You own your data**: No corporation controls your personal knowledge
107
+ - **Portable identity**: Your knowledge graph travels with you across platforms
108
+ - **Interoperable**: Standard RDF vocabularies work with any compatible system
109
+ - **Future-proof**: Your knowledge isn't locked into any proprietary format
110
+
111
+ ### ๐Ÿค– **Agent Enhancement**
112
+ - **Personal AI assistant**: Your MDLDD documents help AI understand your context
113
+ - **Automated insights**: Agents can analyze your patterns and suggest improvements
114
+ - **Knowledge synthesis**: Combine information from multiple domains automatically
115
+ - **Preserved agency**: You maintain control over what and how things are recorded
116
+
117
+ ## Beyond the Todo List
118
+
119
+ ### ๐ŸŽญ **Creative Projects**
120
+ Your artistic works become semantic entities with inspiration sources, techniques, and relationships:
121
+
122
+ ```markdown
123
+ [my] <tag:john@example.org,2026:music:>
124
+
125
+ # Song Ideas {=my:songs .prov:Collection label}
126
+
127
+ ## Midnight Melody {=my:midnight-melody .prov:Entity label}
128
+ [Inspired by insomnia] {+my:inspiration/insomnia ?prov:wasInformedBy .prov:Activity}
129
+ [Electronic] {genre}
130
+ [120 BPM] {tempo}
131
+
132
+ ## Lyric Sketches {=my:lyric-sketches .prov:Entity label}
133
+ [Based on personal experience] {+my:personal ?prov:wasDerivedFrom .prov:Entity}
134
+ [Acoustic] {arrangement}
135
+ [Draft stage] {status}
136
+ ```
137
+
138
+ ### ๐Ÿณ **Learning Journeys**
139
+ Your educational pursuits become documented progress with resources, milestones, and insights:
140
+
141
+ ```markdown
142
+ [my] <tag:sam@example.org,2026:music:learning:>
143
+
144
+ # Guitar Learning {=my:guitar .prov:Entity label}
145
+
146
+ ## First Month {=my:guitar1 .prov:Activity label}
147
+ [Bought acoustic guitar] {+my:guitar ?prov:used .prov:Entity}
148
+ [Learned basic chords] {+my:skill/basic-guitar-chords ?my:skill}
149
+ [Practiced 30 hours] {+my:guitar1 ?time:investment ^^xsd:duration}
150
+
151
+ ## Three Month Progress {=my:guitar2 .prov:Activity label}
152
+ [Mastered F chord progression] {+my:skill/f-chord-progression ?outcome:skill}
153
+ [Learned fingerpicking patterns] {+my:skill/fingerpicking-patterns ?outcome:skill}
154
+ [Performed first song] {+my:event/first-song ?outcome:achievement}
155
+ ```
156
+
157
+ ## The MDLD Lifestyle
158
+
159
+ ### ๐ŸŒ… **Morning Pages**
160
+ Your journal entries become structured reflections with mood, activities, and connections:
161
+
162
+ ```markdown
163
+ # Journal Entry {=my:entry .prov:Entity label}
164
+
165
+ ## Monday, March 24 {=my:entry20260324 .prov:Entity label}
166
+ [Productive and focused] {mood}
167
+ [Completed project planning] {achievement}
168
+ [Evening walk in park] {+#walk-in-park .prov:Activity ?prov:wasInformedBy}
169
+
170
+ [Weather: Sunny, 18ยฐC] {environment}
171
+
172
+ ### Thinking Fast and Slow {currently:reading}
173
+ ```
174
+
175
+ ### ๐Ÿ“Š **Weekly Reviews**
176
+ Your week summaries become meaningful analytics with patterns and goals:
177
+
178
+ ```markdown
179
+ [my] <tag:sam@example.org,2026:weeks:>
180
+
181
+ # Week 12 Review {=my:w12 .my:Review .prov:Entity label}
182
+
183
+ Core goal: [Deep work project] {+my:goals/deep-work-project ?my:goal label .prov:Entity}
184
+
185
+ [Productive week] {my:assessment}
186
+ [Completed 5 major tasks] {my:achievement}
187
+ Key insight: [Need more sleep] {my:learning}
188
+
189
+ ```
190
+
191
+ ## The Promise
192
+
193
+ ### ๐Ÿš€ **Personal Knowledge Evolution**
194
+ MDLD enables what previous knowledge management systems couldn't achieve:
195
+
196
+ 1. **Semantic continuity**: Your knowledge from 2024 connects meaningfully to your knowledge from 2026
197
+ 2. **Provenance context**: Future you understands not just what you know, but how you came to know it
198
+ 3. **Pattern recognition**: Your personal AI can identify your learning styles and decision patterns
199
+ 4. **Knowledge synthesis**: Combine insights from different domains to generate new understanding
200
+ 5. **Legacy preservation**: Your wisdom becomes part of a queryable, interoperable knowledge graph
201
+
202
+ ### ๐ŸŒŸ **The New Possibility**
203
+
204
+ This isn't just about better task management. It's about **creating a personal knowledge ecosystem** where:
205
+
206
+ - **Every thought matters** and can be connected to other thoughts
207
+ - **Every experience teaches** and becomes part of your wisdom
208
+ - **Every goal achieved** adds to your provenance of capability
209
+ - **Every failure teaches** and becomes part of your learning journey
210
+
211
+ MDLD makes your personal knowledge **alive, queryable, and portable**โ€”ready for the decentralized web while remaining completely under your control.
212
+
213
+ ---
214
+
215
+ *This document itself is a living example of MDLD's powerโ€”every section demonstrates different semantic patterns you can use to build your own personal knowledge graph.*
@@ -0,0 +1,354 @@
1
+ # MD-LD Use Cases
2
+
3
+ Real-world applications and examples of MD-LD in action.
4
+
5
+ ## Personal Knowledge Management
6
+
7
+ Create personal knowledge graphs with rich metadata and relationships.
8
+
9
+ ### Journal Entries
10
+
11
+ ```markdown
12
+ [alice] <tag:alice@example.com,2026:>
13
+
14
+ # Meeting Notes {=alice:meeting-2024-01-15 .alice:Meeting}
15
+
16
+ Attendees:
17
+
18
+ - **Alice** {+alice:alice ?alice:attendee label}
19
+ - **Bob** {+alice:bob ?alice:attendee label}
20
+
21
+ Action items:
22
+
23
+ - **Review proposal** {+alice:task-1 ?alice:actionItem label}
24
+ ```
25
+
26
+ **Generated RDF:**
27
+ ```turtle
28
+ @prefix rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#>.
29
+ @prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#>.
30
+ @prefix alice: <tag:alice@example.com,2026:>.
31
+ @prefix xsd: <http://www.w3.org/2001/XMLSchema#>.
32
+
33
+ alice:meeting-2024-01-15 a alice:Meeting;
34
+ alice:attendee alice:alice, alice:bob;
35
+ alice:actionItem alice:task-1.
36
+ alice:alice a alice:Person;
37
+ rdfs:label "Alice".
38
+ alice:bob a alice:Person;
39
+ rdfs:label "Bob".
40
+ alice:task-1 a alice:ActionItem;
41
+ rdfs:label "Review proposal".
42
+ ```
43
+
44
+ ### Project Tracking
45
+
46
+ ```markdown
47
+ [my] <tag:myproject@example.com,2026:>
48
+
49
+ # Project Alpha {=my:proj-alpha .my:Project}
50
+
51
+ Team members:
52
+
53
+ - **Alice** {+my:alice ?my:teamMember label}
54
+ - **Bob** {+my:bob ?my:teamMember label}
55
+
56
+ Tasks:
57
+
58
+ - **Design schema** {+my:task-design ?my:hasTask .my:Task label}
59
+ - **Implement parser** {+my:task-parser ?my:hasTask .my:Task label}
60
+ ```
61
+
62
+ **Benefits:**
63
+ - **Rich relationships** - Model team structure and task dependencies
64
+ - **Temporal tracking** - Add dates and status to project items
65
+ - **Searchable** - Query across projects, tasks, and people
66
+
67
+ ## Developer Documentation
68
+
69
+ Document APIs, schemas, and technical specifications with executable examples.
70
+
71
+ ### API Endpoint Documentation
72
+
73
+ ```markdown
74
+ # API Endpoint {=api:/users/:id .api:Endpoint}
75
+
76
+ [GET] {api:method}
77
+ [/users/:id] {api:path}
78
+
79
+ Example:
80
+
81
+ ```bash {=api:/users/:id#example .api:CodeExample api:code}
82
+ curl https://api.example.com/users/123
83
+ ```
84
+
85
+ **Features:**
86
+ - **Executable examples** - Code blocks with syntax highlighting
87
+ - **Parameter documentation** - Clear path and method specifications
88
+ - **Response examples** - Sample outputs and error handling
89
+
90
+ ### Schema Documentation
91
+
92
+ ```markdown
93
+ # User Schema {=schema:user .sh:NodeShape}
94
+
95
+ ## Required Properties {=schema:user-required .sh:PropertyShape ?sh:property}
96
+ Name: [string] {+schema:name ?sh:path .sh:datatype xsd:string sh:minCount 1 sh:maxCount 1}
97
+ > User must have exactly one name {sh:message}
98
+
99
+ ## Optional Properties {=schema:user-optional .sh:PropertyShape ?sh:property}
100
+ Email: [string] {+schema:email ?sh:path .sh:datatype xsd:string}
101
+ > Optional email address {sh:message}
102
+ ```
103
+
104
+ **Advantages:**
105
+ - **Self-validating** - SHACL shapes validate the documentation itself
106
+ - **Interactive examples** - Code blocks can be executed directly
107
+ - **Version control** - Track schema evolution with polarity
108
+
109
+ ## Academic Research
110
+
111
+ Model research papers, citations, and academic workflows with proper provenance.
112
+
113
+ ### Paper Structure
114
+
115
+ ```markdown
116
+ [alice] <tag:alice@example.com,2026:>
117
+
118
+ # Paper {=alice:paper-semantic-markdown .alice:ScholarlyArticle}
119
+
120
+ [Semantic Web] {label}
121
+ [Alice Johnson] {=alice:alice-johnson ?alice:author}
122
+ [2024-01] {alice:datePublished ^^xsd:gYear}
123
+
124
+ > This paper explores semantic markup in Markdown. {comment @en}
125
+
126
+ ## Related Work {=alice:related .alice:Section}
127
+
128
+ ### Previous Research {=alice:prev-research .alice:Work}
129
+ [Semantic Annotations] {label}
130
+ [2023] {alice:year ^^xsd:gYear}
131
+
132
+ ### Future Directions {=alice:future-work .alice:Work}
133
+ [AI Integration] {label}
134
+ [2025] {alice:plannedYear ^^xsd:gYear}
135
+ ```
136
+
137
+ **Generated RDF:**
138
+ ```turtle
139
+ alice:paper-semantic-markdown a alice:ScholarlyArticle;
140
+ rdfs:label "Semantic Web";
141
+ alice:author alice:alice-johnson;
142
+ alice:datePublished "2024"^^xsd:gYear;
143
+ rdfs:comment "This paper explores semantic markup in Markdown."@en.
144
+ ```
145
+
146
+ **Benefits:**
147
+ - **Proper citations** - Model academic relationships and citations
148
+ - **Provenance tracking** - Track paper evolution and contributions
149
+ - **Metadata standards** - Follow academic metadata schemas
150
+
151
+ ## Content Management System
152
+
153
+ Manage websites, blogs, and content with structured metadata.
154
+
155
+ ### Blog Post
156
+
157
+ ```markdown
158
+ [blog] <https://myblog.example.com/>
159
+
160
+ # Understanding MD-LD {=blog:post-mdld .blog:Post}
161
+
162
+ ## Introduction {=blog:intro .blog:Section}
163
+ [MD-LD] {blog:emphasized label} allows you to embed RDF directly in Markdown while maintaining readability.
164
+
165
+ ## Features {=blog:features .blog:Section}
166
+
167
+ ### Syntax {=blog:syntax .blog:Subsection}
168
+ [Explicit annotations] {blog:feature label} ensure deterministic parsing.
169
+
170
+ ### Benefits {=blog:benefits .blog:Subsection}
171
+ [Zero dependencies] {blog:feature label}
172
+ [Streaming] {blog:feature label}
173
+
174
+ ## Conclusion {=blog:conclusion .blog:Section}
175
+ [Get started] {blog:callToAction label} with the quick start guide.
176
+
177
+ ## Metadata {=blog:metadata .blog:Section}
178
+ [Published] {blog:status label}
179
+ [2024-01-15] {blog:datePublished ^^xsd:date}
180
+ [5 min] {blog:readingTime label}
181
+ ```
182
+
183
+ **SEO Benefits:**
184
+ - **Structured data** - Search engines understand content structure
185
+ - **Rich snippets** - Better search result presentation
186
+ - **Content relationships** - Model series, categories, and references
187
+
188
+ ### Product Documentation
189
+
190
+ ```markdown
191
+ [products] <https://products.example.com/>
192
+
193
+ # Smart Watch {=products:watch-200 .products:Product}
194
+
195
+ ## Specifications {=products:specs .products:Section}
196
+
197
+ ### Display {=products:display .products:Subsection}
198
+ [1.2" OLED] {products:screenSize label}
199
+ [Touchscreen] {products:interface label}
200
+
201
+ ### Performance {=products:performance .products:Subsection}
202
+ [48 hours] {products:batteryLife label}
203
+ [Water resistant] {products:feature label}
204
+
205
+ ## Compatibility {=products:compatibility .products:Section}
206
+
207
+ [iOS] {+products:ios ?products:compatibleWith label}
208
+ [Android] {+products:android ?products:compatibleWith label}
209
+
210
+ ## Pricing {=products:pricing .products:Section}
211
+ [$299] {products:price label ^^xsd:decimal}
212
+ [Available] {products:availability label}
213
+ ```
214
+
215
+ **E-commerce Integration:**
216
+ - **Product catalogs** - Structured product information
217
+ - **Inventory management** - Track stock and availability
218
+ - **Customer reviews** - Model opinions and ratings
219
+
220
+ ## Data Integration
221
+
222
+ ### Database Documentation
223
+
224
+ ```markdown
225
+ [db] <https://database.example.com/>
226
+
227
+ # User Table {=db:users .db:Table}
228
+
229
+ ## Schema {=db:schema .db:Section}
230
+
231
+ ### Primary Key {=db:pk .db:Constraint}
232
+ [id] {db:column .db:Column label}
233
+ [integer] {db:type label}
234
+ [auto increment] {db:constraint label}
235
+
236
+ ### Columns {=db:columns .db:Section}
237
+
238
+ [email] {db:column .db:Column label}
239
+ [string] {db:type label}
240
+ [unique] {db:constraint label}
241
+
242
+ [name] {db:column .db:Column label}
243
+ [string] {db:type label}
244
+ [required] {db:constraint label}
245
+
246
+ ## Sample Data {=db:sample .db:Section}
247
+
248
+ ### User Records {=db:sample .db:Subsection}
249
+ - **Alice** {+db:alice ?db:record .db:User email "alice@example.com"}
250
+ - **Bob** {+db:bob ?db:record .db:User email "bob@example.com"}
251
+ ```
252
+
253
+ **Benefits:**
254
+ - **Data lineage** - Track data transformations and migrations
255
+ - **Schema evolution** - Document database changes over time
256
+ - **Query optimization** - Structure enables efficient queries
257
+
258
+ ## Workflow Automation
259
+
260
+ ### Business Process Modeling
261
+
262
+ ```markdown
263
+ [process] <https://company.example.com/processes/>
264
+
265
+ # Invoice Processing {=process:invoice .process:Workflow}
266
+
267
+ ## Steps {=process:steps .process:Section}
268
+
269
+ ### Data Entry {=process:data-entry .process:Step}
270
+ [Enter invoice data] {process:task label}
271
+ [Validate format] {process:task label}
272
+
273
+ ### Approval {=process:approval .process:Step}
274
+ [Manager review] {process:task label}
275
+ [Financial check] {process:task label}
276
+
277
+ ### Payment Processing {=process:payment .process:Step}
278
+ [Generate payment] {process:task label}
279
+ [Send to accounting] {process:task label}
280
+
281
+ ## Integration Points {=process:integration .process:Section}
282
+
283
+ [Accounting system] {+process:accounting ?process:integratesWith label}
284
+ [CRM system] {+process:crm ?process:integratesWith label}
285
+ ```
286
+
287
+ **Workflow Benefits:**
288
+ - **Process transparency** - Clear steps and responsibilities
289
+ - **Integration points** - Model system connections
290
+ - **Audit trail** - Track process execution and outcomes
291
+
292
+ ## Testing and Validation
293
+
294
+ ### Test Case Documentation
295
+
296
+ ```markdown
297
+ [test] <https://tests.example.com/>
298
+
299
+ # Parser Tests {=test:parser .test:TestSuite}
300
+
301
+ ## Test Categories {=test:categories .test:Section}
302
+
303
+ ### Syntax Tests {=test:syntax .test:Category}
304
+ [Valid annotations] {test:feature label}
305
+ [Error handling] {test:feature label}
306
+
307
+ ### Performance Tests {=test:performance .test:Category}
308
+ [Large documents] {test:scenario label}
309
+ [Memory usage] {test:metric label}
310
+
311
+ ### Integration Tests {=test:integration .test:Category}
312
+ [RDF library compatibility] {test:scenario label}
313
+ [Browser support] {test:scenario label}
314
+
315
+ ## Test Results {=test:results .test:Section}
316
+
317
+ ### Latest Run {=test:latest .test:Run}
318
+ [105 passed] {test:metric label}
319
+ [0 failed] {test:metric label}
320
+ [2.3s] {test:metric label}
321
+
322
+ ## Coverage {=test:coverage .test:Section}
323
+ [Syntax parsing] {test:area covered}
324
+ [Context management] {test:area covered}
325
+ [Polarity system] {test:area covered}
326
+ ```
327
+
328
+ **Quality Assurance:**
329
+ - **Comprehensive coverage** - Test all functionality
330
+ - **Automated validation** - Self-checking test cases
331
+ - **Continuous integration** - Automated test execution
332
+
333
+ ## Best Practices
334
+
335
+ ### Document Structure
336
+
337
+ 1. **Start with prefixes** - Define all namespaces at the top
338
+ 2. **Use consistent subjects** - Logical document organization
339
+ 3. **Add rich metadata** - Types, dates, and relationships
340
+ 4. **Include examples** - Demonstrate usage patterns
341
+
342
+ ### Content Guidelines
343
+
344
+ 1. **Be explicit** - No implicit semantics or guessing
345
+ 2. **Use proper types** - Choose appropriate datatypes
346
+ 3. **Maintain context** - Keep related information together
347
+ 4. **Document changes** - Use polarity for version control
348
+
349
+ ### Technical Guidelines
350
+
351
+ 1. **Validate RDF** - Ensure generated triples are valid
352
+ 2. **Test round-trips** - Verify parse/generate cycles
353
+ 3. **Monitor performance** - Check parsing times and memory usage
354
+ 4. **Handle errors** - Graceful error recovery and reporting
@@ -0,0 +1,56 @@
1
+ # MD-LD User Guide
2
+
3
+ This document will guide you from the start to proficiency in MD-LD authoring.
4
+
5
+ ## 1. First annotation, primary subject definition
6
+
7
+ ~~~md
8
+ # Alice's Journal
9
+
10
+ Hi! My name is Alice Smith. This is my personal semantic journal.
11
+ ~~~
12
+
13
+ This is a regular Markdown note. It is transparent for MD-LD parser. Now let's add our first annotation. We can think of it as like we have a set of special highlighters that we use to mark important parts of the text. So first line is the choice of particular set of markers and in the `##` header you can see our first `{}` curly braces annotation.
14
+
15
+ ~~~md
16
+ [my] <tag:alice.smith@example.org,2026:>
17
+
18
+ # Alice's Journal
19
+
20
+ ## Alice {=my:person/alice .prov:Person label}
21
+
22
+ Hi! My name is Alice Smith. This is my personal semantic journal.
23
+ ~~~
24
+
25
+ Now we have used our personal identifier for Alice - `tag:alice.smith@example.org,2026:person/alice` - it gets unfolded from the short `my:` value with the base IRI set in the first line. This declared that Alice is a person with a label "Alice". Our first point in the knowledge graph. We use built-in PROV-O standard ontology that is designed to describe relations between agents, entities and activities. A `prov:Person` is a kind of `prov:Agent`. `label` is also added as a literal property to have a nice short name for display in graph visualizations. Not having a prefix assumes use the default `@vocab` - `rdfs:`. So `label` is a shortcut for `rdfs:label` to ease friction at labeling things. Then the node on the graph will show cleanly as `Alice` in most graph visualizers and interfaces.
26
+
27
+ ## 2. Context, authority, prefixes
28
+
29
+ First step is to get the concept of namespaces for building knowledge graphs. Everything in the graph - be it subjects, predicates or objects - each of them have unique identifiers - IRI. An IRI may be defined in multiple ways. Most straightforward is the use of URL as IRI. You can see this in all W3C ontologies definitions, that are included as default context in MD-LD. These prefixes may be used without declaration:
30
+
31
+ ```md
32
+ [rdf] <http://www.w3.org/1999/02/22-rdf-syntax-ns#>
33
+ [rdfs] <http://www.w3.org/2000/01/rdf-schema#>
34
+ [xsd] <http://www.w3.org/2001/XMLSchema#>
35
+ [sh] <http://www.w3.org/ns/shacl#>
36
+ [prov] <http://www.w3.org/ns/prov#>
37
+ ```
38
+
39
+ These are 5 core ontologies - collections of interconnected terms - that lay foundation to the expressive knowledge graphs. You can open the links and read about the terms available in each ontology.
40
+
41
+
42
+ So how do we create an IRI? If you have a web-site or you prefer to use some external authority like your company domain or your own social media account - just use the URL link as IRI and it's good to go - `# Alice {=https://example.org/person/alice .prov:Person label}`
43
+
44
+
45
+ But what if you don't have a domain or just want a local personal namespaced IRI? just use the RFC 4151 format that allows to create private namespace with domain/email or any other authority you may provide - be it an ID in some system or a cryptographic key. The IRI assembles as follows - starts with `tag:`, then we put the authority - domain, email or other, then `,2026-05-04:` - the time when the authority was active. You can also provide only year or only year and month - then it will be assumed that you were owning the authority on 1st day of the month/year. Then you may add a custom subspace `journal/` and here you go - your own tag-based namespace is ready for use.
46
+
47
+ `[journal] <tag:alice.smith@example.org,2026:journal/>`
48
+
49
+ This is your first important line of MD-LD - a prefix declaration - a choice of that particular highlighter color that we need to build or own knowledge graphs.
50
+
51
+ When you write `[prefix]` it holds the short version of the IRI in `<IRI>` and it allows us to author complex IRIs without repeating long strings every time. To generate `http://www.w3.org/ns/prov#Entity` we can use shorter version - `prov:Entity` - 'prov:' is built-in. For everything else - don't forget to declare all prefixes first. This is the key feature of MD-LD - each note is self-contained and can be understood without any external context.
52
+
53
+
54
+
55
+
56
+