| title | SPEC |
|---|---|
| category | documentation |
| version | 0.1 |
Modular Markup Language (MML) is a semantic document language designed around a simple principle:
Documents should describe meaning rather than formatting.
MML is intended to remain readable as plain text while providing enough structure for parsing, validation, compilation, and semantic analysis.
Unlike Markdown, MML does not rely on symbolic formatting conventions.
Unlike HTML, MML prioritizes semantic relationships and parent-child validation over presentation.
MML is designed to be:
- Human-readable
- Machine-parseable
- Semantically meaningful
- Validation-friendly
- Extensible
- Plain-text authorable
Elements should represent meaningful concepts rather than visual presentation.
Preferred:
argument
claim
evidence
timeline
event
comparison
image
caption
Avoided:
div
span
wrapper
container
If content is not valid markup, it is treated as text.
The parser should never aggressively reinterpret ordinary writing as structure.
All elements must be explicitly opened and closed.
MML validates semantic relationships, not merely syntax.
Opening tags consist of a valid element name.
Example:
claim
Attributes may be included:
section title="Background"
Closing tags begin with a forward slash.
Example:
/claim
/argument
All element names are singular.
Valid:
claim
event
entity
image
Invalid:
claims
events
entities
images
Attributes may only appear on opening tag lines.
Example:
section title="Introduction"
Attributes are parsed only when attached to a valid opening tag.
Example:
section
title="Introduction"
/section
In this example:
title="Introduction"
is plain text.
Plain text is automatically wrapped in text elements.
Source:
claim
Markdown introduces an unnecessary abstraction layer.
/claim
Internal Representation:
<claim>
<text>Markdown introduces an unnecessary abstraction layer.</text>
</claim>Authors are not expected to manually create text elements in most situations.
Reserved words only act as markup when they appear in tag position.
Example:
claim
Arguments are not always unhealthy.
/claim
The word "Arguments" is text content.
A line is interpreted as an opening tag when:
- It begins with a valid element name.
- Any supplied attributes are valid.
A line is interpreted as a closing tag when:
/element-name
matches a currently open element.
Elements must close in stack order.
Valid:
argument
claim
Text.
/claim
/argument
Invalid:
argument
claim
Text.
/argument
Error:
Cannot close argument while claim is still open.
Expected /claim.
Elements may define required parents.
Example:
evidence
requires:
claim
parent.
Example:
evidence
Some evidence.
/evidence
Produces:
Error:
evidence requires parent claim.
The parser should provide structured repair information whenever possible.
Purpose:
- Represents a collection of claims.
Rules:
- Requires at least one claim.
Allowed Children:
claim
Purpose:
- Represents a semantic assertion.
Rules:
- May exist independently.
- May exist within argument.
Allowed Children:
text
evidence
quote
source
Purpose:
- Supports a claim.
Rules:
- Requires parent claim.
Allowed Children:
text
quote
source
Purpose:
- Represents a chronological range.
Required Children:
year-start
year-end
Optional Children:
event
A timeline containing only year-start and year-end is valid.
Rules:
- Requires parent timeline.
Rules:
- Requires parent timeline.
Purpose:
- Represents a time-bound occurrence.
Rules:
- Requires date.
- May exist independently.
- May exist within timeline.
- May exist within calendar.
Allowed Children:
date
text
image
media
source
note
link
Rules:
- Requires parent event.
Purpose:
- Represents a calendar period.
Required Children:
year-month
Optional Children:
event
A calendar containing only year-month is valid.
Rules:
- Requires parent calendar.
MML supports multiple comparison schemas.
Required Children:
before
after
Example:
comparison
before
Old design.
/before
after
New design.
/after
/comparison
Required:
entity
entity
Optional:
shared
Rules:
- Requires parent comparison.
Allowed Children:
unique
text
Rules:
- Requires parent entity.
Rules:
- Requires parent comparison.
Required:
scenario
scenario
Each scenario should contain:
conditions
Rules:
- Requires parent comparison.
Allowed Children:
conditions
text
note
Rules:
- Requires parent scenario.
Purpose:
- Groups related media assets.
Required Children:
- At least one of:
image
audio
video
Optional Children:
caption
source
- Represents an image.
- Represents audio content.
- Represents video content.
Purpose:
- Describes associated media.
Preferred Parent:
media
Purpose:
- Represents a logical document section.
Attributes:
title
Example:
section title="Background"
The title attribute functions as the section heading.
Purpose:
- Represents a heading within a section.
script
style
canvas
These elements provide runtime functionality and presentation support.
document
section
subhead
text
blockquote
source
link
a
argument
claim
evidence
timeline
calendar
event
date
year-start
year-end
year-month
comparison
before
after
entity
unique
shared
scenario
conditions
media
image
audio
video
caption
table
row
column
cell
form
fieldset
input
select
option
button
canvas
script
style
Potential future areas include:
- Compiler targets
- Rich editor support
- Semantic repair actions
- Schema extensions
- Accessibility metadata
- Knowledge graph generation
- PDF and eBook compilation
- AI-native document representations
A document should remain understandable as plain text while remaining unambiguously parseable as structured semantic data.
Check out the README if you're not sure where to start.
You can read the full SPEC here.
Try the PARSER.
You can find the full list of TAGS here.
#specification #draft #syntax #markup #semantic #grammar #language