Closed skullydazed closed 4 years ago
Building on what @jceaser wrote:
readme.md
The readme.md
for a keyboard should have the following information, in order:
layout.json
To help facilitate documentation and configurators we are asking keyboards to start including a layout.json
file. This file describes the layout of your keyboard in keyboard-layout-editor.com raw data code. The first line should be a "decal" saying "Layer 0". All the key legends should be blank.
For keyboards which support multiple layout options you should find a way to represent those options in a unified layout. (FIXME: what do we do when they can't, or when it's cumbersome to do that?)
Example for keyboards/clueboard
:
[{a:6,f:9,w:3,d:true},"Layer 0"],
[{a:7,f:3},"","","","","","","","","","","","","","","",{x:0.5},""],
[{w:1.5},"","","","","","","","","","","","","",{w:1.5},"",{x:0.5},""],
[{w:1.75},"","","","","","","","","","","","","",{w:1.25},""],
[{w:1.25},"","","","","","","","","","","",{x:-1},"","","",{w:1.25},"",""],
[{w:1.25},"","",{w:1.25},"",{w:1.25},"",{w:2},"",{w:2},"",{w:1.25},"",{w:1.25},"","",{w:1.25},"","","",""]
readme.md
The readme.md
for a keymap should have the following information, in order:
layout.json
This file should be keyboard-layout-editor.com raw data. Each layer should be represented as a separate block within the layout.json
file. Each block should start with a "Decal" saying "Layer
Example for keyboards/clueboard/keymaps/default
:
[{a:6,f:9,w:3,d:true},"Layer Typing"],
[{a:4,f:3},"~\nEsc","!\n1","@\n2","#\n3","$\n4","%\n5","^\n6","&\n7","*\n8","(\n9",")\n0","_\n-","+\n=","~\n`","\nBS",{x:0.5},"\nPage Up"],
[{w:1.5},"\nTab","Q","W","E","R","T","Y","U","I","O","P","{\n[","}\n]",{w:1.5},"|\n\\",{x:0.5},"\nPage Down"],
[{w:1.75},"\nCaps Lock","A","S","D","F","G","H","J","K","L",":\n;","\"\n'","~\n#",{w:1.25},"\nEnter"],
[{w:1.25},"\nShift","|\n\\","Z","X","C","V","B","N","M","<\n,",">\n.",{x:-1},">\n.","?\n/","|\n\\",{w:1.25},"\nShift","\n↑"],
[{w:1.25},"\nCtrl","\nWin",{w:1.25},"\nAlt",{w:1.25},"\nMu henken",{w:2},"\nSpace",{w:2},"\nSpace",{w:1.25},"\nHenken",{w:1.25},"\nAlt","\nCtrl",{w:1.25},"\nFn","\n←","\n↓","\n→"],
[{a:6,f:9,w:3.5,d:true},"Layer Function"],
[{a:4,f:3},"~\n`","\nF1","\nF2","\nF3","\nF4","\nF5","\nF6","\nF7","\nF8","\nF9","\nF10","\nF11","\nF12",{a:7},"",{a:4},"\nDelete",{x:0.5},"LED\nToggle"],
[{a:7,w:1.5},"","","","",{f:2},"",{f:3},"","","",{a:4},"\nPrint Screen","\nScroll Lock","\nPause Break",{a:7},"","",{w:1.5},"",{x:0.5},""],
[{w:1.75},"","","","","","","","","","","","","",{w:1.25},""],
[{w:1.25},"","","","","","","","","","","",{x:-1},"","","",{w:1.25},"",{a:4},"\nPage Up"],
[{a:7,w:1.25},"",{f:4},"",{f:3,w:1.25},"",{w:1.25},"",{w:2},"",{w:2},"",{w:1.25},"",{w:1.25},"","",{a:4,w:1.25},"\nFn","\nHome","\nPage Down","\nEnd"]
For the keyboard readmes, this is the format we can follow:
Planck
===
![Planck](http://i.imgur.com/q2M3uEU.jpg)
A compact 40% (12x4) ortholinear keyboard kit made and sold by OLKB and Massdrop. [More info on qmk.fm](http://qmk.fm/planck/)
Keyboard Maintainer: [Jack Humbert](https://github.com/jackhumbert)
Hardware Supported: Planck PCB rev1, rev2, rev3, rev4, Teensy 2.0
Hardware Availability: [OLKB.com](https://olkb.com)
Make example for this keyboard (after setting up your build environment):
make planck-rev4-default
See [build environment setup](https://docs.qmk.fm/build_environment_setup.html) then the [make instructions](https://docs.qmk.fm/make_instructions.html) for more information.
I think we've implemented these changes a couple different times, so I'm going to close this for now.
As QMK has grown and matured the need for keyboard specific
README.md
files that cover QMK basics such as how to setup the build environment has been reduced. Worse, many of these files have instructions that are out of date or incomplete, making it harder for newcomers to figure QMK out. In reviewing keyboards many of them also have no copyright headers, making ownership and licensing of their source files ambiguous.We'd like to institute a keyboard cleanup project, where we bring all keyboards up to a baseline standard of documentation and organization. This issue was created to talk about and decide on what this project will cover.
Open Questions:
README.md
?README.md
?