Modular Markup (MML)

A meaning-first markup language that remains readable as plain text.

Modular Markup (MML) is an experimental semantic markup language designed around a simple idea:

Documents should describe meaning, not formatting.

Unlike Markdown, which relies on symbolic shortcuts, or HTML, which mixes semantic and presentational concerns, MML focuses on explicit semantic structures that are understandable to both humans and machines.

The source document should remain readable as plain text while compiling into a fully structured document tree.

Goals

• Human-readable source documents
• Explicit semantic structure
• Strong parent-child validation
• Meaning-first document modeling
• Plain text as the authoring format
• Automatic structure generation
• Compiler-friendly AST representation
• Extensible semantic schemas

Core Philosophy

MML is built around semantic objects rather than formatting instructions.

For example:

argument
claim
evidence
timeline
event
comparison
entity
image
caption

represent meaningful concepts.

By contrast, generic containers such as:

<div>
<span>

have no direct equivalent in MML.

Every element should represent something recognizable and meaningful.

Syntax

Opening Tags

Opening tags are written as plain keywords.

claim

section title="Background"

Text Content

Anything that is not recognized as valid markup is treated as text.

claim

Arguments are not always unhealthy.

The word "Arguments" is content, not a tag.

Validation

MML validates semantic structure, not just syntax.

Example:

evidence
The final output is already HTML.

Produces:

Error:
evidence requires parent claim.

Valid:

argument

claim

evidence
The final output is already HTML.

Automatic Text Nodes

Plain text is automatically wrapped in text nodes.

Source:

claim
Markdown is unnecessary.

Internal representation:

<claim>
  <text>Markdown is unnecessary.</text>
</claim>

Authors rarely need to write explicit text tags.

Semantic Schemas

Argument

argument
└── claim
    └── evidence

Rules:

• argument requires at least one claim
• claim may exist standalone
• evidence requires parent claim

Timeline

timeline
├── year-start
├── event
└── year-end

Rules:

• timeline requires year-start
• timeline requires year-end
• event requires date

Calendar

calendar
├── year-month
└── event

Rules:

• calendar requires year-month
• event requires date

Comparison

Before / After

comparison
├── before
└── after

Entity Comparison

comparison
├── entity
│   └── unique
├── entity
│   └── unique
└── shared

Scenario Comparison

comparison
├── scenario
│   └── conditions
└── scenario
    └── conditions

Media

media
├── image
├── video
├── audio
├── caption
└── source

Rules:

• media requires at least one image, audio, or video
• caption typically belongs to media

Design Principles

Text Wins

If something is not valid markup, it is text.

The parser should never aggressively reinterpret ordinary writing as structure.

Singular Elements

Element names are singular.

Valid:

claim
event
entity
image

Invalid:

claims
events
entities
images

Semantic Necessity

A tag should only exist if it represents a meaningful concept that cannot already be expressed using existing tags.

Project Status

Early specification and parser prototype.

The language is actively evolving and many schemas, validation rules, and compilation targets remain under discussion.

CONTRIBUTE

Have an issue? GET IN TOUCH.

Have an idea for a tag we should add? SUBMIT A TAG here.

Do you have a more advanced tag idea? SUBMIT A SCHEMA instead!

SUPPORT

You can read the full SPEC here.

Try the PARSER.

TAGS

Here is the list of TAGS.

Looking for the SHORTHAND version?

Check out a list of PROPOSED TAGS.

Curious about how the tags can be used together? Find out here ---> DEPENDENCIES.

Did you know that you can use the tag CHAPTER instead of SECTION, if you want? SYNONYMS make it fine to replace one with the other!

#readme #markup #grammar #syntax #semantic #data-structure #schemas #official #tags