Write structure, styling, metadata, responsive behavior, and small compile-time helpers in one language, then initialize starter projects, compile to standard HTML and CSS, render polished screenshots, or keep a live watch session running while you iterate.
## 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:
```bash
npm install -g @bytefaceinc/web-lang
```
Then run:
```bash
web init
```
Or scaffold into a named directory:
```bash
web init website
```
Or compile an existing file:
```bash
web home.web
```
Or render a screenshot:
```bash
web screenshot home.web
```
Or watch for changes:
```bash
web watch home.web
```
For local development in a checkout:
```bash
npm link
web init
```
```bash
npm link
web home.web
```
WEB Lang supports Node.js `18+`.
## Quick Start
Initialize a starter project in a clean directory:
```bash
web init
```
Initialize the current directory explicitly:
```bash
web init .
```
Initialize a new `website` folder and create it if it does not exist yet:
```bash
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:
```bash
web home.web
```
Compile the same file without writing the extension:
```bash
web home
```
Compile every `.web` file in the current directory:
```bash
web .
```
Compile matching files from another directory:
```bash
web ./code/*
```
Render a full-page screenshot at the default width:
```bash
web screenshot home.web
```
Render a viewport-sized JPG with an explicit device scale factor:
```bash
web screenshot home.web --jpg 1080 1080 2
```
Keep a file compiling automatically while you work:
```bash
web watch home.web
```
Keep a watch session running and capture a baseline screenshot plus timed snapshots every 5 minutes:
```bash
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 -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:
```js
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](./docs/getting-started.md)
- [Language Guide](./docs/language-guide.md)
- [CLI Guide](./docs/cli.md)
- [Compiler Reference](./docs/compiler.md)
- [Error Handling](./docs/error-handling.md)
## Agent Support
This repo includes committed agent-facing context for the major repository instruction surfaces used by current coding agents:
- [AGENTS.md](./AGENTS.md) for repo-wide instructions, with scoped overrides in `docs/`, `lib/cli/`, and `syntax_highlighter/`
- [CLAUDE.md](./CLAUDE.md) plus `.claude/rules/` for Claude Code
- `.github/copilot-instructions.md`, `.github/instructions/`, and `.github/agents/` for GitHub Copilot
- [web-lang-agents.md](./web-lang-agents.md) and [docs/agents/README.md](./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:
```bash
npm pack --dry-run
```
