keebfolio.netlify.app

What is Keebfolio?

Keebfolio is a curated directory of open-source mechanical keyboard projects, hosted at Keebfolio. It collects 204 projects in one place and organizes them by category rather than by vendor or store, so it works as a starting point for research instead of a shop.

What it covers

• Keyboards — grouped by layout type: staggered (52 traditional layouts), ortholinear (26 grid layouts), split (71 ergonomic split keyboards), and other (55 macropads, numpads and similar).
• Resources — firmware options such as QMK and ZMK, plus tools like PCB generators, layout editors and utilities, and tutorials including build guides.
• Miscellaneous — 3D prints, keycaps, controllers and related parts.
• Recent updates — a dated commit-style log of additions and site changes, useful for spotting what is new since your last visit.

Who it suits

• First-time builders choosing a layout: browse the split and ortholinear sections to see how many established designs exist before committing to a shape.
• Experienced builders looking for firmware or tooling: the resources section is the fastest route to options beyond the mainstream.
• Designers and tinkerers wanting prior art: seeing 204 projects grouped by type makes gaps and recurring patterns easier to spot.

Trade-offs to expect

A curated list is not a buying guide. Entries point to open-source projects, so you still need to check each project's own documentation, parts availability, group-buy status and build difficulty. Categories overlap too — a split ortholinear board could reasonably sit in either section, so search across categories rather than trusting one label.

Next step: if you already know your layout preference, open that category first and shortlist two or three projects; then compare their firmware support and part sourcing before picking one.

How do I choose between a staggered, ortholinear, or split keyboard for my first build?

Start by matching the layout to the problem you actually want solved. For a first build, staggered is the lowest-risk option, ortholinear is the cheapest way to test whether column alignment suits you, and split is the most involved but the only one that directly addresses shoulder and wrist posture.

What each layout is good for

• Staggered (52 projects on Keebfolio): the familiar row-offset layout found on almost every laptop and office keyboard. Choose it if your main goal is learning to solder, flash firmware and assemble a case without also relearning typing. Your existing muscle memory transfers immediately, and troubleshooting advice is easiest to find.
• Ortholinear (26 projects): keys sit in a straight grid rather than offset rows. Choose it if you suspect your fingers travel further than necessary on a staggered board, or you want a compact 40–50% footprint. Expect an adjustment period of days to weeks; numbers and punctuation often move to layers.
• Split (71 projects): two independent halves, usually with tenting or angled placement. Choose it if you have shoulder, wrist or forearm discomfort, or you want your hands at shoulder width. It is also the most demanding first build: two controllers, two cases, and often a TRRS or similar interconnect to get right.

A quick comparison

How to decide

Pick staggered if this is your first time soldering or flashing firmware and you want a finished keyboard rather than a project. Pick ortholinear if you already build electronics confidently and want to test a different typing geometry cheaply. Pick split if comfort is the reason you are here at all — a staggered build will not fix shoulder width.

A practical middle path: build a small macropad or numpad first. Keebfolio groups these under "Other" (55 projects), and the soldering and firmware steps are nearly identical to a full board at a fraction of the cost and time.

To browse candidates, filter by your chosen layout on Keebfolio, then check the firmware and tutorial sections before committing — a board with a well-documented build guide matters more for a first attempt than any spec.

Which open-source firmware should I use for a custom keyboard, and how do QMK, ZMK, and alternatives differ?

Start with the constraint that matters most: whether your keyboard is wired or wireless. That single choice usually decides between QMK and ZMK before you compare features.

QMK is the default for wired custom keyboards. It runs on AVR and ARM controllers, supports the widest range of boards and community keymaps, and is the firmware most group-buy kits assume. Choose it if you want maximum hardware compatibility, mature tooling, and a large pool of existing configurations to adapt.

ZMK is the natural choice for wireless split keyboards, especially those built on nice!nano-style controllers. It is designed around Bluetooth and low power, with a configuration approach that many users find cleaner than editing C files. The trade-off is narrower hardware support and a smaller, though active, ecosystem.

Alternatives fill gaps rather than replace both. KMK runs on CircuitPython, which suits people who prefer Python and quick iteration over compiling firmware. QMK and ZMK remain the mainstream options; other projects tend to be board-specific or experimental.

Practical comparison

Keebfolio is useful here because it groups projects by layout and links firmware, tools and tutorials in one place, so you can check what a specific board actually uses before committing. Browse Keebfolio by layout type, then open the firmware section to see which options appear alongside the boards you like.

A sensible next step: pick two or three keyboards from the list that match your layout preference, note the controller each one specifies, and let that determine the firmware. If you are undecided on hardware, ZMK keeps wireless options open; if you already own a wired kit, QMK is the safer path. For official documentation, check QMK and ZMK.

What tools do I need to design a custom PCB or keymap for a mechanical keyboard?

