What WEB Lang Is

WEB Lang is a compiler and CLI for .web files.

A .web file is designed to feel like a power doc:

• one source file for the page
• one mental model for structure and styling
• one place to express semantic layout, attributes, metadata, states, and responsive rules
• normal web-native output at the end

That means you author in one language, but ship plain HTML and CSS.

Philosophy

WEB Lang is built around a simple idea:

Rich website layouts should be easy to author without splitting design thinking across too many files too early.

The philosophy behind .web is:

• design and implementation should stay close together
• semantic structure should be easy to read at a glance
• shared styles should be reusable without a framework requirement
• HTML attributes and document metadata should stay explicit
• the final output should still be portable, reviewable, and standards-based

In practice, .web gives designers and developers a common source of truth for a page.

Highlights

• Initialize a new WEB project with web init.
• Author .web source and compile to HTML and CSS.
• Render a compiled page to JPG or PNG with web screenshot.
• Keep a live watch session running with web watch.
• Use semantic type declarations such as Main, Section, Heading1, and Link.
• Define reusable tokens and shared style families in one top-level define { ... } block.
• Add real HTML attributes with ::attrs.
• Add head metadata with ::head.
• Emit browser scripts with ::script.
• Add states with pseudo blocks like ::hover.
• Add responsive behavior with ::media.
• Use compile-time js literals for small generated values.
• Keep an escape hatch with raw for targeted CSS that does not fit the core language.
• Run the package as a CLI with web.

Installation

Install globally:

npm install -g @bytefaceinc/web-lang

Then run:

web init

Or scaffold into a named directory:

web init website

Or compile an existing file:

web home.web

Or render a screenshot:

web screenshot home.web

Or watch for changes:

web watch home.web

For local development in a checkout:

npm link
web init

npm link
web home.web

WEB Lang supports Node.js 18+.

Quick Start

Initialize a starter project in a clean directory:

web init

Initialize the current directory explicitly:

web init .

Initialize a new website folder and create it if it does not exist yet:

web init website

That creates:

• index.web
• index.html
• index.css
• web-lang-agents.md

The generated web-lang-agents.md combines the packaged getting-started guide, CLI guide, and compiler reference into one local file so coding agents can load the current WEB context quickly.

Compile one .web file:

web home.web

Compile the same file without writing the extension:

web home

Compile every .web file in the current directory:

web .

Compile matching files from another directory:

web ./code/*

Render a full-page screenshot at the default width:

web screenshot home.web

Render a viewport-sized JPG with an explicit device scale factor:

web screenshot home.web --jpg 1080 1080 2

Keep a file compiling automatically while you work:

web watch home.web

Keep a watch session running and capture a baseline screenshot plus timed snapshots every 5 minutes:

web watch home.web -s

Each source file compiles to matching output files next to the source:

• home.web -> home.html
• home.web -> home.css

Screenshots are written into a screenshot workspace rooted at the current working directory:

• web screenshot home.web -> web-lang-screenshots/home-YYYY-MM-DD_HH-mm-ss-SSS.jpg
• web screenshot pages/about.web -> web-lang-screenshots/pages/about-YYYY-MM-DD_HH-mm-ss-SSS.jpg

The CLI creates ./web-lang-screenshots automatically the first time it needs it, and appends a human-readable local timestamp to each screenshot filename so repeated captures do not overwrite each other.

When web watch <source> -s is enabled, the watch session uses the same screenshot workspace and filename format. Watch sessions stop automatically after 1 hour of no recent source activity and print a verbose exit summary explaining why the process closed.

When web init runs, it writes web-lang-agents.md into the chosen project root. That file bundles docs/getting-started.md, docs/cli.md, and docs/compiler.md in that order so local agents have one up-to-date context document to read. If you pass a directory like website, WEB creates that directory first when needed.

Programmatic API

WEB Lang can also be used as a Node module:

const { compileFile, compileSource, resolveCompileOutputPaths } = require('@bytefaceinc/web-lang');

const result = compileFile('./home.web');

console.log(result.htmlPath);
console.log(result.cssPath);
console.log(result.stats);

The package exports:

• compileFile(inputPath, options)
• compileSource(source, options)
• resolveCompileOutputPaths(inputPath, options)
• CompilerError

Documentation

Start here:

• Getting Started
• Language Guide
• CLI Guide
• Compiler Reference
• Error Handling

Agent Support

This repo includes committed agent-facing context for the major repository instruction surfaces used by current coding agents:

• AGENTS.md for repo-wide instructions, with scoped overrides in docs/, lib/cli/, and syntax_highlighter/
• CLAUDE.md plus .claude/rules/ for Claude Code
• .github/copilot-instructions.md, .github/instructions/, and .github/agents/ for GitHub Copilot
• web-lang-agents.md and docs/agents/README.md for deeper WEB Lang maintainer context

Generated projects created by web init still receive their own local web-lang-agents.md context file bundled from the packaged getting-started, CLI, and compiler docs.

Why It Feels Different

Many tools ask you to split a page into separate structure, style, metadata, and behavior files very early.

WEB Lang intentionally starts from a different place:

• a page is a document
• a document can still be expressive
• structure and styling are easier to reason about when they live close together

That is why .web is a power doc: it is not only a template format and not only a styling language. It is a single authoring surface for rich website layouts.

Publishing Notes

This package is structured for public distribution with:

• a public-ready package.json
• a CLI binary entry in bin
• a documented Node API export
• a curated files list for clean package contents
• a license file
• package-local docs and branding assets

To preview the published package contents:

npm pack --dry-run