aboutsummaryrefslogtreecommitdiff
path: root/docs/newbs_external_userspace.md
diff options
context:
space:
mode:
authorNick Brassel <[email protected]>2024-05-30 12:00:41 +1000
committerGitHub <[email protected]>2024-05-30 12:00:41 +1000
commit6ef97172889ccd5db376b2a9f8825489e24fdac4 (patch)
tree334e3bf41c8554d4bee73a140822f95f60eb64e9 /docs/newbs_external_userspace.md
parent395766657ff98a4b1fd0dcba5917557f8acbb9e4 (diff)
downloadqmk_firmware-6ef97172889ccd5db376b2a9f8825489e24fdac4.tar.gz
qmk_firmware-6ef97172889ccd5db376b2a9f8825489e24fdac4.zip
Vitepress conversion of docs. (#23795)
Diffstat (limited to 'docs/newbs_external_userspace.md')
-rw-r--r--docs/newbs_external_userspace.md24
1 files changed, 17 insertions, 7 deletions
diff --git a/docs/newbs_external_userspace.md b/docs/newbs_external_userspace.md
index 9bdf4b0b18..fdc998c37a 100644
--- a/docs/newbs_external_userspace.md
+++ b/docs/newbs_external_userspace.md
@@ -4,21 +4,29 @@ QMK Firmware now officially supports storing user keymaps outside of the normal
External Userspace mirrors the structure of the main QMK Firmware repository, but only contains the keymaps that you wish to build. You can still use `keyboards/<my keyboard>/keymaps/<my keymap>` to store your keymaps, or you can use the `layouts/<my layout>/<my keymap>` system as before -- they're just stored external to QMK Firmware.
-The build system will still honor the use of `users/<my keymap>` if you rely on the traditional QMK Firmware [userspace feature](feature_userspace.md) -- it's now supported externally too, using the same location inside the External Userspace directory.
+The build system will still honor the use of `users/<my keymap>` if you rely on the traditional QMK Firmware [userspace feature](feature_userspace) -- it's now supported externally too, using the same location inside the External Userspace directory.
Additionally, there is first-class support for using GitHub Actions to build your keymaps, allowing you to automatically compile your keymaps whenever you push changes to your External Userspace repository.
-!> External Userspace is new functionality and may have issues. Tighter integration with the `qmk` command will occur over time.
+::: warning
+External Userspace is new functionality and may have issues. Tighter integration with the `qmk` command will occur over time.
+:::
-?> Historical keymap.json and GitHub-based firmware build instructions can be found [here](newbs_building_firmware_workflow.md). This document supersedes those instructions, but they should still function correctly.
+::: tip
+Historical keymap.json and GitHub-based firmware build instructions can be found [here](newbs_building_firmware_workflow). This document supersedes those instructions, but they should still function correctly.
+:::
## Setting up QMK Locally
-If you wish to build on your local machine, you will need to set up QMK locally. This is a one-time process, and is documented in the [newbs setup guide](https://docs.qmk.fm/#/newbs).
+If you wish to build on your local machine, you will need to set up QMK locally. This is a one-time process, and is documented in the [newbs setup guide](newbs).
-!> If you wish to use any QMK CLI commands related to manipulating External Userspace definitions, you will currently need a copy of QMK Firmware as well.
+::: warning
+If you wish to use any QMK CLI commands related to manipulating External Userspace definitions, you will currently need a copy of QMK Firmware as well.
+:::
-!> Building locally has a much shorter turnaround time than waiting for GitHub Actions to complete.
+::: warning
+Building locally has a much shorter turnaround time than waiting for GitHub Actions to complete.
+:::
## External Userspace Repository Setup (forked on GitHub)
@@ -60,7 +68,9 @@ After creating your new keymap, building the keymap matches normal QMK usage:
qmk compile -kb <keyboard> -km <keymap>
```
-!> The `qmk config user.overlay_dir=...` command must have been run when cloning the External Userspace repository for this to work correctly.
+::: warning
+The `qmk config user.overlay_dir=...` command must have been run when cloning the External Userspace repository for this to work correctly.
+:::
## Adding the keymap to External Userspace build targets