help-14/mechanical-keyboard: A Curated Index of DIY Keyboard Designs

What the list is actually for

The README opens by saying the list "will help you quickly find your favorite layout and you can start DIY your own custom keyboard." That sentence sets the scope precisely. This is a discovery index for people who have already decided to build rather than buy, and who now need to choose a layout and a set of parts. The entries are grouped into keyboard families (normal, ergonomic, ortholinear, numpad and macropad, others) and then into components (controller, case, plate, keycaps), with firmware, tools and tutorials collected under a links heading. Each row gives an image, a name, a link and a one-line description. Nothing more. There is no build log, no bill of materials and no difficulty rating, so the list answers "what exists" rather than "how do I do this". That is a defensible choice for a curated index. It is also the reason the repository feels thin the moment you want to actually order parts: the descriptions are written by whoever contributed the row, and they vary from a full sentence about switch compatibility to a bare product name.

How the repository is organised

The repository is essentially a single document. The top-level entries are .github/ and README.md, so there is no source tree, no build system and no generated site content checked in, even though the project publishes a homepage at mechanical-keyboard.pages.dev. Everything the reader gets is the Markdown file and the images it links to, most of which are hosted on imgur or on the individual projects' own repositories rather than stored locally. That has a practical consequence: the list depends on third-party image hosts, and a dead imgur link leaves a row with a broken thumbnail and no local fallback. The tables are also hand-maintained, which is why the licence badges are inconsistent. Some rows carry a badge for MIT, GPL v3, CC BY 3.0, CC BY-SA 3.0, CERN OHL 1.2 or CERN OHL 2. The SB-147 row, for example, carries a badge reading "No License" and links to choosealicense.com/no-permission/. Several other rows carry the same badge. That inconsistency is not a bug in the rendering; it reflects what the linked projects actually publish, and it is the single most useful signal in the document for anyone planning to reuse a design commercially.

Installing nothing: using the list as a first step

There is nothing to install. The repository has no package, no CLI and no dependencies, so the workflow is to read the README and then follow the link for whichever project matches your layout. Cloning it locally is still useful if you want to search across the whole table or keep a copy while you compare candidates.

Where the index breaks down

The most obvious limitation is that the list is not opinionated. A row tells you that a board is a "compact battleship with a complement of 18 programmable keys" or a "96% Southpaw keyboard, with split space and encoder support", but it never tells you whether the design is finished, whether anyone has successfully built it recently, or whether the files are complete enough to send to a fabricator. The README does not document part availability, group buy status or fabrication notes. For a first-time builder that gap matters more than the layout taxonomy, because the failure mode is not picking the wrong layout, it is picking a design whose files were never finalised. The second limitation is the licence spread. A row badged "No License" is not the same as a permissive one, and the README offers no commentary on what that means for someone who wants to sell a build or modify the files. The third is that the list mixes sources with very different lifespans: some entries point at GitHub repositories, others at Geekhack forum threads, which are discussion boards rather than file hosts. A thread that goes quiet leaves you with no canonical download.

Compared with Keyboard Builders' Digest or the QMK keyboard list

The closest alternative in kind is a community-maintained catalogue such as the QMK keyboard list, which is tied to firmware support rather than to hardware design files. The difference in approach is structural. A firmware-side list only contains boards someone has written a QMK port for, which means every entry is at least electrically understood and testable, but it excludes designs that run other firmware or none at all. This repository makes the opposite trade: it accepts any DIY design regardless of firmware, which is why the README carries a separate firmware links section instead of filtering on it. The cost of that openness is verification. A firmware catalogue has an implicit test, because the port has to compile and run. A hardware index like this one has no equivalent gate, so the reader carries the whole burden of checking whether a design is real and complete. Neither approach is wrong; they answer different questions.

Maintenance and licensing, as far as the repository shows

The repository is not archived and the last push was on 2026-08-18, so the list is being touched, though the README does not describe a release process, a changelog or a contribution policy beyond whatever sits in .github/. There are no releases, so there is no version to upgrade to and no migration cost in the usual sense; the upgrade path is pulling the branch and re-reading the tables. The licensing position is the part that needs care. The repository's own licence is not stated in the README, so the terms under which the list itself is distributed are unconfirmed, while the licence badges describe the linked projects rather than this one. Those badges are summaries, and the entries marked "No License" point at a page explaining that no permission is granted by default. If you intend to fabricate a design or sell a build, read the target project's own licence file rather than the badge in this table.

Editorial conclusion

Adopt this list if you already know you want to build a custom keyboard and need to compare candidate designs by layout, component type and licence before committing to a PCB order. Do not adopt it if you want a shopping recommendation, a switch comparison or a step-by-step build guide; the README carries none of those. Before you order anything, open the specific project's own repository and read its licence file, because the badges here are summaries and several entries are marked as having no licence at all, which is a materially different position from a permissive one.

Frequently asked questions

Official sources

1. help-14/mechanical-keyboard on GitHub
2. Issues
3. Project website
4. README