Hyper-markdown (.hmd) is een uitbreiding van de CommonMark-standaard die platte tekst transformeert naar een systeem voor kennisgrafen. De kern van het formaat ligt in de 'hyper-laag', die naamgebaseerde wiki-links en transclusie (het importeren van specifieke blokken uit andere documenten) mogelijk maakt.
Belangrijke kenmerken:
- Rijke inhoud: Ondersteuning voor TeX-wiskunde, D2-diagrammen, callouts en tabellen is standaard aanwezig.
- Specificatie-gestuurd: De HMD Language Specification (versie 0.1) is leidend over de implementaties om consistentie te waarborgen.
- Tooling: Er zijn drie primaire tools beschikbaar: een Python CLI (
hmd) inclusief MkDocs-plugin, een TypeScript-core (hmd-ts-core) en een VS Code-extensie voor live preview en diagnostiek.
De visie is om een coherente specificatie te creëren waardoor onafhankelijk geauteurde documenten over repositories heen kunnen worden verbonden in een web van betekenis, toegankelijk voor zowel mensen als AI.
Hyper-markdown
Kernpunten (TL;DR)
- Een superset van CommonMark: Hernoem een
.md-bestand naar .hmd en het is direct geldig. Er gaat niets kapot en het formaat kan per bestand worden geadopteerd.
- Namen in plaats van paden:
[[tokens]] wordt eerst gezocht naast de huidige kaart en vervolgens omhoog via de bovenliggende mappen. Een naam die naar twee verschillende documenten zou kunnen verwijzen, resulteert in een fout in plaats van een gok.
- Documenten bestaande uit documenten:
![[glossary/token#^definition]] voegt een benoemd blok samen in een andere pagina. Schrijf een definitie één keer en bedig deze overal waar nodig.
- Rijke inhoud is de standaard, geen optie: TeX-wiskunde, D2-diagrammen, callouts, voetnoten, takenlijsten en tabellen maken deel uit van wat een kaart kan bevatten. Een diagram is tekst in het bestand en een leesbare 'diff'; het degradeert tot de eigen gelabelde broncode in plaats van tot een lege ruimte.
- De specificatie is het leidende artefact: De Python CLI, de MkDocs-plugin en de VS Code-extensie zijn implementaties die conform de specificatie zijn; zij definiëren de standaard niet zelf.
- Versie 0.x is een fase, geen reikwijdte: De resolver, linter, embed expander, renderer en MkDocs-plugin werken momenteel. Queries over de documentgraaf en namespaces buiten één boomstructuur zijn gespecificeerd in hoofdlijnen, maar nog niet gebouwd.
Taal
In één bestand stapelen drie lagen zich op. Aan de basis ligt CommonMark, volledig overgenomen; niets is herdefinieerd of verwijderd, wat verklaart waarom een .md-bestand al een geldige kaart is. Daarbovenop ligt een rijke laag — tabellen, voetnoten, takenlijsten, callouts, TeX-wiskunde, D2-diagrammen — ontleend aan het bredere Markdown-ecosysteem in plaats van zelf uitgevonden, en beschouwd als standaard aanwezig.
De bovenste laag is de 'hyper-laag', het meest innovatieve deel en de reden waarom het formaat bestaat: een kleine set constructen die variaties zijn op één idee: het benoemen van een ander document of een deel daarvan. Deze bovenste twee lagen vormen de toevoeging van hyper-markdown, en een specificatie legt deze vast in plaats van conventie.
Voor het formaat kan men kijken naar [[tokens]], of een volledig blok importeren via: ![[glossary/token#^definition]]
Een kaart kan openen met YAML-frontmatter, waarbij vier sleutels betekenis hebben voor de toolchain — tags, use, import, nav — terwijl elke andere sleutel eigendom is van de auteur. De gehele taal past op één pagina en kan in één sessie worden geleerd via de HMD Tutorial; wat daar wordt onderwezen, wordt normatief vastgelegd in de HMD Language Specification.
Functionaliteiten
De taal biedt wiki-links naar documenten, koppen en benoemde blokken, evenals transclusie van deze elementen. Daarnaast bevat het filesystem-vormige modules met expliciete imports, TeX-wiskunde, D2-diagrammen, callouts, inklapbare secties, voetnoten, tabellen en de GitHub-flavored Markdown baseline. HQL, een querytaal over de documentgraaf, is gereserveerd maar nog niet ontworpen.
Tools
De tool hmd voert een linting uit op een boomstructuur, rendert een kaart naar Markdown of HTML, en dumpen de geresolveerde graaf. Een missend doel is een waarschuwing, omdat een wiki groeit door vooruit te schrijven; een ambigu of foutief doel is echter een fout, omdat het formaat weigert hierover te gokken.
Er zijn drie tools beschikbaar, elk in een eigen directory onder tools/ in de repository:
- hmd: De Python-lijn, gepubliceerd op PyPI als
hyper-markdown. Dit omvat de CLI (lint, render, graph), de onderliggende bibliotheek en de MkDocs-plugin die de site bouwt. Dit is de canonieke implementatie; bij onenigheid tussen implementaties is dit de leidende versie. Deze zal ook de language server hosten.
- hmd-ts-core:
@hyper-markdown/core, een tweede implementatie van het formaat in TypeScript, die voldoet aan hetzelfde conformiteitscorpus als de canonieke tool.
- hmd-vsc-ext: De VS Code-extensie (in ontwikkeling), met een live preview die de embed-grenzen zichtbaar houdt, plus backlinks, red links en diagnostiek.
Presentatie is geen onderdeel van de taal. Een kaart is platte tekst, waardoor een editor, GitHub of een chatvenster deze al kan weergeven. De MkDocs-plugin bouwt een boom van kaarten om tot een gepubliceerde site, en de extensie rendert een kaart in de editor terwijl deze wordt getypt.
Specificatie
De normatieve tekst is één document: de HMD Language Specification. Hierin staat wat een kaart is, wat elk construct betekent en wat een implementatie ermee moet doen. Het beschrijft geen specifiek programma; het gedrag van een programma overstijgt de specificatie niet.
Het is vastgesteld tegenover een benoemde baseline — CommonMark 0.31.2 — omdat "markdown" een familie aanduidt in plaats van een standaard. De specificatie is onafhankelijk geversioneerd van de tools; een release van hmd impliceert niet automatisch een nieuwe taalversie. Wanneer implementaties verschillen over zaken die de tekst onbepaald laat, beslist het taal-neutrale conformiteitscorpus.
De taal bevindt zich in versie 0.1. De tekst is in conceptfase en zal wijzigen voor versie 1.0. Wijzigingen worden eerst besproken als genummerde technische voorstellen (HMD-0001, HMD-0002, etc.), vergelijkbaar met RFC's en lichtgewicht ADR's: een probleem, de genomen beslissing, verworpen alternatieven en een eigen tracker. De meeste van deze voorstellen gaan over tools en de presentatielaag (zoals hoe een naam op schijf wordt geresolveerd of wat de linter rapporteert). Bij tegenstrijdigheid is de specificatie altijd leidend.
Visie
Markdown werd de standaard voor platte tekst, maar kreeg nooit de rol die HTML had bij aanvang: links die betekenis hebben omdat ze naar een kennisgraaf wijzen, en pagina's die deel uitmaken van een web in plaats van een bestand in een map. De ideeën hierachter zijn niet nieuw; het doel is om hiervan een coherente specificatie te maken.
De langere visie is dat dit niet beperkt moet blijven tot één repository: onafhankelijk geauteurde en geserveerde hyper-markdown, die over de kloek heen benoemd kunnen worden en gelezen kunnen worden uit dezelfde bron door mensen, tools en AI.
Status
Pre-release. De scanner, resolver, linter, embed expander, renderer en MkDocs-plugin zijn geïmplementeerd en getest. De taal-specificatie is in versie 0.1 en zal nog wijzigen. Het levende voorbeeld is de wiki, gegenereerd uit .hmd-kaarten in deze repository.
Hyper-markdown
Kernpunten (TL;DR)
- Een superset van CommonMark: Hernoem een
.md-bestand naar .hmd en het is direct geldig. Er gaat niets kapot en het formaat kan per bestand worden geadopteerd.
- Namen in plaats van paden:
[[tokens]] wordt eerst gezocht naast de huidige kaart en vervolgens omhoog via de bovenliggende mappen. Een naam die naar twee verschillende documenten zou kunnen verwijzen, resulteert in een fout in plaats van een gok.
- Documenten bestaande uit documenten:
![[glossary/token#^definition]] voegt een benoemd blok samen in een andere pagina. Schrijf een definitie één keer en bedig deze overal waar nodig.
- Rijke inhoud is de standaard, geen optie: TeX-wiskunde, D2-diagrammen, callouts, voetnoten, takenlijsten en tabellen maken deel uit van wat een kaart kan bevatten. Een diagram is tekst in het bestand en een leesbare 'diff'; het degradeert tot de eigen gelabelde broncode in plaats van tot een lege ruimte.
- De specificatie is het leidende artefact: De Python CLI, de MkDocs-plugin en de VS Code-extensie zijn implementaties die conform de specificatie zijn; zij definiëren de standaard niet zelf.
- Versie 0.x is een fase, geen reikwijdte: De resolver, linter, embed expander, renderer en MkDocs-plugin werken momenteel. Queries over de documentgraaf en namespaces buiten één boomstructuur zijn gespecificeerd in hoofdlijnen, maar nog niet gebouwd.
Taal
In één bestand stapelen drie lagen zich op. Aan de basis ligt CommonMark, volledig overgenomen; niets is herdefinieerd of verwijderd, wat verklaart waarom een .md-bestand al een geldige kaart is. Daarbovenop ligt een rijke laag — tabellen, voetnoten, takenlijsten, callouts, TeX-wiskunde, D2-diagrammen — ontleend aan het bredere Markdown-ecosysteem in plaats van zelf uitgevonden, en beschouwd als standaard aanwezig.
De bovenste laag is de 'hyper-laag', het meest innovatieve deel en de reden waarom het formaat bestaat: een kleine set constructen die variaties zijn op één idee: het benoemen van een ander document of een deel daarvan. Deze bovenste twee lagen vormen de toevoeging van hyper-markdown, en een specificatie legt deze vast in plaats van conventie.
Voor het formaat kan men kijken naar [[tokens]], of een volledig blok importeren via: ![[glossary/token#^definition]]
Een kaart kan openen met YAML-frontmatter, waarbij vier sleutels betekenis hebben voor de toolchain — tags, use, import, nav — terwijl elke andere sleutel eigendom is van de auteur. De gehele taal past op één pagina en kan in één sessie worden geleerd via de HMD Tutorial; wat daar wordt onderwezen, wordt normatief vastgelegd in de HMD Language Specification.
Functionaliteiten
De taal biedt wiki-links naar documenten, koppen en benoemde blokken, evenals transclusie van deze elementen. Daarnaast bevat het filesystem-vormige modules met expliciete imports, TeX-wiskunde, D2-diagrammen, callouts, inklapbare secties, voetnoten, tabellen en de GitHub-flavored Markdown baseline. HQL, een querytaal over de documentgraaf, is gereserveerd maar nog niet ontworpen.
Tools
De tool hmd voert een linting uit op een boomstructuur, rendert een kaart naar Markdown of HTML, en dumpen de geresolveerde graaf. Een missend doel is een waarschuwing, omdat een wiki groeit door vooruit te schrijven; een ambigu of foutief doel is echter een fout, omdat het formaat weigert hierover te gokken.
Er zijn drie tools beschikbaar, elk in een eigen directory onder tools/ in de repository:
- hmd: De Python-lijn, gepubliceerd op PyPI als
hyper-markdown. Dit omvat de CLI (lint, render, graph), de onderliggende bibliotheek en de MkDocs-plugin die de site bouwt. Dit is de canonieke implementatie; bij onenigheid tussen implementaties is dit de leidende versie. Deze zal ook de language server hosten.
- hmd-ts-core:
@hyper-markdown/core, een tweede implementatie van het formaat in TypeScript, die voldoet aan hetzelfde conformiteitscorpus als de canonieke tool.
- hmd-vsc-ext: De VS Code-extensie (in ontwikkeling), met een live preview die de embed-grenzen zichtbaar houdt, plus backlinks, red links en diagnostiek.
Presentatie is geen onderdeel van de taal. Een kaart is platte tekst, waardoor een editor, GitHub of een chatvenster deze al kan weergeven. De MkDocs-plugin bouwt een boom van kaarten om tot een gepubliceerde site, en de extensie rendert een kaart in de editor terwijl deze wordt getypt.
Specificatie
De normatieve tekst is één document: de HMD Language Specification. Hierin staat wat een kaart is, wat elk construct betekent en wat een implementatie ermee moet doen. Het beschrijft geen specifiek programma; het gedrag van een programma overstijgt de specificatie niet.
Het is vastgesteld tegenover een benoemde baseline — CommonMark 0.31.2 — omdat "markdown" een familie aanduidt in plaats van een standaard. De specificatie is onafhankelijk geversioneerd van de tools; een release van hmd impliceert niet automatisch een nieuwe taalversie. Wanneer implementaties verschillen over zaken die de tekst onbepaald laat, beslist het taal-neutrale conformiteitscorpus.
De taal bevindt zich in versie 0.1. De tekst is in conceptfase en zal wijzigen voor versie 1.0. Wijzigingen worden eerst besproken als genummerde technische voorstellen (HMD-0001, HMD-0002, etc.), vergelijkbaar met RFC's en lichtgewicht ADR's: een probleem, de genomen beslissing, verworpen alternatieven en een eigen tracker. De meeste van deze voorstellen gaan over tools en de presentatielaag (zoals hoe een naam op schijf wordt geresolveerd of wat de linter rapporteert). Bij tegenstrijdigheid is de specificatie altijd leidend.
Visie
Markdown werd de standaard voor platte tekst, maar kreeg nooit de rol die HTML had bij aanvang: links die betekenis hebben omdat ze naar een kennisgraaf wijzen, en pagina's die deel uitmaken van een web in plaats van een bestand in een map. De ideeën hierachter zijn niet nieuw; het doel is om hiervan een coherente specificatie te maken.
De langere visie is dat dit niet beperkt moet blijven tot één repository: onafhankelijk geauteurde en geserveerde hyper-markdown, die over de kloek heen benoemd kunnen worden en gelezen kunnen worden uit dezelfde bron door mensen, tools en AI.
Status
Pre-release. De scanner, resolver, linter, embed expander, renderer en MkDocs-plugin zijn geïmplementeerd en getest. De taal-specificatie is in versie 0.1 en zal nog wijzigen. Het levende voorbeeld is de wiki, gegenereerd uit .hmd-kaarten in deze repository.
Groetjes,