MDC Syntax Logo
Syntax

MDC Syntax

Complete guide for writing MDC (Markdown Components) documents with full syntax reference.

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
  • Strikethrough
  • Inline code

Lists

- Item 1
- Item 2
  - Nested item
  - Another nested item
- Item 3
[Link text](https://example.com)
[Link with title](https://example.com "Link title")
![Image alt text](https://example.com/image.png)
![Image with title](https://example.com/image.png "Image 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 data property of ParseResult

Special Fields

FieldDescriptionDefault
titleUsed in table of contents generation-
depthMaximum heading level for TOC2
searchDepthDepth for TOC search2

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

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:

SyntaxDescription
:icon-checkStandalone 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 text](url){target="_blank" rel="noopener"}
[Link text](url){.button .primary}
[External](https://example.com){target="_blank" .external-link}

Image Attributes

![Alt text](image.png){.responsive width="800" height="600"}
![Logo](logo.svg){.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

SyntaxOutputDescription
{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:

SyntaxDescription
{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:

SyntaxAlignment
:---Left
:---:Center
---:Right

Inline Markdown in Tables

Tables support inline markdown:

| Feature      | Status          | Link                    |
| ------------ | --------------- | ----------------------- |
| **Bold**     | *Italic*        | [Link](https://example) |
| `Code`       | ~~Strike~~      | ![Image](img.png)       |

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