1. Introduction

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.

2. Design Goals

MML is designed to be:

• Human-readable
• Machine-parseable
• Semantically meaningful
• Validation-friendly
• Extensible
• Plain-text authorable

3. Core Principles

3.1 Meaning First

Elements should represent meaningful concepts rather than visual presentation.

Preferred:

argument
claim
evidence
timeline
event
comparison
image
caption

Avoided:

div
span
wrapper
container

3.2 Text Wins

If content is not valid markup, it is treated as text.

The parser should never aggressively reinterpret ordinary writing as structure.

3.3 Explicit Structure

All elements must be explicitly opened and closed.

3.4 Semantic Validation

MML validates semantic relationships, not merely syntax.

4. Syntax

4.1 Opening Tags

Opening tags consist of a valid element name.

Example:

claim

Attributes may be included:

section title="Background"

4.2 Element Names

All element names are singular.

Valid:

claim
event
entity
image

Invalid:

claims
events
entities
images

4.3 Attributes

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"

In this example:

title="Introduction"

is plain text.

5. Text Handling

5.1 Automatic Text Nodes

Plain text is automatically wrapped in text elements.

Source:

claim
Markdown introduces an unnecessary abstraction layer.

Internal Representation:

<claim>
  <text>Markdown introduces an unnecessary abstraction layer.</text>

Authors are not expected to manually create text elements in most situations.

5.2 Reserved Words

Reserved words only act as markup when they appear in tag position.

Example:

claim
Arguments are not always unhealthy.

The word "Arguments" is text content.

6. Parsing Rules

6.1 Opening Tag Recognition

A line is interpreted as an opening tag when:

• It begins with a valid element name.
• Any supplied attributes are valid.

7. Validation Rules

7.1 Parent Validation

Elements may define required parents.

Example:

evidence

requires:

claim

parent.

7.2 Missing Parent Errors

Example:

evidence
Some evidence.

Produces:

Error:
evidence requires parent claim.

The parser should provide structured repair information whenever possible.

8. Element Definitions

8.1 Argument System

argument

Purpose:

• Represents a collection of claims.

Rules:

• Requires at least one claim.

Allowed Children:

claim

claim

Purpose:

• Represents a semantic assertion.

Rules:

• May exist independently.
• May exist within argument.

Allowed Children:

text
evidence
quote
source

evidence

Purpose:

• Supports a claim.

Rules:

• Requires parent claim.

Allowed Children:

text
quote
source

9. Timeline System

timeline

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.

year-start

Rules:

• Requires parent timeline.

year-end

Rules:

• Requires parent timeline.

event

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

date

Rules:

• Requires parent event.

10. Calendar System

calendar

Purpose:

• Represents a calendar period.

Required Children:

year-month

Optional Children:

event

A calendar containing only year-month is valid.

year-month

Rules:

• Requires parent calendar.

11. Comparison System

MML supports multiple comparison schemas.

11.1 Before / After Schema

Required Children:

before
after

Example:

comparison

before
Old design.

after
New design.

11.2 Entity Schema

Required:

entity
entity

Optional:

shared

entity

Rules:

• Requires parent comparison.

Allowed Children:

unique
text

unique

Rules:

• Requires parent entity.

shared

Rules:

• Requires parent comparison.

11.3 Scenario Schema

Required:

scenario
scenario

Each scenario should contain:

conditions

scenario

Rules:

• Requires parent comparison.

Allowed Children:

conditions
text
note

conditions

Rules:

• Requires parent scenario.

12. Media System

media

Purpose:

• Groups related media assets.

Required Children:

• At least one of:

image
audio
video

Optional Children:

caption
source

image

• Represents an image.

audio

• Represents audio content.

video

• Represents video content.

caption

Purpose:

• Describes associated media.

Preferred Parent:

media

13. Structural Elements

section

Purpose:

• Represents a logical document section.

Attributes:

title

Example:

section title="Background"

The title attribute functions as the section heading.

subhead

Purpose:

• Represents a heading within a section.

14. Future Considerations

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

15. Guiding Principle

A document should remain understandable as plain text while remaining unambiguously parseable as structured semantic data.

15.1 SUPPORT

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