EXAMPLE 1 — Basic document metadata

The following example shows the minimal required metadata for a Metanorma document.

---
docnumber: "110"
title: "Metanorma Markdown Syntax"
edition: 1
revdate: 2024-10-27
-

Key
1
Triple hyphens delimit the YAML frontmatter block

EXAMPLE 2 — Extended document metadata

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> 
---

Key
1
Arrays in YAML are denoted with hyphens

EXAMPLE 3 — Complex metadata with nested structures

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
---

Key
1
Nested structures use indentation to indicate hierarchy
2
Single values and arrays can be mixed in the same document

EXAMPLE 1 — Title in frontmatter

The title can be specified in the document’s frontmatter.

---
title: "Document Title"
-

Key
1
Title in frontmatter takes precedence over other title declarations

EXAMPLE 2 — Title as level-1 heading

Alternatively, the title can be specified as a level-1 heading in the document body.

# Document Title 

## First Section

Key
1
The hash symbol followed by a space denotes a level-1 heading

EXAMPLE 3 — Title with subtitle

Documents can include both a title and subtitle.

---
title: "Document Title"
subtitle: "A comprehensive guide"  <1> 
---

Key
1
The subtitle field is optional and can contain formatting

EXAMPLE 1 — Basic emphasis and strong emphasis

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> 

Key
1
Asterisks can be used for emphasis and strong emphasis
2
Underscores can be used as an alternative to asterisks

EXAMPLE 2 — Combined emphasis

Text can be both emphasized and strong simultaneously.

This is ***strong and emphasized***.  <1> 
This is ___also strong and emphasized___.  <2> 

Key
1
Triple asterisks combine strong and emphasis
2
Triple underscores provide an alternative syntax

EXAMPLE 3 — Complex formatting

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> 

Key
1
Nested emphasis is processed inside-out
2
Different formatting styles can be mixed in the same paragraph

EXAMPLE 1 — Basic code spans

Code spans are used for inline code references.

Use the `print()` function.  <1> 

Key
1
Single backticks denote inline code

EXAMPLE 2 — Code spans with backticks

When the code itself contains backticks, double backticks can be used as delimiters.

``Use `backticks` within code``  <1> 

Key
1
Double backticks allow inclusion of single backticks

EXAMPLE 3 — Code spans with attributes

Code spans can include language and other attributes.

`{language=ruby} puts "Hello"`  <1> 

Key
1
Attributes in curly braces affect processing and display

EXAMPLE 1 — External links

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> 

Key
1
Links can include optional titles in quotes
2
URLs can be automatically linked using angle brackets

EXAMPLE 2 — Internal cross-references

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> 

Key
1
Section references use the section’s ID
2
IDs are automatically generated from heading text

EXAMPLE 3 — Reference-style links

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> 

Key
1
Link references can be defined anywhere in the document
2
References support optional titles

EXAMPLE 1 — Inline mathematics

Inline math expressions are embedded within text.

The equation $E = mc^2$ shows the relationship.  <1> 

Key
1
Single dollar signs denote inline math mode

EXAMPLE 2 — Display mathematics

Display math appears as separate blocks.

$$
\frac{-b \pm \sqrt{b^2 - 4ac}}{2a}  <1> 
$$

Key
1
Double dollar signs create display math blocks

EXAMPLE 3 — Numbered equations

Equations can be numbered and referenced.

$$
\begin{equation}
  \label{eq:1}  <1> 
  F = ma
\end{equation}
$$

Key
1
Labels enable equation referencing

EXAMPLE 1 — Basic blocks

Paragraphs are separated by blank lines.

This is the first paragraph.

This is the second paragraph.  <1> 

Key
1
Blank lines separate paragraphs

EXAMPLE 2 — Blocks with attributes

Blocks can have attributes that affect their processing.

{.note}  <1> 
This is a note block.

