<spanclass="line"><span>| + ...</span></span></code></pre></div><p>The <code>layouts/default/</code> and <code>layouts/community/</code> are two examples of layout "repositories" - currently <code>default</code> will contain all of the information concerning the layout, and one default keymap named <code>default_<layout></code>, for users to use as a reference. <code>community</code> contains all of the community keymaps, with the eventual goal of being split-off into a separate repo for users to clone into <code>layouts/</code>. QMK searches through all folders in <code>layouts/</code>, so it's possible to have multiple repositories here.</p><p>Each layout folder is named (<code>[a-z0-9_]</code>) after the physical aspects of the layout, in the most generic way possible, and contains a <code>readme.md</code> with the layout to be defined by the keyboard:</p><divclass="language-markdown vp-adaptive-theme"><buttontitle="Copy Code"class="copy"></button><spanclass="lang">markdown</span><preclass="shiki shiki-themes github-light github-dark vp-code"><code><spanclass="line"><spanstyle="--shiki-light:#005CC5;--shiki-dark:#79B8FF;--shiki-light-font-weight:bold;--shiki-dark-font-weight:bold;"># 60_ansi</span></span>
<spanclass="line"><spanstyle="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> LAYOUT_60_ansi</span></span></code></pre></div><p>New names should try to stick to the standards set by existing layouts, and can be discussed in the PR/Issue.</p><h2id="supporting-a-layout"tabindex="-1">Supporting a Layout <aclass="header-anchor"href="#supporting-a-layout"aria-label="Permalink to "Supporting a Layout""></a></h2><p>For a keyboard to support a layout, the variable must be defined in it's <code><keyboard>.h</code>, and match the number of arguments/keys (and preferably the physical layout):</p><divclass="language-c vp-adaptive-theme"><buttontitle="Copy Code"class="copy"></button><spanclass="lang">c</span><preclass="shiki shiki-themes github-light github-dark vp-code"><code><spanclass="line"><spanstyle="--shiki-light:#D73A49;--shiki-dark:#F97583;">#define</span><spanstyle="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> LAYOUT_60_ansi</span><spanstyle="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> KEYMAP_ANSI</span></span></code></pre></div><p>The name of the layout must match this regex: <code>[a-z0-9_]+</code></p><p>The folder name must be added to the keyboard's <code>rules.mk</code>:</p><divclass="language- vp-adaptive-theme"><buttontitle="Copy Code"class="copy"></button><spanclass="lang"></span><preclass="shiki shiki-themes github-light github-dark vp-code"><code><spanclass="line"><span>LAYOUTS = 60_ansi</span></span></code></pre></div><p><code>LAYOUTS</code> can be set in any keyboard folder level's <code>rules.mk</code>:</p><divclass="language- vp-adaptive-theme"><buttontitle="Copy Code"class="copy"></button><spanclass="lang"></span><preclass="shiki shiki-themes github-light github-dark vp-code"><code><spanclass="line"><span>LAYOUTS = 60_iso</span></span></code></pre></div><p>but the <code>LAYOUT_<layout></code> variable must be defined in <code><folder>.h</code> as well.</p><h2id="building-a-keymap"tabindex="-1">Building a Keymap <aclass="header-anchor"href="#building-a-keymap"aria-label="Permalink to "Building a Keymap""></a></h2><p>You should be able to build the keyboard keymap with a command in this format:</p><divclass="language- vp-adaptive-theme"><buttontitle="Copy Code"class="copy"></button><spanclass="lang"></span><preclass="shiki shiki-themes github-light github-dark vp-code"><code><spanclass="line"><span>make <keyboard>:<layout></span></span></code></pre></div><h3id="conflicting-layouts"tabindex="-1">Conflicting layouts <aclass="header-anchor"href="#conflicting-layouts"aria-label="Permalink to "Conflicting layouts""></a></h3><p>When a keyboard supports multiple layout options,</p><divclass="language- vp-adaptive-theme"><buttontitle="Copy Code"class="copy"></button><spanclass="lang"></span><preclass="shiki shiki-themes github-light github-dark vp-code"><code><spanclass="line"><span>LAYOUTS = ortho_4x4 ortho_4x12</span></span></code></pre></div><p>And a layout exists for both options,</p><divclass="language- vp-adaptive-theme"><buttontitle="Copy Code"class="copy"></button><spanclass="lang"></span><preclass="shiki shiki-themes github-light github-dark vp-code"><code><spanclass="line"><span>layouts/</span></span>
<spanclass="line"><span>| + ...</span></span></code></pre></div><p>The FORCE_LAYOUT argument can be used to specify which layout to build</p><divclass="language- vp-adaptive-theme"><buttontitle="Copy Code"class="copy"></button><spanclass="lang"></span><preclass="shiki shiki-themes github-light github-dark vp-code"><code><spanclass="line"><span>make <keyboard>:<layout> FORCE_LAYOUT=ortho_4x4</span></span>
<spanclass="line"><span>make <keyboard>:<layout> FORCE_LAYOUT=ortho_4x12</span></span></code></pre></div><h2id="tips-for-making-layouts-keyboard-agnostic"tabindex="-1">Tips for Making Layouts Keyboard-Agnostic <aclass="header-anchor"href="#tips-for-making-layouts-keyboard-agnostic"aria-label="Permalink to "Tips for Making Layouts Keyboard-Agnostic""></a></h2><h3id="includes"tabindex="-1">Includes <aclass="header-anchor"href="#includes"aria-label="Permalink to "Includes""></a></h3><p>Instead of using <code>#include "planck.h"</code>, you can use this line to include whatever <code><keyboard>.h</code> (<code><folder>.h</code> should not be included here) file that is being compiled:</p><divclass="language-c vp-adaptive-theme"><buttontitle="Copy Code"class="copy"></button><spanclass="lang">c</span><preclass="shiki shiki-themes github-light github-dark vp-code"><code><spanclass="line"><spanstyle="--shiki-light:#D73A49;--shiki-dark:#F97583;">#include</span><spanstyle="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> QMK_KEYBOARD_H</span></span></code></pre></div><p>If you want to keep some keyboard-specific code, you can use these variables to escape it with an <code>#ifdef</code> statement:</p><ul><li><code>KEYBOARD_<folder1>_<folder2></code></li></ul><p>For example:</p><divclass="language-c vp-adaptive-theme"><buttontitle="Copy Code"class="copy"></button><spanclass="lang">c</span><preclass="shiki shiki-themes github-light github-dark vp-code"><code><spanclass="line"><spanstyle="--shiki-light:#D73A49;--shiki-dark:#F97583;">#ifdef</span><spanstyle="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> KEYBOARD_planck</span></span>
<spanclass="line"><spanstyle="--shiki-light:#D73A49;--shiki-dark:#F97583;">#endif</span></span></code></pre></div><p>Note that the names are lowercase and match the folder/file names for the keyboard/revision exactly.</p><h3id="keymaps"tabindex="-1">Keymaps <aclass="header-anchor"href="#keymaps"aria-label="Permalink to "Keymaps""></a></h3><p>In order to support both split and non-split keyboards with the same layout, you need to use the keyboard agnostic <code>LAYOUT_<layout name></code> macro in your keymap. For instance, in order for a Let's Split and Planck to share the same layout file, you need to use <code>LAYOUT_ortho_4x12</code> instead of <code>LAYOUT_planck_grid</code> or just <code>{}</code> for a C array.</p></div></div></main><footerclass="VPDocFooter"data-v-39a288b8data-v-09de1c0f><!--[--><!--]--><!----><navclass="prev-next"data-v-09de1c0f><divclass="pager"data-v-09de1c0f><aclass="VPLink link pager-link prev"href="/documentation_templates"data-v-09de1c0f><!--[--><spanclass="desc"data-v-09de1c0f>Previous page</span><spanclass="title"data-v-09de1c0f>Documentation Templates</span><!--]--></a></div><divclass="pager"data-v-09de1c0f><aclass="VPLink link pager-link next"href="/unit_testing"data-v-09de1c0f><!--[--><spanclass="desc"data-v-09de1c0f>Next page</span><spanclass="title"data-v-09de1c0f>Unit Testing</span><!--]--></a></div></nav></footer><!--[--><!--]--></div></div></div><!--[--><!--]--></div></div><!----><!--[--><!--]--></div></div>
