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.
- package/dist/.nojekyll +0 -0
- package/dist/CNAME +1 -0
- package/dist/README.md +425 -0
- package/dist/docs/API.md +397 -0
- package/dist/docs/Architecture.md +190 -0
- package/dist/docs/Guide.md +816 -0
- package/dist/docs/LLM-MDLD-Inducer.md +550 -0
- package/dist/docs/Parser.md +654 -0
- package/dist/docs/Performance.md +238 -0
- package/dist/docs/Spec-render.md +1439 -0
- package/dist/docs/Subject.md +180 -0
- package/dist/docs/Syntax.md +463 -0
- package/dist/docs/TodoList.md +215 -0
- package/dist/docs/Use-Cases.md +354 -0
- package/dist/docs/guide-m.md +56 -0
- package/dist/docs/index.html +108 -0
- package/dist/docs/index.md +56 -0
- package/dist/docs/one-page.md +322 -0
- package/dist/docs/origin.md +459 -0
- package/dist/docs/polarity.md +586 -0
- package/dist/docs/primary-subject.md +199 -0
- package/dist/docs/statements.md +226 -0
- package/dist/docs/tokenization-performance-report.md +164 -0
- package/dist/examples/Cookbook.md +32 -0
- package/dist/examples/Status-SHACL.md +31 -0
- package/dist/examples/demo/index.md +35 -0
- package/dist/examples/demo/journal.md +119 -0
- package/dist/examples/demo/minimal.md +23 -0
- package/dist/examples/demo/project.md +98 -0
- package/dist/examples/demo/prov.md +107 -0
- package/dist/examples/demo/rdf.md +69 -0
- package/dist/examples/demo/recipe.md +95 -0
- package/dist/examples/demo/research.md +126 -0
- package/dist/examples/demo/shacl.md +161 -0
- package/dist/examples/demo/space-mission.md +129 -0
- package/dist/examples/demo/tasks.md +175 -0
- package/dist/examples/demo/xsd.md +91 -0
- package/dist/examples/dogfood.md +288 -0
- package/dist/examples/few-shot.md +309 -0
- package/dist/examples/graph/rdf-graph.html +473 -0
- package/dist/examples/graph/rdf_force_graph_web_component.html +506 -0
- package/dist/examples/index.md +45 -0
- package/dist/examples/llm-time-workflow.md +173 -0
- package/dist/examples/statements.md +43 -0
- package/dist/examples/workflow.md +150 -0
- package/dist/index.html +3253 -0
- package/dist/index.js +1770 -0
- package/dist/logo.svg +7 -0
- package/dist/spec/Spec-compact.md +363 -0
- package/dist/spec/Spec-ultra.md +221 -0
- package/dist/spec/Spec.md +1068 -0
- package/dist/spec/index.md +46 -0
- package/package.json +7 -8
- package/src/constants.js +0 -31
- package/src/generate.js +0 -245
- package/src/highlight.js +0 -362
- package/src/index.js +0 -13
- package/src/locate.js +0 -23
- package/src/merge.js +0 -157
- package/src/parse.js +0 -711
- package/src/render.js +0 -576
- package/src/shared.js +0 -577
- package/src/tokenizers.js +0 -594
- 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
|
+
|