Koder Markdown Format (.kmd)

kmd specs/kmd/format.kmd

Especificação do formato KMD (Koder Markdown) — extensão de CommonMark com frontmatter YAML, cross-refs validados e blocos Koder Koda inline. Formato canônico de documentação da Koder Stack; consumido pelos editores Koder Dok e pelo render web do Koder Flow.

Quando esta spec se aplica

Todos os triggers

Implementar parser, renderer ou tooling de KMD
Adicionar nova extensão de sintaxe ao KMD
Validar conformidade de tooling KMD à spec

KMD Specification v1.0

KMD (Koder Markdown) is a lightweight document format designed for visual clarity, minimal verbosity, and self-sufficiency.

Extension: .kmd
MIME Type: text/kmd
Encoding: UTF-8

1. Document Structure

A KMD document consists of an optional front matter block followed by body content.

1.1 Front Matter (Metadata)

Optional YAML block delimited by ---:

---
title: Document Title
author: Author Name
date: 2026-03-21
lang: en-US
---

Supported fields: title, author, date, lang, version, description, tags. Custom fields are allowed.

1.2 Comments

// Single-line comment (not rendered)

/*
Multi-line comment
(not rendered)
*/

Comments are stripped during parsing and never appear in output.

2. Headings

Six heading levels using # prefix:

# Heading 1
## Heading 2
### Heading 3
#### Heading 4
##### Heading 5
###### Heading 6

Headings must have a space after the # characters. An optional closing sequence of # is allowed: ## Heading 2 ##.

2.1 Heading Anchors

Each heading automatically generates an anchor ID from its text (lowercase, spaces replaced with -, non-alphanumeric removed).

Custom anchors can be set:

## My Section {#custom-id}

3. Inline Formatting

3.1 Core Formatting

Effect	Syntax	Rendered As
Bold	`text`	text
Italic	`/text/`	/text/
Strikethrough	`-text-`	-text-
Underline	`_text_`	text with underline
Highlight/Marker	`=text=`	highlighted text
Inline code	`text`	`text`
Blink	`@@text@@`	blinking text
Superscript	`^text^`	superscript
Subscript	`~text~`	subscript

3.2 Design Rationale

Each delimiter visually resembles its effect:

* — dense/heavy, suggests strong emphasis (bold)
/ — slanted character, suggests italic tilt
- — horizontal line, suggests strikethrough
_ — line at the bottom, suggests underline
= — thick bar, suggests marker highlight
^ — points upward, suggests superscript
~ — dips downward, suggests subscript

3.3 Rules

Delimiters must be directly adjacent to the text (no space between delimiter and text).
Valid: *bold* — Invalid: * not bold *
Formatters can be nested: *_bold and underlined_*
Formatters do not cross paragraph boundaries.
Literal delimiters are escaped with backslash: \*not bold\*

3.4 Disambiguation

- as strikethrough vs list item:

- followed by a space at the start of a line is a list item: - item
- directly adjacent to text is strikethrough: -deleted-

/ as italic vs path:

/ must appear as a balanced pair around text: /italic text/
Unbalanced / or / in URLs/paths is treated as literal

_ as underline vs identifier:

_ must appear as a balanced pair: _underlined_
_ inside words (e.g., variable_name) is literal when not balanced

4. Block-Level Alignment

Alignment is specified by a prefix at the start of a paragraph:

Text with no prefix is left-aligned (default).

>> This text is right-aligned.

>< This text is centered.

<> This text is justified, filling the
full width of the available space.

Prefix	Alignment	Mnemonic
(none)	Left	Natural reading direction
`>>`	Right	Pushes text to the right
`><`	Center	Squeezes text to the center
`<>`	Justify	Stretches text to both sides

The prefix must be followed by a space. It applies to the entire paragraph (all lines until the next blank line).

5. Lists

5.1 Unordered Lists

- Item one
- Item two
  - Nested item
    - Deep nested

5.2 Ordered Lists

1. First item
2. Second item
   1. Nested ordered
   2. Another nested

5.3 Task Lists

[ ] Pending task
[x] Completed task
[ ] Another pending task

5.4 Definition Lists

Term
: Definition of the term
: Alternative definition

Another Term
: Its definition

6. Links and Anchors

6.1 Inline Links

