This document is part of the Metanorma specifications series that defines requirements for document authoring.
This document specifies the Markdown syntax for use with Metanorma document processing. It defines both the base CommonMark syntax support and Metanorma-specific extensions necessary for standards document authoring.
This specification:
-
Defines the Markdown syntax subset based on CommonMark that Metanorma supports
-
Specifies Metanorma-specific extensions to Markdown
-
Provides migration guidance from Metanorma AsciiDoc to Metanorma Markdown
-
Establishes compatibility requirements between Markdown and existing Metanorma features
A conforming Metanorma Markdown processor SHALL:
-
Implement all CommonMark syntax features as specified
-
Support all Metanorma extension blocks
-
Process document metadata as specified
-
Generate identical output to equivalent AsciiDoc input
-
Support all specified bibliography features
-
Process all specified math expressions
-
Handle all cross-reference mechanisms
-
CommonMark Specification Version 0.30
-
GitHub Flavored Markdown Specification
-
Pandoc Markdown Specification
-
RMarkdown Specification
-
ISO/IEC 2382:2015 Information technology — Vocabulary
-
Metanorma Standard Document Format
extension of CommonMark syntax that supports Metanorma document authoring features
Document metadata provides essential information about the document including its identity, status, and administrative details.
The following example shows the minimal required metadata for a Metanorma document.
---
docnumber: "110"
title: "Metanorma Markdown Syntax"
edition: 1
revdate: 2024-10-27
--- (1)-
Triple hyphens delimit the YAML frontmatter block
This example demonstrates additional metadata fields for document classification and management.
---
docnumber: "110"
title: "Metanorma Markdown Syntax"
edition: 1
revdate: 2024-10-27
language: en
doctype: standard
status: draft
committee: Technical
technical-committee: "Syntax and Document Formats"
keywords:
- markdown
- syntax
- metanorma (1)
----
Arrays in YAML are denoted with hyphens
This example shows how to represent complex metadata relationships and contributor information.
---
docnumber: "110"
title: "Metanorma Markdown Syntax"
edition: 1
revdate: 2024-10-27
contributors:
- role: author
name: Jane Smith
organization: Standards Organization (1)
- role: editor
name: John Doe
organization: Technical Committee
relationships:
obsoletes: MN-109 (2)
related:
- MN-108
- MN-107
----
Nested structures use indentation to indicate hierarchy
-
Single values and arrays can be mixed in the same document
The document title identifies the document and appears as the main heading in the rendered output.
The title can be specified in the document’s frontmatter.
---
title: "Document Title"
--- (1)-
Title in frontmatter takes precedence over other title declarations
Alternatively, the title can be specified as a level-1 heading in the document body.
# Document Title (1)
## First Section-
The hash symbol followed by a space denotes a level-1 heading
Documents can include both a title and subtitle.
---
title: "Document Title"
subtitle: "A comprehensive guide" (1)
----
The subtitle field is optional and can contain formatting
Basic text formatting provides emphasis, strong emphasis, and combinations for inline text styling.
This example shows the fundamental text formatting syntax.
This is *emphasized* and this is **strong**. (1)
This is _also emphasized_ and this is __also strong__. (2)-
Asterisks can be used for emphasis and strong emphasis
-
Underscores can be used as an alternative to asterisks
Text can be both emphasized and strong simultaneously.
This is ***strong and emphasized***. (1)
This is ___also strong and emphasized___. (2)-
Triple asterisks combine strong and emphasis
-
Triple underscores provide an alternative syntax
Formatting can be nested and combined within text.
This **strong text contains *emphasis* within it**. (1)
This paragraph has both *emphasized* and **strong** elements. (2)-
Nested emphasis is processed inside-out
-
Different formatting styles can be mixed in the same paragraph
Code spans are used for inline code references.
Use the `print()` function. (1)-
Single backticks denote inline code
When the code itself contains backticks, double backticks can be used as delimiters.
``Use `backticks` within code`` (1)-
Double backticks allow inclusion of single backticks
Code spans can include language and other attributes.
`{language=ruby} puts "Hello"` (1)-
Attributes in curly braces affect processing and display
External links connect to resources outside the document.
Visit [Metanorma](https://www.metanorma.org "Metanorma Homepage"). (1)
See <https://www.metanorma.org> for more information. (2)-
Links can include optional titles in quotes
-
URLs can be automatically linked using angle brackets
Internal cross-references link to sections within the document.
See [Section 3.2](#section-3-2) for details. (1)
Refer to [Terms and definitions](#terms-and-definitions). (2)-
Section references use the section’s ID
-
IDs are automatically generated from heading text
Reference-style links separate the link text from the URL definition.
This specification uses [CommonMark][cm] syntax.
See the [Metanorma documentation][mn] for more.
[cm]: https://commonmark.org "CommonMark Spec" (1)
[mn]: https://www.metanorma.org/docs/ "Documentation" (2)-
Link references can be defined anywhere in the document
-
References support optional titles
Inline math expressions are embedded within text.
The equation $E = mc^2$ shows the relationship. (1)-
Single dollar signs denote inline math mode
Display math appears as separate blocks.
$$
\frac{-b \pm \sqrt{b^2 - 4ac}}{2a} (1)
$$-
Double dollar signs create display math blocks
Equations can be numbered and referenced.
$$
\begin{equation}
\label{eq:1} (1)
F = ma
\end{equation}
$$-
Labels enable equation referencing
Paragraphs are separated by blank lines.
This is the first paragraph.
This is the second paragraph. (1)-
Blank lines separate paragraphs
Blocks can have attributes that affect their processing.
{.note} (1)
This is a note block.
{#custom-id .warning} (2)
This is a warning block.-
Class attributes affect block styling
-
IDs enable block referencing
Blocks can contain other blocks and inline elements.
{.requirement #req-1}
This requirement block contains:
1. Ordered list
2. With *emphasized* text
3. And `code spans` (1)-
Blocks can contain mixed content types
Lists can be ordered or unordered with nested structures.
* Unordered item 1
* Unordered item 2 (1)
* Nested item 2.1 (2)
* Nested item 2.2
* Unordered item 3
1. Ordered item 1 (3)
2. Ordered item 2
1. Nested item 2.1
2. Nested item 2.2
3. Ordered item 3-
Asterisks denote unordered list items
-
Two spaces indent creates nested lists
-
Numbers with periods create ordered lists
Definition lists associate terms with their definitions.
Term 1
: Definition 1 (1)
: Another definition 1 (2)
Term 2
: Definition 2-
Colon indicates a definition
-
Terms can have multiple definitions
Lists can have attributes affecting their appearance and behavior.
{.checklist} (1)
* [ ] Task 1 (2)
* [x] Task 2
1. Subtask 2.1
2. Subtask 2.2
* [ ] Task 3-
Class attributes modify list behavior
-
Checkbox syntax for task lists
Fenced code blocks use triple backticks with optional language specification.
```ruby (1)
def hello_world
puts "Hello, world!"
end
``` (2)-
Language identifier enables syntax highlighting
-
Triple backticks delimit the code block
Code blocks can have additional attributes for processing and display.
```{.ruby #example-1 .numbered} (1)
def hello_world
puts "Hello, world!"
end
```-
Attributes in curly braces affect block processing
Code blocks can also be created by indentation.
def hello_world (1)
puts "Hello, world!"
end-
Four spaces indent creates a code block
Simple tables use pipe characters to separate columns.
| Header 1 | Header 2 | (1)
|----------|----------| (2)
| Cell 1 | Cell 2 |
| Cell 3 | Cell 4 |-
Header row is separated by pipes
-
Delimiter row indicates column alignment
Column alignment is specified in the delimiter row.
| Left | Center | Right | (1)
|:-----|:------:|------:| (2)
| 1 | 2 | 3 |
| 4 | 5 | 6 |-
Headers establish column count
-
Colons in delimiter row specify alignment
Tables can have attributes and contain formatted content.
{.bordered #table-1 title="Sample Table"} (1)
| Function | Description | Example |
|----------|-------------|---------|
| `sum()` | Adds numbers | `sum(1, 2)` |
| `avg()` | Calculates average | `avg([1, 2])` |-
Table attributes affect presentation and processing
Simple requirement blocks state single requirements.
::: requirement (1)
This system SHALL support UTF-8 encoding. (2)
:::-
Triple colons denote extension blocks
-
Requirements use normative language
Requirements can have identifiers and specific obligation levels.
::: requirement{#req-1 level="shall"} (1)
The processor SHALL implement all CommonMark features. (2)
:::-
Attributes specify requirement properties
-
Content states the normative requirement
Requirements can include structured content and metadata.
::: requirement{#req-2}
level:: shall (1)
inherit:: req-1 (2)
classification:: technical (3)
---
The system SHALL:
1. Parse all valid inputs
2. Report errors clearly
3. Maintain backward compatibility
:::-
Requirement level specified as metadata
-
Inheritance indicates requirement dependencies
-
Classification aids in requirement management
Simple admonitions use the triple exclamation mark syntax.
!!! note (1)
This is a note. (2)
!!! warning
This is a warning.-
Admonition type follows the markers
-
Content is indented by 4 spaces
Admonitions can have custom titles.
!!! important "Critical Information" (1)
This must be considered.-
Custom title in quotes after type
Admonitions can contain structured content and attributes.
!!! note{#note-1 .special} (1)
This note contains:
* Important points
* Critical information
* Key considerations-
Attributes customize admonition behavior
Citations reference bibliography entries.
[@reference-key] (1)-
Citation key in square brackets with @ prefix
Citations can include additional context.
[see @smith2024, p. 23-45] (1)-
Prefixes and page numbers add citation context
Bibliography data is defined in YAML format.
---
references:
- id: smith2024 (1)
type: book
author:
- family: Smith
given: John
title: Example Book
publisher: Publisher Name
year: 2024
----
Entry ID matches citation keys
This example demonstrates a complete Metanorma Markdown document.
---
title: "Sample Metanorma Document"
docnumber: "MN-SAMPLE-1"
date: 2024-10-28
type: standard
status: draft
---
# Sample Metanorma document
## Introduction
This document demonstrates the Metanorma Markdown syntax.
### Purpose
The purpose is to show syntax examples.
## Technical requirements
::: requirement{#req-1}
level:: shall
The system SHALL support all specified features.
:::
### Mathematical expressions
The formula $E = mc^2$ shows mass-energy equivalence.
$$
F = ma
$$
## References
See [@smith2024] for background.
---
references:
- id: smith2024
type: article
author:
- family: Smith
given: J.
title: Sample Article
journal: Journal Name
year: 2024
---