# joshbuchea/HEAD: a reference list for HTML head elements
> HEAD is a CC0 reference list of meta tags, link relations and social markup for the HTML head, published at htmlhead.dev. It is a document, not a library, so its value depends on how current its entries are and how you fold them into your own build.
**joshbuchea/HEAD** — A simple guide to HTML elements
- Repository: https://github.com/joshbuchea/HEAD
- Website: https://htmlhead.dev
- Stars: 30,272 · Forks: 1,912
- Language: Unknown
- License: not declared
- Published: 2026-09-10 · Updated: 2026-09-10 · Language: en
- Canonical page: https://hysenlabs.com/projects/joshbuchea-head
## The problem HEAD solves: head markup is scattered across vendor docs
The HTML head is where you declare character encoding, viewport behaviour, the document title, canonical URLs, favicons, social preview cards and a long tail of browser-specific hints. No single specification page collects the practical subset. You find viewport rules in one place, Open Graph in another, Apple touch icon sizes somewhere else, and Chinese browser meta tags almost nowhere in English. HEAD exists to be that collection. It is a guide, not a library: the repository is a README with fenced HTML examples, a DEPRECATED.md file, a .prettierignore and a .github directory. There is no build step, no package manifest and no runtime. The audience is anyone hand-writing a document head or reviewing one: front-end developers, template authors, and people auditing a page's SEO and social metadata. The project's own description calls it "a simple guide to HTML `` elements", and the table of contents backs that up, covering meta, link, scripts, icons, social, browsers and platforms, app links and a deprecated section.
## How the guide is organised, and the ordering rule that carries real weight
The README opens with a Recommended Minimum block: `meta charset`, `meta name="viewport"` and `title`. It then lists valid head elements (`meta`, `link`, `title`, `style`, `script`, `noscript`, `base`) and gives a Recommended Order. That ordering section is the most opinionated part of the document and the part most likely to change how you write a template. It places `meta charset` first and notes it must appear within the first 1024 bytes of the document, then viewport, then title, then other meta tags, then Open Graph, then canonical and other link tags, then resource hints, stylesheets, favicons and scripts last. The stated reason for putting title after encoding and viewport is to prevent potential re-rendering. The ordering of `preconnect` and `dns-prefetch` before stylesheets is framed as maximising their value. Scripts are pushed to the end with a note to use `defer` or `async` where possible. Structure follows the same pattern throughout: each category is a fenced HTML block with inline comments explaining what the tag does and where it belongs. The Meta section, for instance, groups encoding, viewport, Content-Security-Policy, theme-color, color-scheme, description, robots, verification tokens and more into one long annotated block. The Social section splits into Open Graph, Schema.org, Google JSON-LD Schema, Pinterest, OEmbed, QQ/Wechat, Dublin Core and Fediverse. There is also a Browsers (Chinese) section covering 360 Browser, QQ Mobile Browser and UC Mobile Browser, which is unusual in an English-language reference and reflects the guide's contributor base.
## Using HEAD on a real page: copy the minimum, then layer
There is nothing to install. The README does not give an install command, a package name or a version, and the repository has no manifest. You read the guide at htmlhead.dev or in README.md and copy the snippets into your own template. Start with the Recommended Minimum block, which the README says should come as early as possible in the head, before any other head element:
```html
Page Title
```
After that, add the tags your page actually needs. The README's own ordering example shows the full shape, including description, Open Graph, canonical, resource hints, stylesheet, icon and a deferred script:
```html
Page Title
```
What you should see is a head that validates in order and does not block rendering on scripts. Two details in the README are easy to miss and worth acting on. The Content-Security-Policy example carries a comment that the tag only applies to resources declared after it, so it belongs as early in the head as possible. And `meta name="description"` is annotated with a 150-character limit, with the caveat that the content may be used as part of search engine results, not that it will be.
## Where HEAD stops being the right tool
HEAD is a static document, and it behaves like one. It cannot tell you that a tag you copied is wrong for your framework, and it cannot check that your page actually emits the tags you intended. If your head is generated by a framework, a CMS or a tag manager, the guide's examples are a specification for what the output should look like, not code you paste. The repository layout confirms this: README.md, DEPRECATED.md, .prettierignore and .github, with no test suite, no schema and no machine-readable index of the tags it lists. You cannot import it, lint against it, or diff your rendered head against it without writing that tooling yourself. There is also a currency problem inherent to the genre. Head markup is full of vendor-specific tags that vendors quietly retire, which is presumably why a DEPRECATED.md file exists at the repository root; the README's own table of contents has a Deprecated section. That file is the first place to look before copying anything unusual, and the README does not document a deprecation policy or a review cadence for the entries. Treat every non-standard tag as something to verify against the vendor's current documentation, not as settled.
## HEAD against generated-head tooling
The obvious alternative is a framework-level head manager, and the difference is not quality but category. A head manager is a runtime or build-time API: you declare title, description and social tags as data in your components, and the library merges them, deduplicates them and renders the final head. HEAD gives you the markup and the ordering rationale, and you place it yourself. If your site has per-route social images, dynamic titles or a component tree, the manager solves the assembly problem that HEAD does not address at all. If you are writing a static page, an email template or a server-rendered document where you control the head directly, the manager adds a dependency and an abstraction for something you can write in twenty lines. A second alternative is a validation tool: an HTML validator or a head-specific linter will tell you that your markup is malformed or that a required tag is missing. HEAD will not. What HEAD does that neither of those does is explain the ordering constraints, such as the 1024-byte placement of the charset declaration and the reason title sits after viewport, and cover vendor-specific and regional tags that general tooling ignores.
## Maintenance, licence and what you are actually depending on
The repository was last pushed on 2026-05-28, and it is not archived. There are no releases. That is consistent with a document: the README is the artefact, and changes arrive as edits to it. For a consumer, the maintenance question is not whether the project ships versions but whether the entries you copied are still correct, and the only in-repo signal for that is DEPRECATED.md. The licence is CC0, shown in the README badge and linked to creativecommons.org/publicdomain/zero/1.0. CC0 is a public domain dedication rather than a permissive licence with attribution conditions, which in practice means the snippets carry no attribution obligation. That matters more than usual here because the content is HTML markup you will paste into your own source files. This is a description of what the README states, not legal advice; if your organisation has a policy on public domain dedications or on copying third-party code into a codebase, run it past whoever owns that policy. Practically, the upgrade cost is near zero because there is nothing to upgrade, and the adoption cost is the review time you spend deciding which of the listed tags your pages actually need.
## Reading the guide without copying it wholesale
The temptation with a list like this is to paste everything. The README's own Recommended Minimum argues against that: it identifies three elements as essential and treats the rest as situational. Several entries are explicitly conditional in their comments. `meta name="application-name"` is annotated as only for sites used as an app. `google-site-verification`, `yandex-verification`, `msvalidate.01`, `p:domain_verify` and `norton-safeweb-site-verification` are per-service tokens that only apply if you have registered with that service. The Chinese browser section applies if you target those browsers. Approaching the guide as a menu, with the Recommended Order as the assembly instruction, gets you a head that is both complete for your case and free of tags you cannot justify. The repository's Related Projects and Translations sections in the table of contents point to adjacent work, but the README excerpt here does not describe their contents, so check those sections directly if you need a translation or a tool rather than a reference.
## Conclusion
Adopt HEAD if you write or review HTML head markup by hand and want one page that covers encoding, viewport, social tags and browser-specific meta in a single pass. Skip it if you need a build plugin, a linter or a framework integration: the repository is a README plus a DEPRECATED.md and a .github directory, with no package to install. Before relying on it, check the Recommended Order section against your own template and confirm each entry you copy is not listed in DEPRECATED.md.
## FAQ
### What do you put in the head of HTML?
The README's Recommended Minimum lists three elements: `meta charset="utf-8"`, `meta name="viewport" content="width=device-width, initial-scale=1"` and `title`. It also names the valid head elements as meta, link, title, style, script, noscript and base.
### What is the difference between the head and body sections?
The README does not compare the two sections directly. It describes head elements as providing information for how a document should be perceived and rendered by browsers, search engines and bots, which is the scope it covers.
### What is a head section?
HEAD treats it as the part of the document holding valid elements such as meta, link, title, style, script, noscript and base. The README says these elements tell web technologies how the document should be perceived and rendered.
### What does head title do in HTML?
The README describes `` as setting the document's title, and its Recommended Order places it after the encoding and viewport declarations to prevent potential re-rendering.
## Sources
- [Issues](https://github.com/joshbuchea/HEAD/issues)
- [joshbuchea/HEAD on GitHub](https://github.com/joshbuchea/HEAD)
- [Project website](https://htmlhead.dev)
- [README](https://github.com/joshbuchea/HEAD/blob/master/README.md)
---
Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/joshbuchea-head