[link text](https://example.com)
[link text](https://example.com "title")

6.2 Auto-links

<https://example.com>
<user@example.com>

6.3 Reference Links

[link text][ref-id]

[ref-id]: https://example.com "Optional Title"

6.4 Internal Anchors

{#anchor-name}

[Go to section](#anchor-name)

7. Images

![alt text](image.png)
![alt text](image.png "caption")
![alt text](image.png 300x200)
![alt text](image.png 50%)
![alt text](image.png 300x200 >>)

Dimension formats:

WIDTHxHEIGHT — pixels: 800x600
WIDTH% — percentage of container: 50%
Alignment suffix: << (left), >> (right), >< (center)

8. Video and Audio

8.1 Video

!![alt text](video.mp4)
!![alt text](video.mp4 800x450)
!![](https://youtube.com/watch?v=ID)

!! prefix (double bang) distinguishes video from image (!).

8.2 Audio

!~[alt text](audio.mp3)
!~[podcast](https://example.com/episode.mp3)

!~ prefix — tilde suggests sound wave.

9. Code Blocks

9.1 Inline Code

Use the `print()` function.

9.2 Fenced Code Blocks

```language
code here
```

9.3 Code Block Options

```python {lines=true start=10 highlight=3,5-7 title="example.py"}
def hello():
    print("Hello, KMD!")
```

Options:

lines — show line numbers (default: false)
start — starting line number (default: 1)
highlight — highlighted lines (comma-separated, ranges with -)
title — caption displayed above the block

10. Tables

10.1 Basic Table

| Name  | Age | City     |
|-------|-----|----------|
| Alice | 30  | Portland |
| Bob   | 25  | Austin   |

The header row is separated from body rows by a delimiter row of |---|.

10.2 Column Widths

Widths are specified in the header row using [width] after the column name:

| Name [30%] | Age [10%] | Description [60%] |
|------------|-----------|-------------------|
| Alice      | 30        | Developer         |

Width formats: [30%], [200px], [auto], [*] (fill remaining space).

10.3 Column Horizontal Alignment

Specified in the delimiter row using colons:

| Left   | Center | Right  | Justify |
|:-------|:------:|-------:|:------:|
| text   | text   | text   | text    |

:--- — left-aligned
:--: — centered
---: — right-aligned

Default is left-aligned.

10.4 Row Height

Specified at the end of a row using [h:value]:

| Name  | Bio           |
|-------|---------------|
| Alice | Developer     | [h:80px]
| Bob   | Designer      | [h:60px]

10.5 Cell Vertical Alignment

Prefix inside the cell content:

| ^Top aligned | =Middle aligned | _Bottom aligned |

^ — top alignment
= — middle alignment (vertical center)
_ — bottom alignment

The prefix must be followed by the cell content with no space. To use literal ^, =, or _ at cell start, escape: \^literal.

10.6 Cell Merging

| Name  | Details ||               // colspan: || merges 2 columns
|-------|---------|------|
| Alice | Age     | 30   |
| :::   | City    | PDX  |          // rowspan: ::: merges with cell above

|| (double pipe) at end of header cell — merge with next N columns (colspan)
::: as cell content — merge with cell directly above (rowspan)

10.7 Complete Table Example

| Product [40%] | Qty [15%] | Price [20%]  | Total [25%]  |
|:--------------|:---------:|-------------:|-------------:|
| ^Laptop       | =5        |     3,500.00 |    17,500.00 | [h:50px]
| ^Mouse        | =10       |        89.90 |       899.00 | [h:40px]
| *Subtotal* |||                              18,399.00    |

11. Blockquotes

> Simple blockquote.

> Blockquote with attribution.
> — Author, Source

> Nested blockquote:
>> Inner quote.

12. Footnotes

Text with a footnote[^1] and another[^note].

[^1]: First footnote content.
[^note]: Named footnote with *formatting*.

Footnotes are rendered at the end of the document or section.

13. Admonitions (Callouts)

!!! note "Optional Title"
    Content of the informational note.

!!! tip
    A helpful tip.

!!! warn
    Warning content.

!!! error
    Error content.

!!! success
    Success message.

!!! info
    Informational content.

!!! quote
    A notable quote.

Types: note, tip, warn, error, success, info, quote. Title is optional — defaults to the type name capitalized. Content is indented by 4 spaces.

14. Header and Footer

Document-level header and footer regions:

---header---
>> Confidential Report | Page {page}/{pages}
---/header---

(document body)

---footer---
>< (c) 2026 Koder — Generated on {date}
---/footer---

14.1 Automatic Variables

Variable	Value
`{page}`	Current page number
`{pages}`	Total page count
`{date}`	Current date
`{time}`	Current time
`{title}`	Document title (from front matter)
`{author}`	Document author (from front matter)

Variables are expanded during rendering. They are primarily useful for paginated outputs (PDF, print).

15. Horizontal Rule and Page Break

---          // horizontal rule (thematic break)
===          // page break

Horizontal rule: three or more hyphens on a line by themselves. Page break: three or more equals on a line by themselves.

Note: --- at the very beginning of a document starts front matter, not a rule.

16. Table of Contents

[TOC]           // full table of contents
[TOC 2-4]       // only heading levels 2 through 4

The [TOC] directive is replaced with a generated table of contents based on the document's headings.

17. Includes

{{file.kmd}}                     // include another KMD document
{{components/header.kmd}}        // relative path
{{data.csv as table}}           // include CSV rendered as table

Included files are processed recursively. Circular includes are detected and produce an error.

18. Variables and Substitution

18.1 Definition

{!company = "Koder Systems"!}
{!version = "2.1.0"!}

18.2 Usage

Welcome to {company}, version {version}.

Variables are defined with {! name = "value" !} and referenced with {name}. Variable names must be alphanumeric with underscores (e.g., my_var). Variables are scoped to the document (including included files).

19. Mathematics

19.1 Inline Math

Einstein's equation: $E = mc^2$

19.2 Block Math

$$
\sum_{i=1}^{n} x_i = x_1 + x_2 + \cdots + x_n
$$

Math expressions use LaTeX syntax and are rendered via KaTeX or MathJax.

20. Diagrams

```diagram type=flowchart
Start --> Process --> End
```

```diagram type=sequence
Alice -> Bob: Hello
Bob -> Alice: Hi
```

```diagram type=graph
A -- B
B -- C
A -- C
```

Diagram blocks use the diagram language identifier with a type option. Supported types: flowchart, sequence, graph, gantt, pie.

21. Collapsible Blocks

+++ Click to expand
Hidden content here.
Supports *all* formatting.
+++

The first +++ line contains the summary text. Content between +++ lines is collapsed by default.

Optional: +++> Summary starts expanded (open by default).

22. Columns

22.1 Equal Columns

::: columns 2
Content of column 1.

---col---

Content of column 2.
:::

22.2 Custom Widths

::: columns 3 [50%|25%|25%]
Main column.
---col---
Sidebar.
---col---
Extra.
:::

23. Badges

[!badge green "Approved"]
[!badge red "Critical"]
[!badge blue "v2.1.0"]
[!badge yellow "Beta"]

Colors: green, red, blue, yellow, orange, purple, gray.

24. Escaping

Any formatting character can be escaped with a backslash:

\*literal asterisks\*
\/not italic\/
\-not strikethrough\-
\_not underlined\_
\| pipe in text

25. Paragraphs and Line Breaks

Paragraphs are separated by one or more blank lines.
A single newline within a paragraph is treated as a soft break (rendered as a space in HTML, preserved in formats that support it).
A hard line break is created by ending a line with two spaces or \\.

26. Embedded Raw HTML

For cases where KMD syntax is insufficient:

{{{ html
<div class="custom-widget" data-id="42">
  <canvas id="chart"></canvas>
</div>
}}}

Raw HTML blocks are passed through without processing. Renderers may sanitize or restrict HTML based on security context.

Appendix A: Full Syntax Reference

Element	Syntax
Heading	`# H1` ... `###### H6`
Bold	`text`
Italic	`/text/`
Strikethrough	`-text-`
Underline	`_text_`
Highlight	`=text=`
Inline code	`text`
Blink	`@@text@@`
Superscript	`^text^`
Subscript	`~text~`
Left align	(default)
Right align	`>> text`
Center align	`>< text`
Justify	`<> text`
Unordered list	`- item`
Ordered list	`1. item`
Task list	`[ ] item` / `[x] item`
Definition list	`Term` + `: Definition`
Link	`[text](url)`
Image	`![alt](url)`
Video	`!![alt](url)`
Audio	`!~[alt](url)`
Code block	``` lang
Table	`\| col \| col \|`
Column width	`[30%]` / `[200px]` / `[*]`
Row height	`[h:50px]`
Vertical align	`^top` / `=middle` / `_bottom`
Colspan	`\|\|`
Rowspan	`:::`
Blockquote	`> text`
Footnote	`[^id]`
Admonition	`!!! type`
Header	`---header---`
Footer	`---footer---`
Horizontal rule	`---`
Page break	`===`
TOC	`[TOC]`
Include	`{{file.kmd}}`
Variable def	`{!name = "val"!}`
Variable use	`{name}`
Inline math	$expr$
Block math	`$$expr$$`
Diagram	```diagram type=X
Collapsible	`+++ summary`
Columns	`::: columns N`
Badge	`[!badge color "text"]`
Comment	`//` or `/* */`
Escape	`\`
Hard break	`\\` or two trailing spaces
Raw HTML	`{{{ html ... }}}`

Appendix B: File Extension

The .kmd extension is reserved for KMD documents. Note: .kmd is used by Koder Koda source files and must not be used for KMD.

Appendix C: Comparison with Markdown

Feature	KMD	Markdown
Bold	`text` (single)	`text` (double)
Italic	`/text/` (visual)	`text` (overloaded)
Underline	`_text_` (native)	Not supported
Strikethrough	`-text-` (native)	`~~text~~` (GFM extension)
Alignment	Native (`>>`, `><`, `<>`)	Not supported
Table widths	Native (`[30%]`)	Not supported
Table row height	Native (`[h:50px]`)	Not supported
Vertical cell align	Native (`^`, `=`, `_`)	Not supported
Cell merging	Native (`\|\|`, `:::`)	Not supported
Video/Audio	Native (`!!`, `!~`)	Not supported
Header/Footer	Native	Not supported
Variables	Native	Not supported
Includes	Native	Not supported
Comments	Native (`//`, `/* */`)	HTML comments only
Blink	Native (`@@`)	Not supported
Admonitions	Native (`!!!`)	Extension only
Collapsible	Native (`+++`)	Not supported
Columns	Native (`:::`)	Not supported

/KMD Specification v1.0 — Koder Systems — 2026/

Referências

engines/lang/kmd
policies/document-format.kmd