@hypertext-md/spec

@hypertext-md/spec

Machine-readable block definitions for Hypertext Markdown.

Why this repo

This repo is the source of truth for all LayoutMD block types: what attributes and fields a block type has, what a valid example looks like, and whether it's already implemented or still planned. Everywhere else that needs to know something about blocks — the TypeScript types of @hypertext-md/parser, the README table of hypertext-md.com, the parser code itself — derives from these definitions instead of duplicating them redundantly.

Install

npm install @hypertext-md/spec

ESM only, no runtime dependencies. TypeScript types are included.

import spec, { blocks, byKeyword } from '@hypertext-md/spec';

blocks.filter(b => b.status === 'implemented');
byKeyword.hero.fields;

The raw JSON is available on subpaths for consumers that want the files rather than the module:

import index from '@hypertext-md/spec/index.json' with { type: 'json' };
import schema from '@hypertext-md/spec/schema' with { type: 'json' };
import hero from '@hypertext-md/spec/blocks/hero.json' with { type: 'json' };

dist/index.js inlines the spec data rather than importing the JSON, so it also works in browser bundles without import attributes.

Structure

htmd-spec/
├── schema/
│   └── block-spec.schema.json   # JSON Schema every block spec must satisfy
├── blocks/
│   ├── hero.json
│   ├── split.json
│   ├── grid.json
│   ├── …                         # one file per block keyword
│   └── gallery.json              # status: "planned" — not yet implemented
├── types/
│   └── index.d.ts               # published types — mirrors the schema
├── dist/                        # generated: index.json + index.js
└── scripts/
    └── validate-and-build-index.mjs

Adding a block spec

1. Create blocks/<keyword>.json — the filename must exactly match the keyword field
2. Validate against schema/block-spec.schema.json: npm run validate
3. Set status: "planned" as long as @hypertext-md/parser doesn't parse the block yet — only set status: "implemented" after it's built there
4. A complete, runnable example is mandatory — it's rendered automatically on the syntax reference page of hypertext-md.com

Validation

npm install
npm run validate

Checks every file under blocks/ against the schema and generates everything under dist/ — a sorted overall list of all specs (implemented ones first), as JSON and ESM. The output is committed and shipped in the npm package; npm publish regenerates it via prepublishOnly. Builds are deterministic, so regenerating without a spec change produces no diff.

index.json is additionally published by the pipeline as a Generic Package and can be loaded by other repos without an npm dependency on htmd-spec itself:

https://gitlab.com/api/v4/projects/83926058/packages/generic/htmd-spec/latest/index.json

Consumers

• hypertext-md.com — generates the syntax reference page (/syntax) from index.json, one section per block, including a rendered live example
• @hypertext-md/parser (planned) — could use index.json at runtime or build time to give more targeted warnings for unknown block keywords ("did you mean 'grid'?") instead of just a generic "unknown block"
• htmd-vscode (planned) — autocompletion and hover docs in the editor, fed from the same source. keyword drives completion items, summary/example the hover content, attrs and fields the per-block detail

Status values

implemented — built in @hypertext-md/parser and covered by the default renderer. planned — specified, not yet implemented. draft — under discussion, structure may still change. deprecated — sunset, will be removed in a future major version.