Syntax

Markdown

Comark supports all standard CommonMark and GitHub Flavored Markdown (GFM) features including headings, formatting, lists, tables, code blocks, and more.

Comark 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

**Bold text**
*Italic text*
***Bold and italic***
~~Strikethrough~~
`Inline code`

Text nodes in Comark are simple strings, similar to HTML text nodes. To add custom styles, attributes, or metadata to specific parts of text, use the Span Attributes syntax: Hello [world]{data-world="earth" style="color: blue"}.

This creates a <span> element with custom attributes, allowing you to style or add metadata to inline text.

Lists

Unordered

- Item 1
- Item 2
  - Nested item
  - Another nested item
- Item 3

Ordered

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")
![Image alt text](https://example.com/image.png)
![Image with title](https://example.com/image.png "Image title")

Add custom attributes to links and images with the Attributes syntax: [Link](url){target="_blank"}.

Blockquotes

This is a blockquote
And contain other markdown elements like bold and italic

> This is a blockquote
>
> And contain other markdown elements like **bold** and *italic*

Alerts

The alerts plugin is built-in and transforms special blockquotes into styled callout blocks. Place an alert marker on the first line of a blockquote:

> [!NOTE]
> Useful information that users should know, even when skimming content.

> [!TIP]
> Helpful advice for doing things better or more easily.

> [!IMPORTANT]
> Key information users need to know to achieve their goal.

> [!WARNING]
> Urgent info that needs immediate user attention to avoid problems.

> [!CAUTION]
> Advises about risks or negative outcomes of certain actions.

Supported markers: [!NOTE], [!TIP], [!IMPORTANT], [!WARNING], [!CAUTION].

Horizontal Rules

Any of these create a horizontal rule:

---
***
___

Frontmatter

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

These are the rules for frontmatter:

Must be at the very beginning of the document
Enclosed by --- delimiters
Parsed as YAML

The frontmatter property is available from the parse result:

import { parse } from 'comark'

const content = `---
title: My Article
author: Jane Doe
---

# Hello World
`

const { frontmatter } = await parse(content)
/*
{ "title": "My Article", "author": "Jane Doe" }
*/

Code Blocks

Comark provides advanced code block features with metadata support.

Basic Code Block

function hello() {
  console.log("Hello, World!")
}

```javascript
function hello() {
  console.log("Hello, World!")
}
```

Filename Metadata

Add a filename using [...] brackets:

server.js

const express = require('express')
const app = express()

```javascript [server.js]
const express = require('express')
const app = express()
```

Line Highlighting

Highlight specific lines using {...} syntax:

function example() {
  const a = 1
  const b = 2
  const c = 3
  return a + b + c
}

```javascript {1-3,5}
function example() {
  const a = 1
  const b = 2
  const c = 3
  return a + b + c
}
```

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:

utils.ts

function hello() {
  console.log("Hello")
}

```javascript {1-3} [utils.ts] meta=value
function hello() {
  console.log("Hello")
}
```

Special Characters in Filename

Use backslash to escape special characters:

@[...slug\].ts

// Brackets and special chars are supported

```typescript [@[...slug\].ts]
// Brackets and special chars are supported
```

AST Structure

Code blocks produce this AST structure:

[
  "pre",
  {
    "language": "javascript",
    "filename": "server.js",
    "highlights": [1, 2, 3],
    "meta": "meta=value"
  },
  ["code", { "class": "language-javascript" }, "code content here"]
]

Task Lists

Comark supports GitHub Flavored Markdown task lists:

- [x] Completed task
- [ ] Pending task
- [x] Another completed task
  - [ ] Nested pending task
  - [x] Nested completed task

[x] or [X] for completed tasks
[ ] for pending tasks
Works in both ordered and unordered lists
Supports nesting

Tables

Header 1	Header 2	Header 3
Cell 1	Cell 2	Cell 3
Cell 4	Cell 5	Cell 6

| 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

| Left Aligned | Center Aligned | Right Aligned |
| :----------- | :------------: | ------------: |
| Left         | Center         | Right         |
| Text         | Text           | Text          |

Syntax	Alignment
`:---`	Left
`:---:`	Center
`---:`	Right

Inline Markdown in Tables

Feature	Status	Link
Bold	Italic	Link
`Code`	~~Strike~~

| Feature      | Status          | Link                    |
| ------------ | --------------- | ----------------------- |
| **Bold**     | *Italic*        | [Link](https://example) |
| `Code`       | ~~Strike~~      | ![Image](https://picsum.photos/120/30)       |

Comments

HTML-style comments are supported and preserved in the AST but not rendered in output:

<!-- This is a comment -->

Comments can span multiple lines:

<!--
This is a multi-line comment
that can contain any text
-->

Comments are represented in the AST as a tuple with null as the tag:

[null, {}, " comment text "]

Emojis

Comark includes built-in emoji support using the :emoji_name: syntax:

Hello 👋 Welcome to our docs! 🚀

Hello :wave: Welcome to our docs! :rocket:

Popular Emojis

😄 ❤️ 🔥 🚀 ✨ 🎉 🤔 👀 💯 ⭐ ⚡ 💡 ⚠️

:smile: :heart: :fire: :rocket: :sparkles: :tada:
:thinking: :eyes: :100: :star: :zap: :bulb: :warning:

Next Steps

Components - Embed custom components in your Markdown
Attributes - Add classes, IDs, and styles to elements
Comark AST - Understand the AST format
Parse API - Parse markdown content programmatically

Edit this pageorReport an issue

Installation

Install Comark and render your first Markdown with components in Vue, React, or plain HTML in under 5 minutes.

Components

Embed custom components directly in your Markdown with block and inline syntax, props, slots, and nested children.