mdparser/README.md

📚 MDParser - Markdown to JSON Parser

Ein modularer Parser für Markdown-Dateien mit YAML Front Matter, optimiert für AMB-Metadatenstandard (schema.org) und Transformation zu WordPress & Nostr.

🎯 Features

• ✅ YAML Front Matter Parsing - Volle Unterstützung für komplexe YAML-Strukturen
• ✅ AMB-Metadaten - Schema.org-konforme Metadaten-Extraktion
• ✅ Forgejo/Gitea API - Direkter Zugriff auf Git-Repository-Inhalte
• ✅ AST-basiert - Strukturierte Markdown-Verarbeitung mit unified/remark
• ✅ Isomorph - Funktioniert in Node.js und im Browser
• ✅ Erweiterbar - Modulare Architektur für Custom-Transformationen
• 🚧 WordPress REST API v2 - Transformer (geplant)
• 🚧 Nostr NIP-23 - Long-form Content Transformer (geplant)

📦 Installation

# Repository klonen
git clone https://git.rpi-virtuell.de/Comenius-Institut/mdparser.git
cd mdparser

# Dependencies installieren
npm install

# Environment-Variablen konfigurieren
cp .env.example .env
# .env bearbeiten und API-Zugangsdaten eintragen

🚀 Quick Start

import { parseMarkdownFile } from './src/parser.js';

// Markdown mit YAML Front Matter parsen
const result = await parseMarkdownFile('./content/posts/example/index.md');

console.log(result.metadata);  // Schema.org Metadaten
console.log(result.content);   // Markdown AST
console.log(result.html);      // HTML-Output (optional)

🏗️ Projekt-Struktur

mdparser/
├── src/
│   ├── index.js              # Haupteinstiegspunkt
│   ├── parser.js             # Core Parser (unified/remark)
│   ├── forgejo-client.js     # Forgejo API Client
│   ├── extractors/
│   │   ├── yaml-extractor.js # YAML Front Matter Parsing
│   │   └── amb-extractor.js  # AMB/Schema.org Metadaten
│   └── transformers/         # (geplant)
│       ├── wordpress.js
│       └── nostr.js
├── examples/
│   ├── parse-forgejo.js      # Beispiel: Forgejo API
│   ├── parse-local.js        # Beispiel: Lokale Datei
│   └── parse-url.js          # Beispiel: HTTP URL
├── test/
│   └── parser.test.js
├── docs/
│   ├── ARCHITECTURE.md       # Architektur-Dokumentation
│   ├── API.md               # API-Referenz
│   └── DECISIONS.md         # Design-Entscheidungen
├── .env.example
├── .gitignore
├── .editorconfig
├── package.json
└── README.md

🔧 Konfiguration

Environment-Variablen (.env)

# Forgejo/Gitea API
FORGEJO_API_BASE_URL=https://git.rpi-virtuell.de/api/v1
FORGEJO_OWNER=Comenius-Institut
FORGEJO_REPO=FOERBICO_und_rpi-virtuell
FORGEJO_BRANCH=main
FORGEJO_TOKEN=                    # Optional für private Repos

# API Rate Limiting
API_RATE_LIMIT_DELAY_MS=100

# Logging
LOG_LEVEL=info

📖 Verwendung

1. Lokale Markdown-Datei parsen

import { parseMarkdownFile } from './src/parser.js';

const result = await parseMarkdownFile('./content/post/index.md');
console.log(result);

2. Forgejo API verwenden

import { ForgejoClient } from './src/forgejo-client.js';

const client = new ForgejoClient({
  baseUrl: 'https://git.rpi-virtuell.de/api/v1',
  owner: 'Comenius-Institut',
  repo: 'FOERBICO_und_rpi-virtuell'
});

// Einzelne Datei abrufen
const content = await client.getFileContent(
  'Website/content/posts/2025-04-20-OER-und-Symbole/index.md'
);

// Alle Posts auflisten
const posts = await client.listPosts('Website/content/posts');

3. AMB-Metadaten extrahieren

