<spanclass="line"><span>echo "#include QMK_KEYBOARD_H"> ~/qmk_keymap/source.c</span></span></code></pre></div><divclass="tip custom-block"><pclass="custom-block-title">TIP</p><p>For Windows user running MSYS, those commands will create the folder <code>qmk_keymap/</code> and its content in the <code>C:\Users\<windows_username>\qmk_keymap\</code> path location.</p></div><h3id="add-a-json-keymap"tabindex="-1">Add a JSON keymap <aclass="header-anchor"href="#add-a-json-keymap"aria-label="Permalink to "Add a JSON keymap""></a></h3><p>Visit the <ahref="https://config.qmk.fm/#/"target="_blank"rel="noreferrer">QMK Configurator</a> to create a keymap file:</p><ol><li>Select your keyboard from the drop-down list (and choose a layout if required).</li><li>Use your GitHub username for the <strong>Keymap Name</strong> field.</li><li>Customise the key layout according to your preference.</li><li>Select download next to <strong>KEYMAP.JSON</strong> and save the JSON file into the <code>~/qmk_keymap/</code> folder.</li></ol><divclass="warning custom-block"><pclass="custom-block-title">WARNING</p><p><strong>Important:</strong> Make sure that the GitHub username you use in step 2 is correct. If it is not, the build process will fail to locate your files in the right folder.</p></div><h3id="add-a-github-action-workflow"tabindex="-1">Add a GitHub Action workflow <aclass="header-anchor"href="#add-a-github-action-workflow"aria-label="Permalink to "Add a GitHub Action workflow""></a></h3><p>Open the file <code>~/qmk_keymap/.github/workflows/build.yml</code> with your favorite <ahref="./newbs_learn_more_resources#text-editor-resources">text editor</a>, paste the following workflow content, and save it:</p><divclass="language-yml vp-adaptive-theme"><buttontitle="Copy Code"class="copy"></button><spanclass="lang">yml</span><preclass="shiki shiki-themes github-light github-dark vp-code"><code><spanclass="line"><spanstyle="--shiki-light:#22863A;--shiki-dark:#85E89D;">name</span><spanstyle="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><spanstyle="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">Build QMK firmware</span></span>
<spanclass="line"><spanstyle="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> *.uf2</span></span></code></pre></div><p>Replace <code>username.json</code> with the JSON file name that was downloaded from <ahref="https://config.qmk.fm/#/"target="_blank"rel="noreferrer">QMK Configurator</a> in the previous step.</p><divclass="warning custom-block"><pclass="custom-block-title">WARNING</p><p>Do note that the <code>build.yml</code> file requires <em><strong>proper indentation</strong></em> for every line. Incorrect spacing will trigger workflow syntax errors.</p></div><h3id="commit-files-to-github"tabindex="-1">Commit files to GitHub <aclass="header-anchor"href="#commit-files-to-github"aria-label="Permalink to "Commit files to GitHub""></a></h3><p>If you have completed all steps correctly, the folder <code>qmk_keymap/</code> will contain the following files:</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>├── .github</span></span>
<spanclass="line"><span>└── username.json</span></span></code></pre></div><p>To commit and push them into GitHub, run the following commands (replacing <code>gh-username</code> with your GitHub user name):</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>cd ~/qmk_keymap</span></span>
<spanclass="line"><span>git push -u origin main</span></span></code></pre></div><divclass="tip custom-block"><pclass="custom-block-title">TIP</p><p>Use your GitHub personal access token at the password prompt. If you have setup SSH access, replace <code>https://github.com/gh-username/qmk_keymap.git</code> with <code>git@github.com:gh-username/qmk_keymap.git</code> in the remote origin command above.</p></div><h3id="review-workflow-output"tabindex="-1">Review workflow output <aclass="header-anchor"href="#review-workflow-output"aria-label="Permalink to "Review workflow output""></a></h3><p>Files committed to GitHub in the previous step will automatically trigger the workflow to build the JSON file listed in <code>build.yml</code>. To review its output:</p><ol><li>Visit your "<strong>qmk_keymap</strong>" repository page on <ahref="https://github.com/"target="_blank"rel="noreferrer">GitHub</a>.</li><li>Select <strong>Actions</strong> tab to display the "<strong>Build QMK Firmware</strong>" workflow.</li><li>Select that workflow to display its run from the last commit.</li><li>Successfully compiled firmware will be under the "<strong>Artifacts</strong>" section.</li><li>If there are build errors, review the job log for details.</li></ol><p>Download and flash the firmware file into your keyboard using <ahref="./newbs_flashing#flashing-your-keyboard-with-qmk-toolbox">QMK Toolbox</a>.</p><h2id="customising-your-keymap"tabindex="-1">Customising your keymap <aclass="header-anchor"href="#customising-your-keymap"aria-label="Permalink to "Customising your keymap""></a></h2><p>This setup and workflow relies on the QMK <ahref="./feature_userspace">Userspace</a> feature. The build process will copy the QMK source codes and clone your repository into its <code>users/</code> folder in a container. You must adhere to the following guidelines when customising your keymaps:</p><ul><li>Keymap layout files must be retained in JSON format and cannot be converted to <code>keymap.c</code>.</li><li>User callback and functions (e.g. <code>process_record_user()</code>) can be placed in the <code>source.c</code> file.</li><li>Multiple keymap JSON files can be built in the same workflow. List them under <code>matrix.file:</code>, e.g.:</li></ul><divclass="language-yml vp-adaptive-theme"><buttontitle="Copy Code"class="copy"></button><spanclass="lang">yml</span><preclass="shiki shiki-themes github-light github-dark vp-code"><code><spanclass="line"><spanstyle="--shiki-light:#22863A;--shiki-dark:#85E89D;"> file</span><spanstyle="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">:</span></span>
<spanclass="line"><spanstyle="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> - </span><spanstyle="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">crkbd.json</span></span></code></pre></div><ul><li>Code changes will require Git commit into GitHub to trigger the build workflow.</li></ul><divclass="tip custom-block"><pclass="custom-block-title">TIP</p><p>See <ahref="https://docs.github.com/en/actions/learn-github-actions"target="_blank"rel="noreferrer">GitHub Actions guide</a> to learn more about development workflow.</p></div></div></div></main><footerclass="VPDocFooter"data-v-39a288b8data-v-09de1c0f><!--[--><!--]--><!----><navclass="prev-next"data-v-09de1c0f><divclass="pager"data-v-09de1c0f><!----></div><divclass="pager"data-v-09de1c0f><aclass="VPLink link pager-link next"href="/newbs"data-v-09de1c0f><!--[--><spanclass="desc"data-v-09de1c0f>Next page</span><spanclass="title"data-v-09de1c0f>Introduction</span><!--]--></a></div></nav></footer><!--[--><!--]--></div></div></div><!--[--><!--]--></div></div><!----><!--[--><!--]--></div></div>
