mdld-parse 1.0.7 → 1.0.9
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/README.md +379 -83
- package/dist/crawl.js +660 -0
- package/dist/{index.js → mdld-parse.js} +372 -2
- package/dist/quad-graph.js +1219 -0
- package/package.json +9 -4
package/README.md
CHANGED
|
@@ -38,12 +38,27 @@ Human text → Graph immediately
|
|
|
38
38
|
|
|
39
39
|
## 🚀 Quick Start
|
|
40
40
|
|
|
41
|
+
Install the package in Node environment:
|
|
42
|
+
|
|
41
43
|
```bash
|
|
42
44
|
pnpm install mdld-parse
|
|
43
45
|
```
|
|
44
46
|
|
|
47
|
+
Or use `importmap` in the browser:
|
|
48
|
+
|
|
49
|
+
```html
|
|
50
|
+
<script type="importmap">
|
|
51
|
+
{
|
|
52
|
+
"imports": {
|
|
53
|
+
"mdld-parse": "https://mdld.js.org/mdld-parse.js"
|
|
54
|
+
}
|
|
55
|
+
}
|
|
56
|
+
</script>
|
|
57
|
+
```
|
|
58
|
+
|
|
59
|
+
|
|
45
60
|
```javascript
|
|
46
|
-
import { parse, generate, merge } from 'mdld-parse';
|
|
61
|
+
import { parse, generate, merge, render, deconstruct } from 'mdld-parse';
|
|
47
62
|
|
|
48
63
|
// Parse MDLD to RDF quads
|
|
49
64
|
const result = parse({ text: mdldString });
|
|
@@ -55,6 +70,16 @@ console.log(result.origin); // Provenance tracking
|
|
|
55
70
|
// Generate MDLD from quads
|
|
56
71
|
const { text } = generate({ quads: result.quads });
|
|
57
72
|
|
|
73
|
+
// Render to semantic HTML with preserved annotations
|
|
74
|
+
const html = render(mdldString);
|
|
75
|
+
|
|
76
|
+
// Reconstruct MDLD from HTML (lossless roundtrip)
|
|
77
|
+
const reconstructed = deconstruct(html);
|
|
78
|
+
const quads = parse(reconstructed).quads; // Same quads as original!
|
|
79
|
+
|
|
80
|
+
// Lossy rendering for privacy-preserving publishing
|
|
81
|
+
const cleanHtml = render(parse(mdldString).md);
|
|
82
|
+
|
|
58
83
|
// Merge multiple documents (CRDT-style)
|
|
59
84
|
const merged = merge([doc1, doc2, doc3]);
|
|
60
85
|
```
|
|
@@ -85,6 +110,15 @@ MD-LD removes the intermediary. Writing becomes publishing. Publishing becomes g
|
|
|
85
110
|
- **Text-native agent memory** - LLM Agent memory substrate in plain text — parse context, write knowledge, merge with other agents, all as Markdown files. No database required.
|
|
86
111
|
|
|
87
112
|
|
|
113
|
+
## 📚 Documentation Hub
|
|
114
|
+
|
|
115
|
+
- **📋 [Specification](./spec/index.md)** — Formal specification and test suite
|
|
116
|
+
- **📚 [Grammar](./grammar/index.md)** — EBNF+TextMate grammar specifications
|
|
117
|
+
- **📖 [Documentation](./docs/index.md)** — Complete documentation with guides and references
|
|
118
|
+
- **🎯 [Examples](./examples/index.md)** — Real-world MD-LD examples and use cases
|
|
119
|
+
- **💾 [Reference server](./server/index.md)** - a Node.js implementation of the server for git-powered semantic workflows and publishing
|
|
120
|
+
- **🧩 [Ontologies](./ontologies/index.md)** — W3C and related standard ontologies used in RDF
|
|
121
|
+
|
|
88
122
|
### Real-World Applications
|
|
89
123
|
|
|
90
124
|
#### Personal Knowledge Management
|
|
@@ -128,6 +162,15 @@ Authored by [Alice Johnson] {+alice:alice-johnson ?alice:author} on [2026-08-12]
|
|
|
128
162
|
[MD-LD] {blog:emphasized} allows you to embed RDF directly in Markdown.
|
|
129
163
|
```
|
|
130
164
|
|
|
165
|
+
#### Local-First Personal Knowledge Base
|
|
166
|
+
```markdown
|
|
167
|
+
[alice] <tag:alice@example.com,2026:>
|
|
168
|
+
|
|
169
|
+
# Meeting with Bob {=alice:meeting-2026-01-21 .Meeting label}
|
|
170
|
+
Attendees: [Alice] {=alice:alice}, [Bob] {+alice:bob ?attendees}
|
|
171
|
+
Location: [Coffee Shop] {alice:location}
|
|
172
|
+
Discussed [Project Alpha] {alice:discussed}
|
|
173
|
+
|
|
131
174
|
## ✨ Core Features
|
|
132
175
|
|
|
133
176
|
- **🔗 Prefix folding** — Build hierarchical namespaces with CURIE-based IRI authoring
|
|
@@ -143,8 +186,9 @@ Authored by [Alice Johnson] {+alice:alice-johnson ?alice:author} on [2026-08-12]
|
|
|
143
186
|
- **🎯 Elevated statements** — Automatic rdf:Statement pattern detection
|
|
144
187
|
- **🏷️ Primary metadata quartet** — Subject, type, label, comment for document identity
|
|
145
188
|
- **🔄 Round-trip safety** — Deterministic parse ↔ generate cycles
|
|
189
|
+
- **🌐 HTML Codec** — Lossless `render()` and `deconstruct()` pair for web publishing
|
|
146
190
|
|
|
147
|
-
**Bundle size:**
|
|
191
|
+
**Bundle size:** 101KB unminified, 24KB gzipped
|
|
148
192
|
|
|
149
193
|
## 📦 Installation
|
|
150
194
|
|
|
@@ -442,6 +486,300 @@ Locate quad origin entry for UI navigation.
|
|
|
442
486
|
|
|
443
487
|
**Returns:** `{ blockId, range, valueRange, carrierType, ... }` or `null`
|
|
444
488
|
|
|
489
|
+
### `render(mdld, options?)`
|
|
490
|
+
|
|
491
|
+
Convert MD-LD to semantic HTML with preserved annotations.
|
|
492
|
+
|
|
493
|
+
**Parameters:**
|
|
494
|
+
- `mdld` (string, required) — MD-LD formatted text
|
|
495
|
+
- `options` (object, optional):
|
|
496
|
+
- `context` (object) — Additional prefix mappings
|
|
497
|
+
|
|
498
|
+
**Returns:** `string` — Semantic HTML with `data-annotation` attributes
|
|
499
|
+
|
|
500
|
+
**Features:**
|
|
501
|
+
- Preserves complete MD-LD syntax in `data-annotation` for roundtrip reconstruction
|
|
502
|
+
- Resolves IRIs into `data-iri` attributes for easy querying
|
|
503
|
+
- Adds semantic CSS classes: `.mdld-heading`, `.mdld-link`, `.typed`, `.retracted`
|
|
504
|
+
- Platform-agnostic: works in Node.js, Deno, browsers, edge workers
|
|
505
|
+
|
|
506
|
+
**Example:**
|
|
507
|
+
```javascript
|
|
508
|
+
const html = render('# Alice {=ex:alice .Person label}');
|
|
509
|
+
```
|
|
510
|
+
produces
|
|
511
|
+
```html
|
|
512
|
+
<h1 class="mdld-heading typed"
|
|
513
|
+
data-annotation="{=ex:alice .Person label}"
|
|
514
|
+
data-iri="http://example.org/alice">Alice</h1>
|
|
515
|
+
```
|
|
516
|
+
|
|
517
|
+
### `deconstruct(html)`
|
|
518
|
+
|
|
519
|
+
Reconstruct MD-LD from rendered HTML via pure string scanning.
|
|
520
|
+
|
|
521
|
+
**Parameters:**
|
|
522
|
+
- `html` (string, required) — HTML produced by `render()`
|
|
523
|
+
|
|
524
|
+
**Returns:** `string` — Reconstructed MD-LD text
|
|
525
|
+
|
|
526
|
+
**Roundtrip invariant:**
|
|
527
|
+
```javascript
|
|
528
|
+
parse(deconstruct(render(mdld))).quads === parse(mdld).quads
|
|
529
|
+
```
|
|
530
|
+
|
|
531
|
+
**Example:**
|
|
532
|
+
```javascript
|
|
533
|
+
const html = '<h1 data-annotation="{=ex:alice .Person label}">Alice</h1>';
|
|
534
|
+
const mdld = deconstruct(html);
|
|
535
|
+
// # Alice {=ex:alice .Person label}
|
|
536
|
+
```
|
|
537
|
+
|
|
538
|
+
**Use cases:**
|
|
539
|
+
- Server-side rendering: render MD-LD to HTML, send to client
|
|
540
|
+
- Client-side graph extraction: `parse(deconstruct(document.body.innerHTML))`
|
|
541
|
+
- Offline-first apps: cache HTML, reconstruct quads on demand
|
|
542
|
+
|
|
543
|
+
## 🎨 Graph Visualization — `<quad-graph>`
|
|
544
|
+
|
|
545
|
+
Visualize your RDF quads as an interactive force-directed graph with the zero-dependency `<quad-graph>` web component.
|
|
546
|
+
|
|
547
|
+
### Quick Start
|
|
548
|
+
|
|
549
|
+
```html
|
|
550
|
+
<!DOCTYPE html>
|
|
551
|
+
<html>
|
|
552
|
+
<head>
|
|
553
|
+
<script type="importmap">
|
|
554
|
+
{
|
|
555
|
+
"imports": {
|
|
556
|
+
"mdld-parse": "https://mdld.js.org/mdld-parse.js",
|
|
557
|
+
"quad-graph": "https://mdld.js.org/quad-graph.js"
|
|
558
|
+
}
|
|
559
|
+
}
|
|
560
|
+
</script>
|
|
561
|
+
</head>
|
|
562
|
+
<body>
|
|
563
|
+
<quad-graph height="600"></quad-graph>
|
|
564
|
+
<script type="module">
|
|
565
|
+
import { parse } from 'mdld-parse';
|
|
566
|
+
import 'quad-graph'
|
|
567
|
+
const graph = document.querySelector('quad-graph');
|
|
568
|
+
|
|
569
|
+
const mdld = `[ex] <tag:example.org,2026:>
|
|
570
|
+
# Alice {=ex:alice .prov:Person label}
|
|
571
|
+
[Alice] {ex:name} knows [Bob] {+ex:bob ?ex:knows}`;
|
|
572
|
+
|
|
573
|
+
const result = parse({ text: mdld });
|
|
574
|
+
graph.context = result.context
|
|
575
|
+
graph.quads = result.quads;
|
|
576
|
+
</script>
|
|
577
|
+
</body>
|
|
578
|
+
</html>
|
|
579
|
+
```
|
|
580
|
+
|
|
581
|
+
### Browser Console Usage
|
|
582
|
+
|
|
583
|
+
```javascript
|
|
584
|
+
// Load the modules directly
|
|
585
|
+
const mdld = await import('https://mdld.js.org/mdld-parse.js');
|
|
586
|
+
const graph = await import('https://mdld.js.org/quad-graph.js');
|
|
587
|
+
|
|
588
|
+
// Create and configure the graph
|
|
589
|
+
const quadGraph = document.createElement('quad-graph');
|
|
590
|
+
quadGraph.height = '600';
|
|
591
|
+
document.body.appendChild(quadGraph);
|
|
592
|
+
|
|
593
|
+
// Parse and visualize
|
|
594
|
+
const result = mdld.parse({ text: yourMdldString });
|
|
595
|
+
quadGraph.context = result.context;
|
|
596
|
+
quadGraph.quads = result.quads;
|
|
597
|
+
```
|
|
598
|
+
|
|
599
|
+
### Installation
|
|
600
|
+
|
|
601
|
+
```bash
|
|
602
|
+
pnpm install mdld-parse
|
|
603
|
+
```
|
|
604
|
+
|
|
605
|
+
```javascript
|
|
606
|
+
import { parse } from 'mdld-parse';
|
|
607
|
+
import 'mdld-parse/quad-graph'; // Registers <quad-graph> custom element
|
|
608
|
+
```
|
|
609
|
+
|
|
610
|
+
### Features
|
|
611
|
+
|
|
612
|
+
- **Zero dependencies** — Pure Canvas2D rendering, ~650 LOC
|
|
613
|
+
- **Interactive** — Wheel/pinch zoom, drag background to pan, drag nodes to move, double-click to pin/unpin
|
|
614
|
+
- **Force-directed layout** — Barnes-Hut quadtree for performance, time-sliced across frames
|
|
615
|
+
- **Collision-free labels** — Greedy placement with viewport culling
|
|
616
|
+
- **Dark theme** — High contrast light text on dark background
|
|
617
|
+
- **Customizable** — Attributes for height, charge, link distance, labels
|
|
618
|
+
- **API methods** — `focus(iri)`, `select(iri)`, `fit()`, `pin(iri, on)`, `reheat()`, `getNode(iri)`
|
|
619
|
+
|
|
620
|
+
### Attributes
|
|
621
|
+
|
|
622
|
+
| Attribute | Default | Description |
|
|
623
|
+
|-----------|---------|-------------|
|
|
624
|
+
| `height` | `480px` | Component height |
|
|
625
|
+
| `charge` | `40` | Repulsion force between nodes |
|
|
626
|
+
| `link-dist` | `45` | Preferred link length |
|
|
627
|
+
| `labels` | `on` | Set to `"off"` to hide labels |
|
|
628
|
+
|
|
629
|
+
### API Methods
|
|
630
|
+
|
|
631
|
+
```javascript
|
|
632
|
+
const graph = document.querySelector('quad-graph');
|
|
633
|
+
|
|
634
|
+
// Focus on a specific node
|
|
635
|
+
graph.focus('http://example.org/alice');
|
|
636
|
+
|
|
637
|
+
// Select a node
|
|
638
|
+
graph.select('http://example.org/bob');
|
|
639
|
+
|
|
640
|
+
// Fit graph to viewport
|
|
641
|
+
graph.fit();
|
|
642
|
+
|
|
643
|
+
// Pin/unpin a node
|
|
644
|
+
graph.pin('http://example.org/alice', true);
|
|
645
|
+
|
|
646
|
+
// Reheat the simulation
|
|
647
|
+
graph.reheat();
|
|
648
|
+
|
|
649
|
+
// Get node data
|
|
650
|
+
const nodeData = graph.getNode('http://example.org/alice');
|
|
651
|
+
// { id, label, x, y, degree, pinned, type, literals }
|
|
652
|
+
```
|
|
653
|
+
|
|
654
|
+
### Events
|
|
655
|
+
|
|
656
|
+
```javascript
|
|
657
|
+
graph.addEventListener('node-click', (e) => {
|
|
658
|
+
console.log('Clicked:', e.detail); // IRI string
|
|
659
|
+
});
|
|
660
|
+
|
|
661
|
+
graph.addEventListener('node-select', (e) => {
|
|
662
|
+
console.log('Selected:', e.detail); // IRI string or null
|
|
663
|
+
});
|
|
664
|
+
|
|
665
|
+
graph.addEventListener('node-hover', (e) => {
|
|
666
|
+
console.log('Hovered:', e.detail); // IRI string or null
|
|
667
|
+
});
|
|
668
|
+
|
|
669
|
+
graph.addEventListener('settled', () => {
|
|
670
|
+
console.log('Layout settled');
|
|
671
|
+
});
|
|
672
|
+
```
|
|
673
|
+
|
|
674
|
+
## Styling by Type
|
|
675
|
+
|
|
676
|
+
Use CSS attribute selectors to style elements by their RDF types:
|
|
677
|
+
|
|
678
|
+
```css
|
|
679
|
+
/* Style all Person entities */
|
|
680
|
+
[data-iri$="Person"] { color: green; }
|
|
681
|
+
|
|
682
|
+
/* Style all Recipe entities */
|
|
683
|
+
[data-types*="Recipe"] { background: #fff3cd; }
|
|
684
|
+
|
|
685
|
+
/* Style entities with specific IRI */
|
|
686
|
+
[data-iri="http://example.org/alice"] { font-weight: bold; }
|
|
687
|
+
```
|
|
688
|
+
|
|
689
|
+
## 🕸️ Crawling the graph — `crawl.js`
|
|
690
|
+
|
|
691
|
+
MD-LD documents link to each other with ordinary Markdown links, so the graph
|
|
692
|
+
is already on the wire — you just need to follow it. `crawl.js` is a
|
|
693
|
+
**zero-dependency crawler primitive** that does exactly that: fetch raw text,
|
|
694
|
+
extract links, recurse. It knows nothing about MD-LD — the parser is applied at
|
|
695
|
+
the call site, which keeps the core pure and the crawler reusable for *any*
|
|
696
|
+
linked text format.
|
|
697
|
+
|
|
698
|
+
New in **v1.0.9**. Ships as a separate entry point (`mdld-parse/crawl`) and is
|
|
699
|
+
self-contained enough to load straight from the browser console — no bundler,
|
|
700
|
+
no build step:
|
|
701
|
+
|
|
702
|
+
```js
|
|
703
|
+
// Browser console, on any MD-LD site
|
|
704
|
+
const { crawl } = await import('/crawl.js');
|
|
705
|
+
const { pages, errors } = await crawl('/index.md', { sameOrigin: true });
|
|
706
|
+
console.table(pages.map(p => ({ url: p.url, depth: p.depth, links: p.links.length })));
|
|
707
|
+
```
|
|
708
|
+
|
|
709
|
+
```js
|
|
710
|
+
// Node ≥ 18 / Deno / Bun
|
|
711
|
+
import { crawl } from 'mdld-parse/crawl';
|
|
712
|
+
const { pages } = await crawl('https://mdld.js.org/index.md', { maxPages: 25 });
|
|
713
|
+
```
|
|
714
|
+
|
|
715
|
+
Full pipeline — crawl the graph, parse every document into its own named graph:
|
|
716
|
+
|
|
717
|
+
```js
|
|
718
|
+
import { crawl } from 'mdld-parse/crawl';
|
|
719
|
+
import { parse, deconstruct } from 'mdld-parse';
|
|
720
|
+
|
|
721
|
+
const { pages } = await crawl('/index.md', { sameOrigin: true, cache: myCache });
|
|
722
|
+
|
|
723
|
+
const results = pages.map(p => parse({
|
|
724
|
+
text: p.kind === 'html' ? deconstruct(p.text) : p.text, // HTML is a first-class transport
|
|
725
|
+
graph: p.finalUrl, // redirect-correct document identity
|
|
726
|
+
}));
|
|
727
|
+
const quads = results.flatMap(r => r.quads); // the whole crawled graph, provenance intact
|
|
728
|
+
```
|
|
729
|
+
|
|
730
|
+
### What it extracts
|
|
731
|
+
|
|
732
|
+
Both scanners run on **every** document — inline HTML is valid CommonMark, so
|
|
733
|
+
documents are routinely mixed:
|
|
734
|
+
|
|
735
|
+
- **Markdown**: inline links & images `[text](url)`, reference definitions
|
|
736
|
+
`[label]: url`, autolinks `<https://…>`
|
|
737
|
+
- **HTML**: `<a href>` — comment-aware, quote-aware, entities decoded;
|
|
738
|
+
`<script>`/`<style>` contents are skipped
|
|
739
|
+
|
|
740
|
+
Extraction is character-scanned (no regex in hot paths) and context-aware:
|
|
741
|
+
fenced code blocks, code spans and HTML comments never yield phantom links.
|
|
742
|
+
|
|
743
|
+
### Options
|
|
744
|
+
|
|
745
|
+
| Option | Default | Description |
|
|
746
|
+
| --- | --- | --- |
|
|
747
|
+
| `maxDepth` | `5` | Maximum link distance from the start document |
|
|
748
|
+
| `maxPages` | `100` | Hard cap on fetched pages — untrusted graphs can't balloon the crawl |
|
|
749
|
+
| `concurrency` | `5` | Maximum in-flight fetches |
|
|
750
|
+
| `sameOrigin` | `false` | Restrict the crawl to the start document's origin |
|
|
751
|
+
| `cache` | `memoryCache()` | Any `{ get, set, delete? }` adapter |
|
|
752
|
+
| `fetchFn` | `globalThis.fetch` | Wrap for retries, auth, proxies, rate limits |
|
|
753
|
+
| `accept` | docs extensions | `(url) => boolean` target filter |
|
|
754
|
+
| `onPage` | — | Per-page callback — parse incrementally while the crawl is in flight |
|
|
755
|
+
| `signal` | — | `AbortSignal` — cancels and resolves with partial results |
|
|
756
|
+
|
|
757
|
+
### Cache
|
|
758
|
+
|
|
759
|
+
Caching is a three-method interface — bring your own storage:
|
|
760
|
+
|
|
761
|
+
```js
|
|
762
|
+
const cache = {
|
|
763
|
+
async get(url) { /* → { text, etag, lastModified, ... } | null */ },
|
|
764
|
+
async set(url, entry) { /* persist */ },
|
|
765
|
+
async delete(url) { /* evict */ },
|
|
766
|
+
};
|
|
767
|
+
```
|
|
768
|
+
|
|
769
|
+
Conditional requests are automatic: stored `ETag` / `Last-Modified` are re-sent
|
|
770
|
+
as validators, `304` responses cost zero bytes and zero re-parse, and on 5xx or
|
|
771
|
+
network failure the cached copy is served (stale-if-error). Cache failures are
|
|
772
|
+
swallowed — a broken adapter (e.g. Safari private mode) degrades to "no cache",
|
|
773
|
+
never to a failed crawl. Drop-in adapters for IndexedDB, localStorage and Node
|
|
774
|
+
JSON-file caching live in `docs/cache-adapters.md`.
|
|
775
|
+
|
|
776
|
+
### Guarantees
|
|
777
|
+
|
|
778
|
+
- **Deterministic** — pages return in BFS discovery order, never completion order
|
|
779
|
+
- **Bounded** — `maxDepth`, `maxPages`, http(s)-only protocol allow-list, binary content-types rejected
|
|
780
|
+
- **Partial-result-safe** — errors are collected in `result.errors`; the crawl continues
|
|
781
|
+
- **Cancellable** — `AbortSignal` yields `{ aborted: true }` plus everything fetched so far
|
|
782
|
+
|
|
445
783
|
### Utility Functions
|
|
446
784
|
|
|
447
785
|
```javascript
|
|
@@ -458,13 +796,14 @@ import {
|
|
|
458
796
|
## 🏗️ Architecture
|
|
459
797
|
|
|
460
798
|
### Design Principles
|
|
461
|
-
- **Zero dependencies** — Pure JavaScript,
|
|
799
|
+
- **Zero dependencies** — Pure JavaScript, 101KB unminified (24KB gzipped)
|
|
462
800
|
- **Streaming-first** — Single-pass parsing, O(n) complexity
|
|
463
801
|
- **Character-based tokenization** — 20-28% faster than regex-based approaches
|
|
464
802
|
- **Standards-compliant** — RDF/JS data model, W3C CURIE 1.0 syntax
|
|
465
803
|
- **Deterministic** — Same input always produces same output
|
|
466
804
|
- **Explicit semantics** — No guessing, inference, or heuristics
|
|
467
805
|
- **Dual-layer origin** — Every parse emits both a semantic quad graph and a walkable textual topology graph simultaneously
|
|
806
|
+
- **HTML as codec** — Lossless roundtrip between MD-LD and HTML via `render()`/`deconstruct()`
|
|
468
807
|
|
|
469
808
|
### Origin: Blocks and Spans
|
|
470
809
|
|
|
@@ -479,6 +818,42 @@ The parser output includes a complete document chain at no extra cost:
|
|
|
479
818
|
|
|
480
819
|
Spans store no text — content is always recovered via `sourceText.slice(span.range[0], span.range[1])`. This unlocks context-aware UI, autocomplete neighborhood retrieval, and cross-document topology without any parser-level interpretation.
|
|
481
820
|
|
|
821
|
+
### HTML Codec: Server/Client Equivalence
|
|
822
|
+
|
|
823
|
+
The `render()` and `deconstruct()` pair enables two equivalent workflows:
|
|
824
|
+
|
|
825
|
+
**Server-Side Rendering (SSR):**
|
|
826
|
+
```
|
|
827
|
+
MD-LD files → render() → HTML → Browser
|
|
828
|
+
↓
|
|
829
|
+
deconstruct() → parse() → quads
|
|
830
|
+
```
|
|
831
|
+
|
|
832
|
+
**Client-Side Rendering (CSR):**
|
|
833
|
+
```
|
|
834
|
+
MD-LD files → Browser → render() → HTML
|
|
835
|
+
↓
|
|
836
|
+
deconstruct() → parse() → quads
|
|
837
|
+
```
|
|
838
|
+
|
|
839
|
+
Both modes produce identical quads. The choice depends on your deployment model:
|
|
840
|
+
- **SSR:** Better for SEO, faster initial page load, works without JavaScript
|
|
841
|
+
- **CSR:** Better for offline-first apps, reduces server load, enables dynamic updates
|
|
842
|
+
|
|
843
|
+
**Bandwidth optimization:**
|
|
844
|
+
- Full fidelity: `render(mdld)` includes `data-annotation` for roundtrip
|
|
845
|
+
- Lossy mode: `render(parse(mdld).md)` strips annotations for privacy-preserving publishing
|
|
846
|
+
- HTML payload is 2-3x smaller than MD-LD + JSON-LD combination
|
|
847
|
+
|
|
848
|
+
**Use cases:**
|
|
849
|
+
- Personal knowledge bases (Obsidian-like, web-native)
|
|
850
|
+
- Community wikis with semantic search
|
|
851
|
+
- Offline-first research notes with citations
|
|
852
|
+
- Collaborative task management with provenance
|
|
853
|
+
- Reading lists that become knowledge graphs
|
|
854
|
+
- Meeting notes with automatic linking
|
|
855
|
+
- Decentralized community event calendars
|
|
856
|
+
|
|
482
857
|
### Performance Characteristics
|
|
483
858
|
- **Real-time (60fps):** Up to 4,527 quads per frame
|
|
484
859
|
- **Batch processing:** Up to 225,059 quads per second
|
|
@@ -512,89 +887,10 @@ Comprehensive test suite covering:
|
|
|
512
887
|
- Elevated statements detection
|
|
513
888
|
- Primary metadata extraction
|
|
514
889
|
- Round-trip parse/generate cycles
|
|
890
|
+
- HTML codec roundtrip — `mdld = deconstruct(render(mdld))`
|
|
515
891
|
- Origin tracking and provenance
|
|
516
892
|
|
|
517
893
|
|
|
518
|
-
## 📚 Documentation Hub
|
|
519
|
-
|
|
520
|
-
- **📋 [Specification](./spec/index.md)** — Formal specification and test suite
|
|
521
|
-
- [Formal Specification](./spec/Spec.md)
|
|
522
|
-
- [Compact Spec](./spec/Spec-compact.md)
|
|
523
|
-
- [Ultra Compact Spec](./spec/Spec-ultra.md)
|
|
524
|
-
|
|
525
|
-
- **📚 [Grammar](./grammar/index.md)** — EBNF+TextMate grammar specifications
|
|
526
|
-
- [The TextMate grammar](./grammar/mdld.tmLanguage.json)
|
|
527
|
-
- [ISO 14977 EBNF grammar](./grammar/mdld.ebnf)
|
|
528
|
-
|
|
529
|
-
- **📖 [Documentation](./docs/index.md)** — Complete documentation with guides and references
|
|
530
|
-
- [MD-LD Authoring Guide](./docs/Guide.md)
|
|
531
|
-
- [One Page Guide](./docs/one-page.md)
|
|
532
|
-
- [Semantic Infrastructure as Readable Text](./docs/Semantic-Text.md)
|
|
533
|
-
- [Elevated Statements](./docs/statements.md)
|
|
534
|
-
- [Primary Metadata System](./docs/primary-subject.md)
|
|
535
|
-
- [Origin System](./docs/origin.md)
|
|
536
|
-
- [Polarity & Retraction](./docs/polarity.md)
|
|
537
|
-
- [Subject System](./docs/Subject.md)
|
|
538
|
-
- [API Reference](./docs/API.md)
|
|
539
|
-
- [Generate: Quads to MDLD](./docs/generate.md)
|
|
540
|
-
- [Diff Documents](./docs/diff.md)
|
|
541
|
-
- [Syntax Reference](./docs/Syntax.md)
|
|
542
|
-
- [Architecture & Design](./docs/Architecture.md)
|
|
543
|
-
- [Parser Architecture](./docs/Parser.md)
|
|
544
|
-
- [Performance Benchmarks](./docs/Performance.md)
|
|
545
|
-
- [Token Efficiency](./docs/Token-Efficiency.md)
|
|
546
|
-
- [Knowledge Round Trip](./docs/Knowledge-Round-Trip.md)
|
|
547
|
-
- [Human-Scale Software & Semantic Infrastructure](./docs/Human-Scale.md)
|
|
548
|
-
- [Quad[] as a Universal Semantic Runtime](./docs/quad-runtime.md)
|
|
549
|
-
- [Use Cases](./docs/Use-Cases.md)
|
|
550
|
-
|
|
551
|
-
- **🎯 [Examples](./examples/index.md)** — Real-world MD-LD examples and use cases
|
|
552
|
-
- [Minimal](./examples/demo/minimal.md)
|
|
553
|
-
- [One-Page Guide](./examples/one-page.md)
|
|
554
|
-
- [Few-Shot Examples](./examples/few-shot.md)
|
|
555
|
-
- [Journal](./examples/demo/journal.md)
|
|
556
|
-
- [Tasks](./examples/demo/tasks.md)
|
|
557
|
-
- [Medical AI Research](./examples/demo/research.md)
|
|
558
|
-
- [Cookbook](./examples/Cookbook.md)
|
|
559
|
-
- [Website Redesign Project](./examples/demo/project.md)
|
|
560
|
-
- [Task Management System](./examples/demo/tasks.md)
|
|
561
|
-
- [Cassini-Huygens Mission](./examples/demo/space-mission.md)
|
|
562
|
-
- [RDF Fundamentals](./examples/demo/rdf.md)
|
|
563
|
-
- [PROV-O Patterns](./examples/demo/prov.md)
|
|
564
|
-
- [SHACL Validation](./examples/demo/shacl.md)
|
|
565
|
-
- [XSD Datatypes](./examples/demo/xsd.md)
|
|
566
|
-
- [Status & SHACL Validation](./examples/Status-SHACL.md)
|
|
567
|
-
- [LLM Time Workflow](./examples/llm-time-workflow.md)
|
|
568
|
-
- [Research Workflow](./examples/workflow.md)
|
|
569
|
-
- [Dogfood](./examples/dogfood.md)
|
|
570
|
-
|
|
571
|
-
- **💻 [Reference server](./server/index.md) - a Node.js implementation of the server for git-powered semantic workflows and publishing
|
|
572
|
-
- [Source code](./server/mdld-server.js)
|
|
573
|
-
|
|
574
|
-
- **🧩 [Ontologies](./ontologies/index.md)** — W3C and related standard ontologies used in RDF
|
|
575
|
-
- [RDF — Resource Description Framework](./ontologies/rdf.md)
|
|
576
|
-
- [RDFS — RDF Schema](./ontologies/rdfs.md)
|
|
577
|
-
- [SHACL — Shapes Constraint Language](./ontologies/shacl.md)
|
|
578
|
-
- [PROV-O — W3C Provenance Ontology](./ontologies/prov-o.md)
|
|
579
|
-
- [XSD — XML Schema Definition Datatypes](./ontologies/xsd.md)
|
|
580
|
-
- [DCTERMS — Dublin Core Metadata Terms](./ontologies/dcterms.md)
|
|
581
|
-
- [DCAT — Data Catalog Vocabulary](./ontologies/dcat.md)
|
|
582
|
-
- [FOAF — Friend of a Friend](./ontologies/foaf.md)
|
|
583
|
-
- [VCard](./ontologies/vcard.md)
|
|
584
|
-
- [Time — OWL-Time Ontology](./ontologies/time.md)
|
|
585
|
-
- [Activity Streams 2.0](./ontologies/activity-streams-2.md)
|
|
586
|
-
- [SKOS — Simple Knowledge Organization System](./ontologies/skos.md)
|
|
587
|
-
- [Schema.org](./ontologies/schemaorg.md)
|
|
588
|
-
- [CIDOC CRM — Conceptual Reference Model](./ontologies/cidoc_crm.md)
|
|
589
|
-
- [SOSA — Sensor, Observation, Sample, and Actuator](./ontologies/sosa.md)
|
|
590
|
-
- [QUDT — Quantities, Units, Dimensions and Types](./ontologies/qudt.md)
|
|
591
|
-
- [GOLD — General Ontology for Linguistic Description](./ontologies/gold.md)
|
|
592
|
-
- [LexInfo — Lexical Information Ontology](./ontologies/lexinfo.md)
|
|
593
|
-
- [OWL — Web Ontology Language](./ontologies/owl.md)
|
|
594
|
-
- [P-PLAN — Plan Ontology](./ontologies/p-plan.md)
|
|
595
|
-
- [Hydra — Hypermedia API Vocabulary](./ontologies/hydra.md)
|
|
596
|
-
- [Web Annotations](./ontologies/web-annotations.md)
|
|
597
|
-
|
|
598
894
|
## Governance
|
|
599
895
|
|
|
600
896
|
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.
|