import { extractAMBMetadata } from './src/extractors/amb-extractor.js';

const ambData = extractAMBMetadata(result.yaml);

// Ausgabe: Schema.org-konforme Struktur
console.log(ambData.name);        // Titel
console.log(ambData.creator);     // Autoren
console.log(ambData.license);     // Lizenz
console.log(ambData.about);       // Themen/Tags

🎓 AMB-Metadatenstandard

Dieses Projekt unterstützt den AMB-Standard (Metadaten für Bildungsressourcen) basierend auf schema.org:

Unterstützte Felder:

• @context, type, name, description
• creator (Person/Organization mit ORCID/ROR)
• license, inLanguage, datePublished
• about (Hochschulfächersystematik)
• learningResourceType, educationalLevel
• image, id (URL)

Siehe AMB-Dokumentation für Details.

🔌 API-Referenz

parseMarkdownFile(filePath, options)

Parst eine Markdown-Datei mit YAML Front Matter.

Parameter:

• filePath (string) - Pfad zur Markdown-Datei
• options (object) - Optionale Konfiguration
  • extractYaml (boolean) - YAML extrahieren (default: true)
  • parseGfm (boolean) - GitHub Flavored Markdown (default: true)
  • toHtml (boolean) - HTML-Output generieren (default: false)

Rückgabe:

{
  yaml: { /* YAML Front Matter als Objekt */ },
  metadata: { /* Extrahierte AMB-Metadaten */ },
  ast: { /* Markdown Abstract Syntax Tree */ },
  content: { /* Reiner Content ohne Front Matter */ },
  html: "..." // Optional
}

Siehe docs/API.md für vollständige API-Dokumentation.

🧪 Tests

# Tests ausführen
npm test

# Mit Watch-Mode während Entwicklung
npm run dev

🤝 Entwicklung

Technologie-Stack

Bereich	Bibliothek	Begründung
Markdown Parser	unified + remark-parse	AST-basiert, erweiterbar, isomorph
YAML Parser	yaml	Robust, spec-compliant
Front Matter	remark-frontmatter	Nahtlose Integration mit remark
GFM Support	remark-gfm	Tabellen, Task Lists, etc.
HTTP Client	native fetch	Standard, keine Dependencies

Warum unified/remark?

✅ Isomorph - Node.js + Browser
✅ AST-basiert - Präzise Manipulation
✅ Erweiterbar - Riesiges Plugin-Ökosystem
✅ Standard - MDAST ist De-facto-Standard
✅ Aktiv - Große Community, gute Wartung

Siehe docs/DECISIONS.md für detaillierte Design-Entscheidungen.

📋 Roadmap

Phase 1: Core Parser (aktuell)

• Projekt-Setup mit Git, npm, Dokumentation
• Markdown + YAML Parser implementieren
• Forgejo API Client
• AMB-Metadaten-Extraktor
• Beispiele und Tests

Phase 2: Transformers (nächster Schritt)

• WordPress REST API v2 Transformer
  • title, content, excerpt, featured_media
  • tags, categories, custom fields
  • author mapping
• Nostr NIP-23 Transformer
  • d (identifier), title, summary
  • published_at, image
  • t (tags), e/a/p (references)

Phase 3: Erweiterte Features

• Browser-Build (ESM)
• CLI-Tool
• Batch-Processing
• Caching-Strategie
• Error-Handling & Logging

📄 Lizenz

MIT License - siehe LICENSE für Details.

👥 Autoren

• Jörg Lohrer - ORCID
• Comenius-Institut - ROR

🔗 Links

• Projekt-Repository: https://git.rpi-virtuell.de/Comenius-Institut/mdparser
• Forgejo API: https://git.rpi-virtuell.de/api/swagger
• AMB-Standard: https://dini-ag-kim.github.io/amb/
• unified/remark: https://unifiedjs.com/
• WordPress REST API: https://developer.wordpress.org/rest-api/
• Nostr NIPs: https://github.com/nostr-protocol/nips

---

Status: 🚧 In aktiver Entwicklung - Phase 1