{"id":15393493,"url":"https://github.com/kristoff-it/superhtml","last_synced_at":"2025-05-14T18:02:38.238Z","repository":{"id":245469003,"uuid":"818338493","full_name":"kristoff-it/superhtml","owner":"kristoff-it","description":"HTML Language Server \u0026 Templating Language Library","archived":false,"fork":false,"pushed_at":"2025-04-09T13:08:52.000Z","size":4435,"stargazers_count":942,"open_issues_count":14,"forks_count":38,"subscribers_count":10,"default_branch":"main","last_synced_at":"2025-05-14T18:02:29.537Z","etag":null,"topics":["language-server","language-server-protocol","lsp","lsp-server","templating-engine","zig-package"],"latest_commit_sha":null,"homepage":"","language":"Zig","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/kristoff-it.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2024-06-21T16:15:09.000Z","updated_at":"2025-05-12T18:20:12.000Z","dependencies_parsed_at":"2024-06-22T08:56:19.214Z","dependency_job_id":"b1195253-246d-4342-8702-00687c043aea","html_url":"https://github.com/kristoff-it/superhtml","commit_stats":{"total_commits":123,"total_committers":13,"mean_commits":9.461538461538462,"dds":0.2682926829268293,"last_synced_commit":"b684bbe28ecd740a7110ead5674355770186ca9c"},"previous_names":["kristoff-it/super-html","kristoff-it/superhtml"],"tags_count":13,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kristoff-it%2Fsuperhtml","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kristoff-it%2Fsuperhtml/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kristoff-it%2Fsuperhtml/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kristoff-it%2Fsuperhtml/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kristoff-it","download_url":"https://codeload.github.com/kristoff-it/superhtml/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254198452,"owners_count":22030964,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["language-server","language-server-protocol","lsp","lsp-server","templating-engine","zig-package"],"created_at":"2024-10-01T15:19:29.928Z","updated_at":"2025-05-14T18:02:38.162Z","avatar_url":"https://github.com/kristoff-it.png","language":"Zig","readme":"# SuperHTML\nHTML Language Server and Templating Language Library\n\n\n## HTML Language Server\nThe Super CLI Tool offers **syntax checking** and **autoformatting** features for HTML files.\n\nThe tool can be used either directly (for example by running it on save), or through a LSP client implementation.\n\n```\n$ superhtml\nUsage: superhtml COMMAND [OPTIONS]\n\nCommands:\n  check         Check documents for syntax errors\n  interface, i  Print a SuperHTML template's interface\n  fmt           Format documents\n  lsp           Start the Super LSP\n  help          Show this menu and exit\n  version       Print Super's version and exit\n\nGeneral Options:\n  --help, -h   Print command specific usage\n```\n\n\u003e[!WARNING]\n\u003eSuperHTML currently only supports UTF8-encoded HTML and assumes HTML5 compliance (e.g. doesn't support XHTML, regardless of what you define the doctype to be).\n\n### Diagnostics\n\n![](.github/vscode.png)\n\nThis language server is stricter than the HTML spec whenever it would prevent potential human errors from being reported.\n\n\nAs an example, HTML allows for closing some tags implicitly. For example the following snippet is correct HTML.\n\n```html\n\u003cul\u003e\n  \u003cli\u003e One\n  \u003cli\u003e Two\n\u003c/ul\u003e\n```\n\nThis will still be reported as an error by SuperHTML because otherwise the following snippet would have to be considered correct (while it's most probably a typo):\n\n```html\n\u003cli\u003eitem\u003cli\u003e\n```\n\n### Autoformatting\n![](.github/vscode-autoformat.gif)\n\nThe autoformatter has two main ways of interacting with it in order to request for horizontal / vertical alignment.\n\n1. Adding / removing whitespace between the **start tag** of an element and its content.\n2. Adding / removing whitespace between the **last attribute** of a start tag and the closing  `\u003e`.\n\n\n#### Example of rule #1\nBefore:\n```html\n\u003cdiv\u003e \u003cp\u003eFoo\u003c/p\u003e\u003c/div\u003e\n```\n\nAfter:\n```html\n\u003cdiv\u003e\n    \u003cp\u003eFoo\u003c/p\u003e\n\u003c/div\u003e\n```\n\n##### Reverse\n\nBefore:\n```html\n\u003cdiv\u003e\u003cp\u003eFoo\u003c/p\u003e\n\u003c/div\u003e\n```\n\nAfter:\n```html\n\u003cdiv\u003e\u003cp\u003eFoo\u003c/p\u003e\u003c/div\u003e\n```\n\n#### Example of rule #2\nBefore:\n```html\n\u003cdiv foo=\"bar\" style=\"verylongstring\" \u003e\n    Foo\n\u003c/div\u003e\n```\n\nAfter:\n```html\n\u003cdiv\n   foo=\"bar\"\n   style=\"verylongstring\"\n\u003e\n    Foo\n\u003c/div\u003e\n```\n\n##### Reverse\n\nBefore:\n```html\n\u003cdiv\n   foo=\"bar\"\n   style=\"verylongstring\"\u003e\n    Foo\n\u003c/div\u003e\n```\n\nAfter:\n```html\n\u003cdiv foo=\"bar\" style=\"verylongstring\"\u003e\n    Foo\n\u003c/div\u003e\n```\n\n### Editor support\n#### VSCode\nInstall the [Super HTML VSCode extension](https://marketplace.visualstudio.com/items?itemName=LorisCro.super).\n\n#### Neovim\n1. Download a prebuilt version of `superhtml` from the Releases section (or build it yourself).\n2. Put `superhtml` in your `PATH`.\n3. Configure `superhtml` for your chosen lsp\n\n\t- ##### [Neovim Built-In](https://neovim.io/doc/user/lsp.html#vim.lsp.start())\n\n\t\t```lua\n\t\tvim.api.nvim_create_autocmd(\"Filetype\", {\n\t\t\tpattern = { \"html\", \"shtml\", \"htm\" },\n\t\t\tcallback = function()\n\t\t\t\tvim.lsp.start({\n\t\t\t\t\tname = \"superhtml\",\n\t\t\t\t\tcmd = { \"superhtml\", \"lsp\" },\n\t\t\t\t\troot_dir = vim.fs.dirname(vim.fs.find({\".git\"}, { upward = true })[1])\n\t\t\t\t})\n\t\t\tend\n\t\t})\n\t\t```\n\n\t- ##### [LspZero](https://github.com/VonHeikemen/lsp-zero.nvim)\n\n\t\t```lua\n\t\tlocal lsp = require(\"lsp-zero\")\n\n\t\trequire('lspconfig.configs').superhtml = {\n\t\t\t\tdefault_config = {\n\t\t\t\t\t\tname = 'superhtml',\n\t\t\t\t\t\tcmd = {'superhtml', 'lsp'},\n\t\t\t\t\t\tfiletypes = {'html', 'shtml', 'htm'},\n\t\t\t\t\t\troot_dir = require('lspconfig.util').root_pattern('.git')\n\t\t\t\t}\n\t\t}\n\n\t\tlsp.configure('superhtml', {force_setup = true})\n\t\t```\n\n#### Helix\n\nIn versions later than `24.07` `superhtml` is supported out of the box, simply add executable to your `PATH`.\n\nFor `24.07` and earlier, add to your `.config/helix/languages.toml`:\n```toml\n[language-server.superhtml-lsp]\ncommand = \"superhtml\"\nargs = [\"lsp\"]\n\n[[language]]\nname = \"html\"\nscope = \"source.html\"\nroots = []\nfile-types = [\"html\"]\nlanguage-servers = [ \"superhtml-lsp\" ]\n```\nSee https://helix-editor.com for more information on how to add new language servers.\n\n#### [Flow Control](https://github.com/neurocyte/flow)\nAlready defaults to using SuperHTML, just add the executable to your `PATH`.\n\n#### Vim\nVim should be able to parse the errors that `superhtml check [PATH]`. This\nmeans that you can use `:make` and the quickfix window to check for syntax\nerrors.\n\nSet the `makeprg` to the following in your .vimrc:\n```\n\" for any html file, a :make\u003ccr\u003e action will populate the quickfix menu\nautocmd filetype html setlocal makeprg=superhtml\\ check\\ %\n\" if you want to use gq{motion} to format sections or the whole buffer (with gggqG)\nautocmd filetype html setlocal formatprg=superhtml\\ fmt\\ --stdin\n```\n\n#### Zed\n\nSee [WeetHet/superhtml-zed](https://github.com/WeetHet/superhtml-zed).\n\n#### Other editors\nFollow your editor specific instructions on how to define a new Language Server for a given language / file format.\n\n*(Also feel free to contribute more specific instructions to this readme / add files under the `editors/` subdirectory).*\n\n## Templating Language Library\nSuperHTML is also a HTML templating language. More on that soon.\n\n## Contributing\nSuperHTML tracks the latest Zig release (0.13.0 at the moment of writing).\n\n### Contributing to the HTML parser \u0026 LSP\nContributing to the HTML parser and LSP doesn't require you to be familiar with the templating language, basically limiting the scope of what you have to worry about to:\n\n- `src/cli.zig`\n- `src/cli/`\n- `src/html/`\n\nIn particular, you will care about `src/html/Tokenizer.zig` and `src/html/Ast.zig`.\n\nYou can run `zig test src/html/Ast.zig` to run parser unit tests without needing to worry the rest of the project.\n\nRunning `zig build` will compile the Super CLI tool, allowing you to also then test the LSP behavior directly from your favorite editor.\n\nThe LSP will log in your cache directory so you can `tail -f ~/.cache/super/super.log` to see what happens with the LSP.\n","funding_links":[],"categories":["Zig"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkristoff-it%2Fsuperhtml","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkristoff-it%2Fsuperhtml","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkristoff-it%2Fsuperhtml/lists"}