You need two separate toolchains: one for the circuit board (schematic capture, PCB layout, and often a keyboard-specific generator), and one for the keymap (firmware plus a configurator or code editor). Keebfolio is a curated index of 204 open-source mechanical keyboard projects, and its Resources section is organised into exactly these categories — Firmware, Tools, Tutorials — which makes it a reasonable starting point for finding candidates rather than a tool itself. See Keebfolio.

PCB design: pick one path

Keebfolio lists PCB generators, layout editors and utilities together under Tools, so it's worth browsing that list before defaulting to a general EDA package. For a first board, a generator plus a simple ortholinear or staggered layout is the lowest-risk route; save full EDA work for a split ergonomic board with custom geometry.

Keymap: firmware first, then an editor

Firmware choices in the index include QMK, ZMK and others, with a separate firmware list and a Smart Keymap entry among the updates. The practical split:

• Wired boards — QMK is the common default, configured either by editing keymap files in code or through a graphical configurator.
• Wireless/split boards — ZMK is the usual choice, with keymaps written in a devicetree-style file and built in the cloud.
• Visual editing — layout editors and keymap tools let you drag keys and export a keymap, which suits anyone who doesn't want to learn the firmware's config language.

A concrete scenario: you want a 4x12 ortholinear board with a rotary encoder. Use a generator to produce the matrix and encoder footprint, order the board, then write a QMK keymap with the encoder mapped to volume and layer switching. If you later go wireless, expect to rewrite the keymap for ZMK rather than port it directly.

Decision criteria

Choose a generator if your layout is close to a standard row-staggered, ortholinear or common split design. Choose full EDA if you need a novel shape or integrated MCU. Choose a visual keymap editor if you'll iterate on layers often and don't want to rebuild firmware by hand; choose code-based keymaps if you need advanced features like tap-hold tuning or custom C.

A useful next step is to open Keebfolio's Firmware and Tools lists side by side and note which entries support your intended controller and connection type before you start drawing anything.

Where can I find beginner-friendly tutorials and build guides for a DIY mechanical keyboard?

Keebfolio collects open-source mechanical keyboard projects and also links out to build guides and learning resources. Its own "Tutorials" section is described as build guides and learning resources, so it is a reasonable starting point when you want a guided path rather than just a parts list. Because Keebfolio is a curated index, expect it to point you toward external guides rather than host a full step-by-step course itself.

A practical way to use it: pick your layout first, then follow the matching resource.

• Staggered (52 projects) — the familiar row-offset layout. Best if you want the widest choice of beginner kits and guides.
• Ortholinear (26) — grid layout. Fewer projects, but often simpler to hand-wire because keys line up.
• Split (71) — ergonomic two-half builds. More wiring and firmware decisions, so treat these as a second build unless you already solder.
• Other (55) — macropads, numpads and similar. Often the cheapest and least risky first soldering project.

Keebfolio also separates Firmware (QMK, ZMK and others), Tools (PCB generators, layout editors, utilities) and Miscellaneous (3D prints, keycaps, controllers), which maps neatly onto the three skills a first build tests: soldering, flashing firmware, and case/plate sourcing.

For broader beginner material, compare a few established sources:

A concrete first step: open Keebfolio, choose Other or Staggered, pick one project with a linked build guide, and read that guide end to end before buying anything. If the guide assumes tools you do not own — a soldering iron, a multimeter, a 3D printer — that is your signal to start with a macropad instead of a full split ergonomic board.

How can I contribute a new keyboard project or tool to the Keebfolio list?

Contribute through the project's GitHub repository, since Keebfolio is a curated static list rather than a submission form. The maintainer adds entries by commit, and the update log shows a steady pattern of individual keyboards, firmware, tools and guides being merged over time.

What to prepare before you submit

• The project's public repository or official page, so the maintainer can verify it exists and is open source.
• Its keyboard category: staggered, ortholinear, split, or "other" for macropads and numpads. Tools, firmware and tutorials have their own sections.
• A short, factual description. Keebfolio's schema includes a description field, so a one- or two-line summary of what the board or tool does is appropriate.
• A representative image, if the project has one. Recent updates mention image optimization and ortho image updates, so images are expected and get processed.

A practical submission scenario

Suppose you designed a split ergonomic board with an open-source PCB and firmware. You would open a pull request or issue on the repository, placing it under split keyboards, adding your description and image, and linking the source files. If you built a layout editor instead, it belongs in the tools list, as happened with Capistry and Snakeskin.

Decision criteria

• If your project is a physical keyboard, pick the layout category that matches how the keys are arranged, not how it feels to type on.
• If it is software, choose firmware or tools depending on whether it runs on the keyboard or helps you design one.
• If it is documentation, it goes under tutorials.

Next step

Read the repository's README and contribution workflow before opening a request, then check recent commits to match the current entry format. Keebfolio itself is at Keebfolio, and the wider open-source keyboard community around GitHub is where these lists are typically maintained.