HTML Components

HTML components (.com.html files) are the simplest way to create reusable markup in Tkeron. Pure HTML that gets inlined at build time.

Quick Start

Create a file named with .com.html extension:

<!-- my-button.com.html -->
<button class="btn">Click me</button>

Use it with a matching custom element:

<!-- index.html -->
<my-button></my-button>

Build, and the custom element is replaced with the component's content.

How They Work

Component Naming

Component filenames must:

• End with .com.html
• Use lowercase with hyphens
• Contain at least one hyphen (custom element requirement)

Component Resolution

Tkeron looks for components in this order:

1. Same directory as the file using it (highest priority)
2. Any subdirectory of websrc/ via glob search (**/${tagName}.com.html)

websrc/
├── index.html
├── my-header.com.html         # Found by any file
├── components/
│   └── my-card.com.html       # Also found by any file (glob)
├── blog/
│   ├── post.html
│   └── post-comment.com.html  # Found by blog/post.html (local priority)

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

Build Process

Before Build:  <user-card></user-card>
After Build:   <div class="card">...</div>

The .com.html file is NOT copied to output — only its content is inlined.

Examples

Header Component

<!-- site-header.com.html -->
<header class="site-header">
  <div class="container">
    <h1 class="logo">My Website</h1>
    <nav>
      <a href="/">Home</a>
      <a href="/about">About</a>
      <a href="/contact">Contact</a>
    </nav>
  </div>
</header>

Nested Components

Components can use other components:

<!-- user-avatar.com.html -->
<div class="avatar">
  <img src="/avatars/default.jpg" alt="User" />
</div>

<!-- user-card.com.html -->
<div class="user-card">
  <user-avatar></user-avatar>
  <div class="user-info">
    <h3>John Doe</h3>
  </div>
</div>

Multiple Root Elements

<!-- two-columns.com.html -->
<div class="column">
  <h2>Column 1</h2>
</div>
<div class="column">
  <h2>Column 2</h2>
</div>

Limitations

• No dynamic content — Can't read attributes or use logic
• No slots or Shadow DOM — No content projection
• No circular dependencies — Components can't include themselves
• Max nesting depth — 50 levels

For dynamic content, use TypeScript Components.

Best Practices

✅ Use for static UI patterns: Headers, footers, cards, navigation ✅ Keep components small and focused ✅ Name descriptively: user-profile-card.com.html, not thing.com.html ✅ Organize by feature: Group related components in directories

❌ Don't use for dynamic content — Use TypeScript Components instead

Next Steps

• TypeScript Components — Dynamic components with attributes
• Markdown Components — Content in Markdown
• Pre-rendering — Build-time DOM manipulation
• Best Practices — Patterns and tips