Define your terms. Once.
termd is a Markdown dialect for term definitions — glossaries your team reads, your docs index, and your AI understands.
Words drift. Projects pay.
Teams argue about words. Glossaries rot in wikis because they have no format — no structure, no lifecycle, not machine-readable. And the AI that writes your code doesn't know your vocabulary.
One block type. Plain Markdown.
A termd document is a glossary: one ::: term
block per term. Only Definition is required — a minimal
glossary stays minimal.
::: term id="draft"
# Draft
## Definition
An article that has not been published yet.
## Usage
- Say "draft", not "unpublished article".
## Examples
+ "You have 3 drafts."
- "You have 3 unpublished articles."- id — the stable key: HTML anchor, JSON key, target of cross-references.
- # H1 — the display form of the term.
- Definition — the only required section.
- + / − — correct and incorrect usage, the exact format an AI learns do/don't from.
Three outputs from one source
Register
The HTML renderer generates an alphabetical keyword register with anchors. Synonyms point at their main term; retired terms are struck through.
{ "id": "draft",
"term": "Draft",
"definition": "…",
"examples": {
"positive": ["…"],
"negative": ["…"] } }AI context
The JSON renderer emits a flat glossary index — drop it into a model's context, a search index, or tooltips. Your AI starts using your words as defined.
Governance
Terms have a lifecycle: deprecated names its
successors, rejected stays in the glossary so nobody
reintroduces it.
Quick start
npm install @idiomd/core @idiomd/dialect-termdimport { createEngine } from '@idiomd/core';
import { termd } from '@idiomd/dialect-termd';
const doc = createEngine().use(termd).parse(glossarySource);
const html = createEngine().use(termd).render(doc, { format: 'html' });That's the whole integration: parse, validate, render — register included. Full install guide →
Built for teams
The glossary lives in the repo, next to the code. Review happens in
pull requests. The status lifecycle is term governance
without an extra tool, and the JSON export feeds onboarding docs and AI
assistants alike.
termd is a normative specification (RFC 2119) with a machine-readable block definition as its source of truth — conformance is checkable, not a style opinion.
Plays well with OKF
A termd glossary is simultaneously a valid document in Google's Open Knowledge Format.
OKF regulates what termd leaves open — bundle layout, document graph, discovery — and leaves open what termd regulates: the structure inside the document. Complementary, not competing.
termd's default document type is
Glossary; one term is one concept, which makes a termd
document the most natural OKF citizen in the family. The same file
lands in the Google Cloud Knowledge Catalog and in your rendered
docs — no conversion.
One of four dialects
termd is one of the Idiomd dialects. Same kernel, same fence syntax — different job.