superhtml

# SuperHTML
HTML Validator, Formatter, LSP, and Templating Language Library

## SuperHTML CLI Tool
The SuperHTML CLI Tool offers **validation** and **autoformatting** features for HTML files.

The tool can be used either directly (for example by running it on save), or through a LSP client implementation.

```
$ superhtml
Usage: superhtml COMMAND [OPTIONS]

Commands:
  check         Check documents for errors.
  fmt           Format documents.
  lsp           Start the Language Server.
  help          Show this menu and exit.
  version       Print the version and exit.

General Options:
  --help, -h        Print command specific usage.
  --syntax-only     Disable HTML element and attribute validation.
```

>[!WARNING]
>SuperHTML only supports HTML5 (the WHATWG living spec) regardless of what you put in your doctype (a warning will be generated for unsupported doctypes).

>[!WARNING]
>Templated HTML (Jinja2, Angular, Mustache, ...) is not yet supported when all validation rules are enabled, use `--syntax-only` (or the relative Extension Setting in VSCode) to limit validation to syntax errors to use SuperHTML with templated HTML documents.
>
> Compatibility with popular templating languages is being explored. 


### Diagnostics
SuperHTML validates not only syntax but also element nesting and attribute values.
No other language server implements the full HTML spec in its validation code.

![](.github/helix.png)


### Autoformatting
The autoformatter has two main ways of interacting with it in order to request for horizontal / vertical alignment.

1. Adding / removing whitespace between the **start tag** of an element and its content.
2. Adding / removing whitespace between the **last attribute** of a start tag and the closing  `>`.


>[!TIP]
>Consider using `superhtml fmt --check` in your CI to enforce every change to be performed on normalized HTML files. This is a technique commonly used in Zig (and Go) for source code that can also help streamline frontend development.


#### Example of rule #1
Before:
```html
<div> <p>Foo</p></div>
```

After:
```html
<div>
    <p>Foo</p>
</div>
```

##### Reverse

Before:
```html
<div><p>Foo</p>
</div>
```

After:
```html
<div><p>Foo</p></div>
```

### Example of rule #2
Before:
```html
<div foo="bar" style="verylongstring" hidden >
    Foo
</div>
```

After:
```html
<div foo="bar" 
     style="verylongstring" 
     hidden
>
    Foo
</div>
```

#### Reverse

Before:
```html
<div foo="bar" 
     style="verylongstring"
     hidden>
    Foo
</div>
```

After:
```html
<div foo="bar" style="verylongstring" hidden>
    Foo
</div>
```

### Download
See the Releases section here on GitHub.

### Editor support
#### VSCode
Install the [Super HTML VSCode extension](https://marketplace.visualstudio.com/items?itemName=LorisCro.super) (doesn't require the CLI tool as it bundles a WASM build of the language server).

#### Neovim
This guide assumes that you are already familiar with Neovims built-in package manager [Pack](http