Introduction
humans.txt is an initiative, started at humanstxt.org, “for knowing the people behind a
website”: a text file with information about the people who contributed to building it. Its authors say they chose a text file because it
is simple and fast to make and does not touch the site’s code. It is not a standard of a standards body, and it defines almost no rules.
Structure
The pages say: create a text file called humans.txt, “always in lower-case”, UTF-8 encoded; put it in the site root next to
robots.txt; optionally point to it from the page head with <link rel="author" href="humans.txt" />. “For the sake of
clarity” the headings /*TEAM*/ and /*SITE*/ separate the team from the other information. For each person: role, name,
contact, Twitter, location and so on. About the site: the date of the last update (YYYY/MM/DD), the main language, the Doctype, components,
tools and software. The template on the page:
/* TEAM */
Your title: Your name.
Site: email, link to a contact form, etc.
Twitter: your Twitter username.
Location: City, Country.
/* THANKS */
Name: name or url
/* SITE */
Last update: YYYY/MM/DD
Standards: HTML5, CSS3,..
Components: Modernizr, jQuery, etc.
Software: Software used for the development
“You are free to add any information you want.” Nothing in the file is required, and the one format the pages state is the date
YYYY/MM/DD.
In the explorer
Drop a file named humans.txt on the explorer to see each /* HEADING */ as a group of lines, each Name: value
line as a field (the template’s own field names are labelled), and any other line as text. A Fields tab lists every field with its
section; a line that starts with # or // is shown as a comment (the pages define no comment syntax: our reading, because real files use
them). The Issues the viewer raises are a Last update value that is not YYYY/MM/DD and, for a file that is not UTF-8
(humanstxt.org asks for UTF-8), a UTF-8 Issue; a heading other than TEAM, THANKS or SITE is labelled and allowed. A Fields table of more than 5,000
rows is paged, 200 at a time with Previous and Next, and the Overview says so: no field is left out.
A file is recognised as humans.txt by its name and its content. By name (how a dropped or listed humans.txt reaches the
viewer): after any blank lines and # or // comment lines, the first line is a /* TEAM */, /* THANKS */ or
/* SITE */ heading and the file holds at least one Name: value line; free text under the headings is allowed, so the real
humans.txt of html5rocks.com (67 fields, many lines of free text) opens in the viewer. The stricter content test (the first line with content is any
/* … */ heading, and at least two of every three lines are headings or Name: value lines) is kept for callers that have no
name. Files that are only prose or ASCII art, such as the humans.txt of some large sites, are not recognised and open as plain text as before; so
does any other file called humans.txt (an HTML error page, an empty file). There is no size limit on the claim; the viewer says "too
large" above 8 MiB.
Not described
Known, not yet covered
- Viewer: free-form humans.txt files (prose, a list of names with no headings, ASCII art) are not recognised; they open as plain text.
- Viewer: the text is shown plain: there is no highlighting family for humans.txt.
- Viewer: a humans.txt whose first heading is not TEAM, THANKS or SITE, or that has no heading, is recognised only by the strict test; by name alone it opens as plain text (a name claim on any
/* … */line would claim random text; this limit is ours, not the specification's). - Viewer: a line is a field when it holds a colon within its first 40 characters, so an indented free-text line with a URL (the "http:" in html5rocks.com's team list) is listed as a field; the pages define no field syntax, so this is our reading.
- Viewer: a file over 8 MiB gets a size message instead of a tree.
Unknown
- Reference: the field names beyond the template (the pages say “role, name, contact, twitter, geolocation, etc.”): there is no list, so unknown fields are shown without a label.
- Reference: how any program reads the file: the pages describe no parser.
Links
Reference
- humanstxt.org – the initiative and its explanation
- humanstxt.org: quick start – the template and the guidelines