hacker-news-undocumented: a reference for HN's unwritten rules

What hacker-news-undocumented actually is

The repository contains a LICENSE, a README.md, and an images directory. That is the whole project. There is no build step, no package manifest, no runtime, and no configuration. The README is a long Markdown document titled "A List of Hacker News's Undocumented Features and Behaviors," and its stated purpose is to detail "some of the hidden norms about Hacker News not otherwise covered in the Guidelines and the FAQ."

The audience is narrow and specific. If you have ever wondered why a comment appeared faded, why a submission vanished from the front page without a visible reason, or why a thread you were reading suddenly reordered itself, this document is the index to those behaviours. It is written for people who already use Hacker News and want the mechanics rather than the etiquette. It is not a tutorial for new users, and it does not explain how to submit a link or create an account.

The README carries a disclaimer in italics: the list has no affiliation with Hacker News, Y Combinator, or any YC-backed company. That sentence sets the reliability ceiling for everything below it. This is a community compilation of observed behaviour, sourced largely from staff comments on the site itself, not an official specification.

The karma gates that unlock HN's hidden controls

The most concrete content in the document is a set of numeric thresholds. These are the parts worth quoting because they are falsifiable and easy to check against your own profile.

At 31 Karma, a user can flag submissions and can vouch for a [dead] submission or comment. At 251 Karma, a user can set the colour of the top bar in profile settings, with the default given as #ff6600, and the Y Combinator logo changes colour to match. At 501 Karma, a user gains the ability to downvote another comment.

The document also describes the mechanics around those powers. All comments start at a score of 1 point, and the score is visible only to the author, which the README frames as a measure against bandwagoning. Downvoted comments fall below 1, sink in the thread, and appear desaturated. The floor is -4 points; further downvotes still subtract from the voter's karma but the comment does not go lower. Two restrictions apply: you cannot downvote a direct reply to your own comment, and you cannot downvote more than 24 hours after the original comment was posted. There is no upper limit on a comment score.

Flagging is described as a "super" downvote. Submissions cannot be downvoted, but enough flags strongly reduce a submission's rank or kill it outright, and a submission flagged to death carries a [flagged] tag. The README is candid that flagging is supposed to be reserved for guideline violations but that this is not always how it is used in practice.

Reading this repo locally and using the endpoints it documents

There is nothing to install. The project is a document, and the README is the artifact. The repository layout is LICENSE, README.md, and images, so cloning gives you the text and the screenshots and nothing else.

To read it offline, clone the default branch and open the file:

git clone https://github.com/minimaxir/hacker-news-undocumented.git
cd hacker-news-undocumented

The practical value is in the endpoints the README documents, which you can use without the repository at all. The one most likely to change how you read a thread is the reverse-chronological view. Given a thread at /item?id=42009039, the same conversation in reverse order is at:

# open in a browser
https://news.ycombinator.com/latest?id=42009039

The README states that this works for whole threads and for nested replies to a sub-thread, using that comment's ID. If you are following a live discussion, this is the difference between scrolling to the bottom repeatedly and seeing new comments first.

The README also notes a workaround for comment desaturation: clicking a comment's timestamp takes you to its own page, where the comment is no longer faded. It points to a CSS extension discussed in a linked HN thread for readers who find the fading hard to read generally.

Where the document is thin, and where it can go stale

The largest section of the README is not about features at all. It covers implicit downranking: politics, topics around diversity and inclusion, posts without URLs, paywalled links, tutorials, and perceived favouritism toward YC companies. These entries describe editorial tendencies rather than switches. There is no threshold to check, no endpoint to call, and no way for a reader to confirm the claim from outside. The document is honest about the sourcing, but honesty about sourcing does not make an unverifiable claim verifiable.

The same applies to the Second Chance Pool and the flame-war detector. The README names them and explains what they are for, but a reader cannot observe either one directly. If you need to know why a specific submission was rescued or why a thread was penalised, this document will not tell you.

Staleness is the structural risk. Hacker News is a live site with two named full-time moderators, Dan Gackle and Tom Howard, and the README notes that Scott Bell formerly held that role. Thresholds, tags, and ranking behaviour can change without any change to this repository. The last push to the repository was on 2026-09-20, so the file is current as of that date, but currency of the file and currency of the described behaviour are different things. Nothing in the repository enforces or tests the claims it makes.

What to use instead when you need authoritative answers

The obvious alternative is Hacker News's own documentation: the Guidelines and the FAQ, both linked from the README. The difference in approach is the difference between a specification and a field guide. The Guidelines and FAQ are maintained by the site's operators and describe intended behaviour. This repository collects observed behaviour, including the parts operators have not written down. When the two disagree, the official pages win on policy and this document is more likely to be right about mechanics.

A second alternative is the moderator comment history itself. The README points to the comment threads of dang, tomhow, and sctb, and describes them as providing a pseudo-log of Hacker News moderation. If you want to know how a rule was applied in a specific case, reading those threads is closer to the source than any summary, including this one. The cost is time: there is no index, and you are reading a chronological record.

A third option is the set of bonus features the README lists, which point outward rather than inward: Hacker News Classic, Hacker News Wayback, the Hacker News dataset on BigQuery, official RSS feeds, and Hacker News Search. If your question is about historical data rather than current mechanics, those are the right tools and this repository is not.

Maintenance, licence, and what a contribution costs

The licence is MIT, which permits reuse, modification, and redistribution provided the copyright notice and permission notice are retained. For a document, that means you can fork it, translate it, or embed it in your own material. It does not grant you any rights to Hacker News content, and the MIT licence says nothing about the accuracy of the text. The README's own disclaimer about lack of affiliation is a factual statement, not a legal one, and it is worth reading alongside the licence rather than instead of it.

Upgrade cost is near zero in the software sense and non-zero in the editorial sense. There is no dependency to bump and no version to pin. The work is keeping the claims true. The README invites exactly that: if anything is missing or incorrect, file a GitHub issue or a pull request. Because the repository has no tests and no CI visible in its top-level layout, a pull request is reviewed as prose, and the burden of evidence falls on the contributor.

The last push was on 2026-09-20. There are no releases, which is expected for a document with no build output. If you fork it, the maintenance question you inherit is who checks the karma thresholds and the tag behaviour after HN changes something, because nothing in the repository will tell you that it has.

Editorial conclusion

Adopt this if you moderate, study, or write about Hacker News and need the karma thresholds and mechanics in one place; the README is the entire artifact, so there is nothing to run and nothing to break. Do not adopt it if you need an authoritative source: it states plainly that it has no affiliation with Hacker News, Y Combinator, or any YC-backed company, and every fact in it is a claim about a site that can change without notice. Before relying on any threshold, open the linked HN thread the entry cites and confirm the behaviour still holds, then file an issue or PR if it does not.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. minimaxir/hacker-news-undocumented on GitHub
4. README