ClearHTML — Made for Sesi

A Sesi native compiler for ClearHTML, a readable, human first markup language that compiles to standard HTML. Create pages in descriptive, self-describing syntax and let the Sesi scripts handle the build pipeline and tooling.

---

What is ClearHTML?

ClearHTML is a proposed alternative authoring layer for HTML. It keeps the semantic purpose of HTML while replacing terse, abbreviated tag names with explicit, self-describing ones.

document language="en" {
  metadata {
    character-encoding "utf-8"
    page-title "Neighborhood Library"
  }

  page {
    page-header {
      heading level=1 "Neighborhood Library"
      navigation {
        link to="/" "Home"
        link to="/events" "Events"
      }
    }

    main-content {
      content-section {
        heading level=2 "Welcome"
        paragraph "Our library is open seven days a week."
        link to="/hours" "See library hours"
      }
    }

    page-footer {
      paragraph "© 2026 Neighborhood Library"
    }
  }
}

Compiles to standard, valid HTML with the full ClearHTML design system injected automatically.

---

Project Structure

/
├── src/                    ← Your .chtml source files
│   ├── index.chtml
│   ├── about.chtml
│   └── demo.chtml          ← Generated by `main.sesi`
│
├── out/                    ← Compiled HTML output (generated, do not edit)
│   ├── index.html
│   ├── about.html
│   ├── demo.html
│   ├── clearhtml.css       ← Design system, copied from `assets/`
│   └── generated.css       ← Custom overrides, copied from `assets/`
│
├── assets/
│   ├── clearhtml.css       ← ClearHTML design system (source of truth)
|   └── generated.css       ← Custom overrides (optional)
│
├── bin/
│   ├── chtml.js            ← Unified CLI tool (build, watch, lint, etc.)
│   └── chtml-parser.js     ← Node.js ClearHTML tokenizer & HTML generator
│
├── customize_css.sesi       ← Generate custom CSS styles using Sesi
├── compiler.sesi           ← Sesi compiler: discovers `src/*.chtml`, compiles all
├── main.sesi               ← Demo: creates ClearHTML inside a Sesi prompt block
└── ClearHTML-Proposal.md   ← Full language specification

Requirements

• Node.js (v16+ recommended)
• Sesi runtime (included in node_modules after npm install)

---

Getting Started

Quick Setup

Install dependencies:

npm install

Global CLI Setup (Optional)

To use the chtml command from anywhere in your terminal, run:

npm link

Note: On some systems, you may need to use npm link --force if there are naming conflicts with existing tools.

The chtml CLI

ClearHTML provides a unified CLI tool to manage your project:

# Compile all files in src/ to out/
npm run build

# Watch src/ for changes and recompile automatically
npm run watch

# Run the syntax auditor on all chtml and sesi files
npm run lint

# Fetch remote content
npm run fetch

# Generate custom CSS via Sesi
npm run customize

Direct CLI usage

If you have the binary linked or use node:

chtml build
chtml watch
chtml lint

---

Key Features

• Semantic First: Uses descriptive keywords like main-content and content-section instead of generic tags.
• Component System: Reusable markup with define-component and slot.
• Integrated Tooling: Native Sesi scripts for building, watching, and linting.
• AI-Powered Styling: Customize your design system via natural language prompts using customize_css.sesi.
• Source Mapping: Every generated element can be mapped back to its source line/column for easy debugging.

Create a page inline (Sesi prompt block mode)

npm run demo

main.sesi demonstrates authoring ClearHTML directly inside a Sesi prompt block — the ClearHTML source lives in the script itself, is written to src/demo.chtml, compiled, and output to out/demo.html.

---

ClearHTML Syntax

ClearHTML source files use the .chtml extension.

Document shell

document language="en" {
  metadata {
    character-encoding "utf-8"
    page-title "Page Title"
  }

  page {
    // page content here
  }
}

---

Writing ClearHTML in a Sesi Prompt Block

You can author ClearHTML directly inside a Sesi prompt block. Inner " characters are doubled ("") per Sesi's prompt string rules:

prompt chtmlSource {"document language=""en"" {
  metadata {
    character-encoding ""utf-8""
    page-title ""My Page""
  }

  page {
    main-content {
      content-section {
        heading level=2 ""Hello""
        paragraph ""This was written in a Sesi prompt block.""
      }
    }
  }
}"}

write_file("src/my-page.chtml", chtmlSource)
let html = exec("node bin/chtml-parser.js src/my-page.chtml")
write_file("out/my-page.html", html)

Note: Most special characters (like ©, :, ?, &) and raw URLs are now supported in unquoted content. However, avoid = in unquoted prose, as the parser may mistake it for an element attribute. Use quotes for content containing equals signs.

---

Design System

Every compiled HTML page automatically links to clearhtml.css (base design) and generated.css (custom overrides). clearhtml.css provides:

• Typography — Bricolage Grotesque (headings) + DM Sans (body)
• Color palette — warm cream background (#f7f4ee), terracotta accent (#b54a14), near-black text
• Styled components — header, nav, sections, articles, aside, tables, forms, lists, blockquotes, code blocks, figures
• Responsive layout — centered max-width, mobile-friendly at 640px
• Micro-interactions — hover states on links, nav items, table rows, and form buttons

---

Customize CSS generator

This repository includes a Sesi script that can generate a tailored stylesheet from a short design prompt: customize_css.sesi.

• What it does: reads README.md, src/index.chtml, and out/index.html (if present), prompts a model to produce a complete CSS stylesheet, and writes the result to assets/generated.css.
• Location: customize_css.sesi (repo root).
• Output: assets/generated.css — this file is overwritten each run with a different description; review changes before committing.
• Important: The script expects compiled HTML examples in out/ for context. Run npm run compile first if out/ is missing.

Run the generator locally with:

npm run sesi customize_css.sesi

After running, review assets/generated.css and integrate it into your pages as needed.

How the Compiler Works

src/*.chtml
    ↓  compiler.sesi reads each file
    ↓  exec("node bin/chtml-parser.js <file>")
    ↓  bin/chtml-parser.js tokenizes + parses + generates HTML
    ↓  clearhtml.css injected into <head>
out/*.html + out/clearhtml.css + out/generated.css

The Sesi script (compiler.sesi) is the orchestrator — it handles file discovery, I/O, tool registration, and error reporting. The Node.js parser (bin/chtml-parser.js) is a self-contained, dependency-free recursive descent tokenizer and HTML emitter.

If you want to inspect or run the compilation pipeline manually, run:

node bin/chtml-parser.js src/your-file.chtml > out/your-file.html

---

Adding a New Page

1. Create src/your-page.chtml
2. Run npm run compile
3. Open out/your-page.html

That's it. The compiler discovers all .chtml files in src/ automatically.

---

Scripts

Command	Description
npm run compile	Compile all src/*.chtml → out/*.html
npm run demo	Run the prompt-block demo
npm run compile:single	Compile a single file (stdout)
npm run fetch	Grab an HTML page from a URL & convert to ClearHTML (Experimental)

If your workflow needs a single-file compile helper, npm run compile:single is the quickest way to inspect output on stdout.

---

Documentation

• ClearHTML-Proposal.md — Full proposal with design rationale and migration strategy
• SPECIFICATION.md — Quick reference guide for all ClearHTML elements and attributes
• ROADMAP.md — Future plans and roadmap (phases 1–3)
• CONTRIBUTING.md — How to contribute to the project