MDC Syntax
Standard Markdown
MDC Syntax supports all standard CommonMark and GitHub Flavored Markdown (GFM) features.
Headings
# Heading 1
## Heading 2
### Heading 3
#### Heading 4
##### Heading 5
###### Heading 6
All headings automatically get ID attributes generated from their content for linking:
# Hello World
<!-- Becomes: <h1 id="hello-world">Hello World</h1> -->
Text Formatting
**Bold text**
*Italic text*
***Bold and italic***
~~Strikethrough~~
`Inline code`
Renders as:
- Bold text
- Italic text
- Bold and italic
StrikethroughInline code
Lists
- Item 1
- Item 2
- Nested item
- Another nested item
- Item 3
1. First item
2. Second item
1. Nested item
2. Another nested item
3. Third item
Links and Images
[Link text](https://example.com)
[Link with title](https://example.com "Link title")


Blockquotes
> This is a blockquote
> It can span multiple lines
>
> And contain other markdown elements like **bold** and *italic*
Renders as:
This is a blockquote It can span multiple lines
And contain other markdown elements like bold and italic
Horizontal Rules
Any of these create a horizontal rule:
---
***
___
Frontmatter
MDC Syntax supports YAML frontmatter at the beginning of documents:
---
title: My Document Title
author: John Doe
date: 2024-01-15
tags:
- markdown
- documentation
depth: 3
searchDepth: 2
custom_field: custom value
---
# Document Content
Your markdown content here...
Features
- Must be at the very beginning of the document
- Enclosed by
---delimiters - Parsed as YAML
- Available in the
dataproperty of ParseResult
Special Fields
| Field | Description | Default |
|---|---|---|
title | Used in table of contents generation | - |
depth | Maximum heading level for TOC | 2 |
searchDepth | Depth for TOC search | 2 |
Example Usage
import { parse } from 'mdc-syntax'
const content = `---
title: My Article
author: Jane Doe
depth: 3
---
# Introduction
Content here...
`
const result = parse(content)
console.log(result.data)
// { title: 'My Article', author: 'Jane Doe', depth: 3 }
MDC Components
MDC (Markdown Components) extends standard markdown with custom component syntax while maintaining readability.
Block Components
Block components use the ::component-name syntax:
::component-name{prop1="value1" prop2="value2"}
Content inside the component
Can have **markdown** and other elements
::
Examples
::alert{type="info"}
This is an important message!
::
::card{title="My Card"}
Card content with **markdown** support
::
::divider
::
Inline Components
Inline components use the :component-name syntax and can be placed within text:
Check out this :icon-star component in the middle of text.
Click the :button[Submit]{type="primary"} to continue.
The status is :badge[Active]{color="green"} right now.
Syntax variations:
| Syntax | Description |
|---|---|
:icon-check | Standalone inline component |
:badge[New] | Inline component with content |
:badge[New]{color="blue"} | Inline component with content and properties |
:tooltip{text="Hover text"} | Inline component with properties only |
Component Properties
Components support various property syntaxes:
::component{prop="value"}
<!-- Standard key-value pair -->
::
::component{bool}
<!-- Boolean property (becomes :bool="true" in AST) -->
::
::component{#custom-id}
<!-- ID attribute -->
::
::component{.class-name}
<!-- CSS class -->
::
::component{.class-one .class-two}
<!-- Multiple CSS classes -->
::
::component{obj='{"key": "value"}'}
<!-- Object/JSON value -->
::
::component{arr='["item1", "item2"]'}
<!-- Array/JSON value -->
::
::component{multiple="props" bool #id .class}
<!-- Multiple properties combined -->
::
Component Slots
Block components support named slots using the #slot-name syntax:
::card
#header
## Card Title
#content
This is the main content of the card
#footer
Footer text here
::
AST Output:
{
"type": "minimark",
"value": [
[
"card",
{},
[
"template",
{ "name": "header" },
["h2", {}, "Card Title"]
],
[
"template",
{ "name": "content" },
["p", {}, "This is the main content of the card"]
],
[
"template",
{ "name": "footer" },
["p", {}, "Footer text here"]
]
]
]
}
Nested Components
Components can be nested within each other using additional colons:
:::outer-component
Content in outer
::inner-component{variant="compact"}
Content in inner
::
More content in outer
:::
Deep nesting:
::level-1
:::level-2
::::level-3
Content
::::
:::
::
Attributes
MDC Syntax allows adding custom attributes to native markdown elements using {...} syntax after the element.
Strong/Bold Attributes
**bold text**{.highlight #important}
**bold text**{data-value="custom"}
**bold text**{bool}
Italic/Emphasis Attributes
*italic text*{.emphasized}
_italic text_{#custom-id}
Link Attributes
[Link text](url){target="_blank" rel="noopener"}
[Link text](url){.button .primary}
[External](https://example.com){target="_blank" .external-link}
Image Attributes
{.responsive width="800" height="600"}
{.logo #site-logo}
Inline Code Attributes
`code snippet`{.language-js}
`variable`{data-type="string"}
Span Attributes
Create spans with custom attributes:
This is [highlighted text]{.highlight .yellow} in a paragraph.
Attribute Types Summary
| Syntax | Output | Description |
|---|---|---|
{bool} | :bool="true" | Boolean attribute |
{#my-id} | id="my-id" | ID attribute |
{.my-class} | class="my-class" | Class attribute |
{key="value"} | key="value" | Key-value attribute |
{:data='{"key": "val"}'} | data={"key": "val"} | JSON object attribute |
Code Blocks
MDC Syntax provides advanced code block features with metadata support.
Basic Code Block
```javascript
function hello() {
console.log("Hello, World!")
}
```
Language with Syntax Highlighting
```typescript
interface User {
name: string
age: number
}
```
Filename Metadata
Add a filename using [...] brackets:
```javascript [server.js]
const express = require('express')
const app = express()
```
Line Highlighting
Highlight specific lines using {...} syntax:
```javascript {1-3,5}
function example() {
const a = 1 // Lines 1-3 highlighted
const b = 2
const c = 3
return a + b + c // Line 5 highlighted
}
```
Highlighting syntax:
| Syntax | Description |
|---|---|
{3} | Single line |
{1-5} | Range of lines |
{1,3,5} | Multiple specific lines |
{1-3,7,10-12} | Combined ranges and lines |
Combined Metadata
All metadata can be combined in any order:
```javascript {1-3} [utils.ts] meta=value
function hello() {
console.log("Hello")
}
```
Special Characters in Filename
Use backslash to escape special characters:
```typescript [@[...slug\].ts]
// Brackets and special chars are supported
// Backslash escapes special characters
```
AST Structure
Code blocks produce this AST structure:
{
"type": "minimark",
"value": [
[
"pre",
{
"language": "javascript",
"filename": "server.js",
"highlights": [1, 2, 3],
"meta": "meta=value"
},
[
"code",
{ "class": "language-javascript" },
"code content here"
]
]
]
}
Task Lists
MDC Syntax supports GitHub Flavored Markdown task lists:
- [x] Completed task
- [ ] Pending task
- [x] Another completed task
- [ ] Nested pending task
- [x] Nested completed task
Renders as:
- Completed task
- Pending task
- Another completed task
- Nested pending task
- Nested completed task
Features
[x]or[X]for completed tasks[ ]for pending tasks- Works in both ordered and unordered lists
- Supports nesting
HTML Output
<ul class="contains-task-list">
<li class="task-list-item">
<input type="checkbox" disabled checked class="task-list-item-checkbox">
Completed task
</li>
<li class="task-list-item">
<input type="checkbox" disabled class="task-list-item-checkbox">
Pending task
</li>
</ul>
Tables
MDC Syntax supports GitHub Flavored Markdown tables:
| Header 1 | Header 2 | Header 3 |
| -------- | -------- | -------- |
| Cell 1 | Cell 2 | Cell 3 |
| Cell 4 | Cell 5 | Cell 6 |
Aligned Tables
| Left Aligned | Center Aligned | Right Aligned |
| :----------- | :------------: | ------------: |
| Left | Center | Right |
| Text | Text | Text |
Alignment syntax:
| Syntax | Alignment |
|---|---|
:--- | Left |
:---: | Center |
---: | Right |
Inline Markdown in Tables
Tables support inline markdown:
| Feature | Status | Link |
| ------------ | --------------- | ----------------------- |
| **Bold** | *Italic* | [Link](https://example) |
| `Code` | ~~Strike~~ |  |
Excerpts
Use <!-- more --> comment to define an excerpt:
# Article Title
This is the introduction paragraph that will be used as an excerpt.
<!-- more -->
This is the full article content that won't appear in the excerpt.
const result = parse(content)
console.log(result.excerpt) // Contains content before <!-- more -->
console.log(result.body) // Contains full content
See Also
- Parse API - Parsing markdown content
- Auto-Close API - Handling incomplete syntax
- Minimark AST - AST format reference
- Vue Renderer - Rendering in Vue
- React Renderer - Rendering in React