{#custom-id .warning}  <2> 
This is a warning block.

Key
1
Class attributes affect block styling
2
IDs enable block referencing

EXAMPLE 3 — Complex blocks

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> 

Key
1
Blocks can contain mixed content types

EXAMPLE 1 — Basic list 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

Key
1
Asterisks denote unordered list items
2
Two spaces indent creates nested lists
3
Numbers with periods create ordered lists

EXAMPLE 2 — Definition lists

Definition lists associate terms with their definitions.

Term 1
: Definition 1  <1> 
: Another definition 1  <2> 

Term 2
: Definition 2

Key
1
Colon indicates a definition
2
Terms can have multiple definitions

EXAMPLE 3 — Lists with attributes

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

Key
1
Class attributes modify list behavior
2
Checkbox syntax for task lists

EXAMPLE 1 — Fenced code blocks

Fenced code blocks use triple backticks with optional language specification.

```ruby  <1> 
def hello_world
  puts "Hello, world!"
end
```  <2> 

Key
1
Language identifier enables syntax highlighting
2
Triple backticks delimit the code block

EXAMPLE 2 — Code blocks with attributes

Code blocks can have additional attributes for processing and display.

```{.ruby #example-1 .numbered}  <1> 
def hello_world
  puts "Hello, world!"
end
```

Key
1
Attributes in curly braces affect block processing

EXAMPLE 3 — Indented code blocks

Code blocks can also be created by indentation.

    def hello_world  <1> 
      puts "Hello, world!"
    end

Key
1
Four spaces indent creates a code block

EXAMPLE 1 — Basic tables

Simple tables use pipe characters to separate columns.

| Header 1 | Header 2 |  <1> 
|----------|----------|  <2> 
| Cell 1   | Cell 2   |
| Cell 3   | Cell 4   |

Key
1
Header row is separated by pipes
2
Delimiter row indicates column alignment

EXAMPLE 2 — Aligned columns

Column alignment is specified in the delimiter row.

| Left | Center | Right |  <1> 
|:-----|:------:|------:|  <2> 
| 1    | 2      | 3     |
| 4    | 5      | 6     |

Key
1
Headers establish column count
2
Colons in delimiter row specify alignment

EXAMPLE 3 — Complex tables with attributes

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])` |

Key
1
Table attributes affect presentation and processing

EXAMPLE 1 — Basic requirement

Simple requirement blocks state single requirements.

::: requirement  <1> 
This system SHALL support UTF-8 encoding.  <2> 
:::

Key
1
Triple colons denote extension blocks
2
Requirements use normative language

EXAMPLE 2 — Requirement with attributes

Requirements can have identifiers and specific obligation levels.

::: requirement{#req-1 level="shall"}  <1> 
The processor SHALL implement all CommonMark features.  <2> 
:::

Key
1
Attributes specify requirement properties
2
Content states the normative requirement

EXAMPLE 3 — Complex 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
:::

Key
1
Requirement level specified as metadata
2
Inheritance indicates requirement dependencies
3
Classification aids in requirement management

EXAMPLE 1 — Basic admonitions

Simple admonitions use the triple exclamation mark syntax.

!!! note  <1> 
    This is a note.  <2> 

!!! warning
    This is a warning.

Key
1
Admonition type follows the markers
2
Content is indented by 4 spaces

EXAMPLE 2 — Admonitions with titles

Admonitions can have custom titles.

!!! important "Critical Information"  <1> 
    This must be considered.

Key
1
Custom title in quotes after type

EXAMPLE 3 — Complex admonitions

Admonitions can contain structured content and attributes.

!!! note{#note-1 .special}  <1> 
    This note contains:

    * Important points
    * Critical information
    * Key considerations

Key
1
Attributes customize admonition behavior

EXAMPLE 1 — Basic citation

Citations reference bibliography entries.

[@reference-key]  <1> 

Key
1
Citation key in square brackets with @ prefix

EXAMPLE 2 — Citation with prefix and locator

Citations can include additional context.

[see @smith2024, p. 23-45]  <1> 

Key
1
Prefixes and page numbers add citation context

EXAMPLE 3 — Bibliography entry

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
---

Key
1
Entry ID matches citation keys