Markdown Components

Markdown components (.com.md files) let you write reusable content in Markdown that gets converted to HTML and inlined at build time. Powered by Bun's built-in Markdown parser with full GitHub Flavored Markdown (GFM) support.

Quick Start

Create a file named with .com.md extension:

<!-- hero-text.com.md -->

# Welcome to My Site

This is a **great** place to start.

- Fast
- Simple
- Powerful

Use it with a matching custom element:

<!-- index.html -->
<hero-text></hero-text>

Build, and the custom element is replaced with the rendered HTML.

How They Work

Component Naming

Same rules as other components:

• End with .com.md
• Use lowercase with hyphens
• Must contain at least one hyphen

Component Priority

When multiple component types exist for the same name:

1. .com.ts — highest priority
2. .com.html
3. .com.md — lowest priority

Component Resolution

Same as other components:

1. Same directory as the file using it
2. Any subdirectory of websrc/ via glob search

You can organize components in subdirectories and they'll be found automatically.

GFM Features

Full GitHub Flavored Markdown support out of the box:

• Headings — # H1 through ###### H6
• Bold, italic, strikethrough — **bold**, _italic_, ~~strike~~
• Lists — Ordered and unordered
• Links and images — [text](url), ![alt](src)
• Tables — Full GFM table syntax
• Blockquotes — > quoted text
• Code blocks — Fenced with language syntax
• Task lists — - [x] Done

Examples

About Section

<!-- about-section.com.md -->

## About Us

We are a **small team** building great tools.

- Open source
- Community driven
- Built with love

Feature Table

<!-- feature-list.com.md -->

## Features

| Feature     | Description               |
| ----------- | ------------------------- |
| Fast builds | Sub-second build times    |
| Zero config | Works out of the box      |
| Components  | Reusable HTML, TS, and MD |

FAQ Content

<!-- faq-section.com.md -->

## Frequently Asked Questions

### How do I install?

Run `bun install -g tkeron` to install globally.

### How do I build?

Run `tk build` in your project directory.

Nested Components

Markdown components can include other components:

<!-- page-content.com.md -->

# Main Content

Here is some introductory text.

<feature-list></feature-list>

And here is the conclusion.

When to Use

✅ Perfect for: Content-heavy sections, documentation, FAQs, blog content, feature descriptions, text-heavy UI

❌ Not ideal for: Dynamic content (use TypeScript Components), complex layouts (use HTML Components)

Combining Component Types

Use Markdown for content, HTML for layout, and TypeScript for dynamic parts:

websrc/
├── page-layout.com.html      # Layout structure
├── hero-content.com.md        # Content in Markdown
├── user-greeting.com.ts       # Dynamic greeting
├── index.html

Limitations

• No dynamic content — Can't read attributes or use logic
• No circular dependencies — Build fails with clear error
• Max nesting depth — 50 levels
• Static only — Produces static HTML

Next Steps

• HTML Components — Precise HTML structure
• TypeScript Components — Dynamic logic
• Pre-rendering — Build-time transformations
• Best Practices — Patterns and tips