allcontributors.org: the All Contributors spec site, its bot and its .all-contributorsrc

What the All Contributors project actually ships

The repository at all-contributors/allcontributors.org is the website and specification for a convention: recognize contributors in the project README, not in a separate CONTRIBUTORS file that nobody opens. The README states the idea plainly: use the project README, or another prominent public documentation page, to recognize the contributions of members of the project community. The output is a table with an avatar, a name and one or more emoji, each emoji standing for a contribution type such as documentation, translation, design, maintenance or answering questions.

That table is the deliverable. Everything else in the repository exists to explain the table, generate it, or keep it in sync. The site is built from MDX content with Astro and the Starlight documentation theme, which is why the primary language listed for the repository is MDX rather than TypeScript. If you came looking for a runtime library that computes contributor statistics, you are looking at the wrong artifact. The packages that do the generating live in the all-contributors GitHub organization, and this site is their documentation.

The audience is maintainers of open source projects who want translation, triage, design and community work to appear next to code commits. It is also for the people who write the tooling: the specification page defines what a valid table looks like, so a bot, a CLI or a GitHub Action can agree on the same format.

How the table, the emoji key and the bot fit together

The mechanism is a marker comment pair inside a Markdown file. In this repository's own README the block is fenced by `<!-- ALL-CONTRIBUTORS-LIST:START - Do not remove or modify this section -->` and a matching end marker, with `<!-- prettier-ignore-start -->` and `<!-- markdownlint-disable -->` around the generated HTML. Tooling rewrites only what sits between the markers. That is the whole data flow: a config file lists contributors and contribution types, a generator reads the config, renders an HTML table, and replaces the marked region in the README.

The config file is `.all-contributorsrc`, and it sits at the top level of this repository just as it would in yours. The README points at the hosted bot for automation: the @all-contributors bot, documented at allcontributors.org/bot/overview, is what most maintainers use. You comment on an issue or pull request with a mention of the bot and the contributor and contribution type, and the bot opens or updates a pull request that edits the table.

The emoji key is the vocabulary. It is published at allcontributors.org/reference/emoji-key/ and is the part of the specification that projects most often get wrong: the emoji are not decorative, they are typed identifiers. A contributor entry that uses the wrong emoji records the wrong kind of work. Because the key is a fixed list rather than free text, tables stay comparable across projects, and that constraint is deliberate.

Running the documentation site locally with pnpm and Astro

This repository is the site, so the install path here builds documentation rather than adding a dependency to your project. The package manifest defines the scripts; `dev` and `start` both run `astro dev`, and `build` runs `astro build`. Note that the manifest shown here does not declare a `packageManager` field, so the pnpm lockfile and workspace file are the signal that pnpm is the expected client.

Install dependencies, then start the development server:

pnpm install
pnpm dev

Astro prints a local URL in the terminal, and that is where you read the specification, emoji key and bot pages from source. To produce the static output that Netlify serves, run the build and then the preview server:

pnpm build
pnpm preview

The repository also wires up two checks worth knowing about before you open a pull request. `pnpm lint` runs markdownlint across `**/*.{md,mdx}`, and `pnpm link-check` runs lychee against the built HTML in `dist/`, remapping the production host to the local directory. There is an offline variant, `pnpm link-check-offline`, for environments without outbound network access. Translations are pulled separately with `pnpm get-translations`, which calls the Crowdin CLI for a fixed list of locales including de, es-ES, fr, hi, id, ja, ko, nl, pl, pt-BR, ro, ru and zh-CN.

Where the All Contributors convention breaks down

The table is a recognition device, not a measurement device. Every emoji carries the same visual weight, so a contributor who answered one question and a contributor who maintained the project for two years appear as rows of equal size. Projects that try to use the table for governance, release credits or funding decisions will find it gives them nothing to rank on. The specification does not define contribution counts, hours or impact, and the README does not claim it does.

The generated block is also hostile to hand editing. The marker comments say not to remove or modify the section, and the surrounding `prettier-ignore` and `markdownlint-disable` comments exist because the generated HTML would otherwise fail formatting and lint rules. If you edit inside the markers by hand, the next bot run or CLI run overwrites you. On a busy repository that means the contributor table is effectively owned by the tool, and a maintainer who wants a hand-written thank-you note has to put it somewhere else.

There is a friction cost that the README does not discuss: the bot responds to comments, which means someone has to remember to invoke it. Contribution types that arrive outside GitHub, such as a conference talk or a design file shared in a chat, have to be added by a human who knows the emoji key. The convention makes non-code work visible; it does not detect it.

All Contributors versus a plain CONTRIBUTORS file or an auto-generated commit list

The obvious alternative is a `CONTRIBUTORS.md` file maintained by hand, or a link to the GitHub contributors graph. The difference is placement and vocabulary. A separate contributors file is a page nobody visits from the project's front door, and the GitHub contributors graph is derived from commit authorship, so it structurally cannot show a translator, a designer or someone who triaged issues. All Contributors puts the table in the README and gives non-code work a named type, which is the entire point of the project.

The second alternative is a tool that generates a contributors list from git history or from a platform API. Those tools answer "who committed" or "who has an account here." All Contributors answers "who did what kind of work," and it answers it from a config file that a human maintains. That is a real trade-off: the config can be wrong, stale or incomplete, while a git-derived list is automatically accurate about the narrow thing it measures. If commit authorship is the only thing you care about, the convention adds a maintenance obligation for no gain.

The third comparison is within the project's own ecosystem. The README mentions the bot and links to the CLI and the `.all-contributorsrc` config, and the site's dependency list includes `astro-contributors`, a package that renders contributor data inside the Astro documentation build. Those are three different integration points for the same specification, so a project can adopt the format without adopting the bot.

Licence, maintenance cost and what a fork inherits

The repository is MIT licensed, and the package manifest declares `"license": "MIT"`. For anyone reusing the site content or the specification text, MIT permits reuse with the licence and copyright notice retained. The emoji key and specification are published on the site itself, so the practical question for an adopter is not the licence of this repository but the licence and maintenance of whichever generator package you install; those live in separate repositories and are not covered by the facts here.

Maintenance cost splits in two. Running the site means tracking Astro, Starlight and the Starlight plugins listed in the manifest, plus Tailwind and the Crowdin CLI. The pinned versions are caret ranges, so a fresh `pnpm install` months from now will resolve newer minor releases than the ones this repository was last built against. The published releases are sparse: v2.17.1 is dated 2023-07-28, v2.17.0 is dated 2022-09-06, and v2.16.3 is dated 2021-04-13. That release cadence belongs to the tooling packages rather than to the site content, and it is a signal to check the specific package you plan to depend on rather than assuming the whole ecosystem moves together.

The last push to this repository was on 2026-09-16, so the site itself has recent activity. Translation work is explicitly open: the README carries a call for translators linking to issue 143 in the all-contributors repository, and Crowdin is configured for the locale list above. A fork that drops Crowdin loses translated pages.

Editorial conclusion

Adopt All Contributors if your project already has a README table or wants non-code contributions visible, and if you accept that the generated HTML block is machine-owned. Do not adopt it if you need a contribution metric for performance reviews or funding decisions; the emoji key records types, not weight. Before committing, read the specification page at allcontributors.org/specification, check the .all-contributorsrc in this repository for the field names your tooling expects, and confirm which of the three contributor-tooling packages your setup will actually use. The last push to this repository was on 2026-09-16.

Frequently asked questions

Official sources

1. all-contributors/allcontributors.org on GitHub
2. License: MIT
3. Project website
4. README
5. Releases