Simplify, update, detail keyboard customization

.wordlist.txt

@@ -94,3 +94,6 @@ udev
 
 Singel
 LEBASTARD
+
+Alli # keeps getting detected as a word in youtube video id in embed
+upstreaming

_includes/use_keyboard.md

@@ -0,0 +1,55 @@
+# Table of contents
+
+1. TOC
+{:toc}
+
+# Introduction
+
+Congratulations on successfully building your keyboard!
+
+The Bastard Keyboards come with a range of features, and it's also easy to customize them. On this page you will find additional information on how to use them and make them your own.
+
+# Daily use
+
+## Default keymap
+
+You can find pictures of the default keymaps on the [default keymaps page][keymaps].
+
+Alternatively, you can also plug in your keyboard and visualize the keymap using VIA (see VIA section).
+
+## Miryoku
+
+The 3x5 keyboards (Skeletyl, Charybdis Nano) come flashed with [Miryoku](https://github.com/manna-harbour/miryoku). On its github repository you will find useful information on the different layers available.
+
+# Customization
+
+For customizing your keyboard, you can:
+
+- use VIA
+- use QMK
+
+## Using VIA
+
+All Bastard Keyboards come flashed with VIA. VIA is an additional layer that comes on top of QMK, and comes with a handy graphical interface. While it's limited in features, it removes the need to manage a git repository, the console and a QMK installation.
+
+You can open the [VIA Web Interface through use.via.app](https://usevia.app/). At the moment, only WebHID-enabled browsers work (eg. Chrome and Chromium-based).
+
+You can check the following tutorial on how to use it:
+{% include youtube.html id="cYICAlliJfU" %}
+
+Through VIA, you can customize:
+- the keymap
+- macros, layers
+- RGB
+
+## Using QMK
+
+This is for advanced users. 
+
+For how to compile a custom hardware for your keyboard, take a look at the [how to compile your own firmware page][compile-firmware].
+
+---
+
+[compile-firmware]: {{site.baseurl}}/fw/compile-firmware.html
+[keymaps]: {{site.baseurl}}/fw/default-keymaps.html
+[flashing]: {{site.baseurl}}/fw/flashing.html

_includes/customize_keyboard.md → _includes/use_keyboard_chary.md

@@ -34,7 +34,7 @@ The most important ones are on the thumb cluster - it transforms into mouse butt
 
 ### Sniping 
 
-Sniping **slows down the trackball**. This way, you can move the cursor more precisely.
+Sniping **slows down the trackball/trackpad**. This way, you can move the cursor more precisely.
 
 By default, Sniping mode is activated when you hold the `MOUSE + SNIP` keys at the same time.
 You can also configure qmk to have it activated automatically.
@@ -43,11 +43,19 @@ You can also configure qmk to have it activated automatically.
 
 The 3x5 keyboards (Skeletyl, Charybdis Nano) come flashed with [Miryoku](https://github.com/manna-harbour/miryoku). On its github repository you will find useful information on the different layers available.
 
+
 # Customization
 
+For customizing your keyboard, you can:
+
+- use VIA
+- use QMK
+
 ## Using VIA
 
-All Bastard Keyboards come flashed with VIA. You can open the [VIA Web Interface through use.via.app](https://usevia.app/). At the moment, only WebHID-enabled browsers work (eg. Chrome and Chromium-based).
+All Bastard Keyboards come flashed with VIA. VIA is an additional layer that comes on top of QMK, and comes with a handy graphical interface. While it's limited in features, it removes the need to manage a git repository, the console and a QMK installation.
+
+You can open the [VIA Web Interface through use.via.app](https://usevia.app/). At the moment, only WebHID-enabled browsers work (eg. Chrome and Chromium-based).
 
 You can check the following tutorial on how to use it:
 {% include youtube.html id="cYICAlliJfU" %}
@@ -59,14 +67,15 @@ Through VIA, you can customize:
 
 ## Using QMK
 
-You can find the latest **default images** for all Bastard Keyboards in the release section of the [BastardKB QMK fork](https://github.com/Bastardkb/bastardkb-qmk/releases).
+This is for advanced users. 
 
-For how to flash your keyboard, take a look at the [how to flash your keyboard page][flashing].
+For how to compile a custom hardware for your keyboard, take a look at the [how to compile your own firmware page][compile-firmware].
 
-For **advanced customization of the Charybdis and Charybdis Nano**, take a look at the [customize page][customize].
+For **advanced customization of the Charybdis and Charybdis Nano**, take a look at the [customize page][customize-chary].
 
 ---
 
-[customize]: {{site.baseurl}}/fw/charybdis-features.html
+[customize-chary]: {{site.baseurl}}/fw/charybdis-features.html
 [keymaps]: {{site.baseurl}}/fw/default-keymaps.html
-[flashing]: {{site.baseurl}}/fw/flashing.html
+[flashing]: {{site.baseurl}}/fw/flashing.html
+[compile-firmware]: {{site.baseurl}}/fw/compile-firmware.html

bg_charybdis/13customize.md

@@ -1,9 +1,9 @@
 ---
 layout: default
-title: Customizing your keyboard
+title: Using your keyboard
 nav_order: 13
 parent: Build guide - Charybdis
 ---
 
 
-{% include customize_keyboard.md %}
+{% include use_keyboard_chary.md %}

bg_cnano/13customize.md

@@ -1,9 +1,9 @@
 ---
 layout: default
-title: Customizing your keyboard
+title: Using your keyboard
 nav_order: 13
 parent: Build guide - Charybdis Nano
 ---
 
 
-{% include customize_keyboard.md %}
+{% include use_keyboard_chary.md %}

bg_dilemma/customize.md

@@ -0,0 +1,9 @@
+---
+layout: default
+title: Using your Dilemma
+nav_order: 99
+parent: Build guide - Dilemma
+---
+
+
+{% include use_keyboard_chary.md %}

bg_dilemma/intro.md

@@ -11,5 +11,7 @@ We recommend you start by reading the *required tools* section.
 
 There are written guides, and there are also video guides in the *video guides* section.
 
+For building the Dilemma MAX, just follow the Dilemma instructions - it's the same keyboard, just bigger.
+
 1. TOC
 {:toc}

bg_dilemma/v1.md

@@ -108,6 +108,5 @@ Solder in your switches of preference.
 
 You're all done!
 
-Head over to [bstkbd.com/custom](https://bstkbd.com/custom) to customize your keyboard to your needs.
+Head over to [Customize your Dilemma firmware][use-dilemma] to customize your keyboard to your needs.
 
-If you need any help with it, make sure to hop on the discord : [bstkbd.com/discord](https://www.bstkbd.com/discord)

bg_dilemma/v2.md

@@ -120,6 +120,8 @@ Solder in your switches of preference.
 
 You're all done!
 
-Head over to [bstkbd.com/custom](https://bstkbd.com/custom) to customize your keyboard to your needs.
+Head over to [Customize your Dilemma firmware][use-dilemma] to customize your keyboard to your needs.
 
-If you need any help with it, make sure to hop on the discord : [bstkbd.com/discord](https://www.bstkbd.com/discord)
+---
+
+[use-dilemma]: {{site.baseurl}}/bg_dilemma/customize.html

bg_scylla/13customize.md

@@ -1,9 +1,9 @@
 ---
 layout: default
-title: Customizing your keyboard
+title: Using your keyboard
 nav_order: 13
 parent: Build guide - Scylla
 ---
 
 
-{% include customize_keyboard.md %}
+{% include use_keyboard.md %}

bg_skeletyl/13customize.md

@@ -1,9 +1,9 @@
 ---
 layout: default
-title: Customizing your keyboard
+title: Using your keyboard
 nav_order: 13
 parent: Build guide - Skeletyl
 ---
 
 
-{% include customize_keyboard.md %}
+{% include use_keyboard.md %}

fw/compile-firmware.md

@@ -0,0 +1,146 @@
+---
+layout: default
+title: Compiling your firmware
+nav_order: 99
+parent: Firmware
+---
+
+# Table of contents
+
+1. TOC
+{:toc}
+
+# Introduction
+
+The [BastardKB QMK repository](https://github.com/bastardkb/bastardkb-qmk) contains the firmware code and releases for the Bastard Keyboards Charybdis boards.
+
+While that repository is used as primary source of truth for Bastard Keyboards firmwares as it contains the latest changes and improvements, the maintainers aim at upstreaming all those changes to the official [QMK repository](https://github.com/qmk/qmk_firmware).
+
+While the behavioural code is stored on the QMK repository, the keymaps are stored in our [QMK userspace](https://github.com/Bastardkb/qmk_userspace).
+
+This page details how to compile your own firmware. Building from source is useful to people who want to customize their keyboard and keymaps beyond what Via offers. This involves using a command-line interface, writing C code, and compiling this code into the final firmware file.
+
+If that seems too complicated, you can also use one of the default releases, or VIA.
+
+# Pre-requisites
+
+## Working QMK environment
+
+Make sure you have a functional QMK environment. See [QMK Docs](https://docs.qmk.fm/#/newbs) for details. At this point, **you don't need** to run `qmk setup`.
+
+## BastardKb QMK fork
+
+Clone the BKB QMK repository, using either github desktop or the command line, and switch to the `bkb-master` branch:
+
+```shell
+git clone https://github.com/bastardkb/bastardkb-qmk
+cd bastardkb-qmk
+git checkout origin/bkb-master
+```
+
+Now that you've cloned the repository, `cd` into it and set it as the default local QMK repository. You also need to do this if you had a previous, separate QMK installation.
+
+```shell
+qmk config user.qmk_home="$(realpath .)" 
+```
+
+{: .info }
+If you have multiple QMK installations, you will need to manually set the qmk home path again to use the other ones.
+
+## BastardKb userspace
+
+While the QMK repository contains the logic behind the keyboards, the keymaps are in the userspace repository.
+
+In a separate folder, clone the BKB QMK repository, using either github desktop or the command line:
+
+
+```shell
+git clone https://github.com/bastardkb/qmk_userspace
+```
+
+Next, `cd` into the repository and enable userspace:
+
+```shell
+cd qmk_userspace
+qmk config user.overlay_dir="$(realpath .)"
+```
+
+## Github actions
+
+// TODO screenshot enable actions workflows
+
+// TODO mroe details, screenshots
+actions tab -- "I understand my workflows, go ahead and enable them"
+
+1. In the GitHub Actions tab, enable workflows
+2. Push your changes above to your forked GitHub repository
+3. Look at the GitHub Actions for a new actions run
+4. Wait for the actions run to complete
+5. Inspect the Releases tab on your repository for the latest firmware build
+
+# Compiling with console
+
+Once in the QMK Userspace repository, compiling a keymap works the same as normal:
+
+```shell
+qmk compile -c -kb bastardkb/{keyboard} -km {keymap}
+```
+
+## `{keyboard}` argument
+
+`{keyboard}` corresponds to the physical keyboard you are building the firmware for. It can be one of the following:
+
+- `charybdis/4x6`: the 4x6+5 [Charybdis](https://github.com/bastardkb/charybdis/)
+- `charybdis/3x5`: the 3x5+3 [Charybdis Nano](https://github.com/bastardkb/charybdis/)
+- `charybdis/3x6`: the 3x6+3 [Charybdis Mini](https://github.com/bastardkb/charybdis/)
+- `scylla`: the 4x6+5 [Scylla](https://github.com/Bastardkb/Scylla)
+- `skeletyl`: the 3x5+3 [Skeletyl](https://github.com/Bastardkb/Skeletyl/)
+- `tbkmini`: the 3x6+3 [TBK Mini](https://github.com/Bastardkb/TBK-Mini/)
+- `dilemma/3x5_3`: the 3x5+3 [Dilemma](https://github.com/bastardkb/dilemma/)
+- `dilemma/4x6_4`: the 4x6+4 [Dilemma Max](https://github.com/bastardkb/dilemma/)
+
+## `{keymap}` argument
+
+All keyboards have a `default` keymap. Most also have a `via` keymap. The latter is already configured to work with [Via](https://usevia.app).
+
+To build *any* keymap with Via support, simply add the following argument to the command line: `-e VIA_ENABLE=yes`, e.g.:
+
+```shell
+qmk compile -c -kb {keyboard} -km default -e VIA_ENABLE=yes
+```
+
+# Compiling with Github Actions
+
+If you clone the BastardKB Userspace repository, it is alredy configured to work with the BastardKB QMK fork.
+
+If you created your own keymap, you will need to add it to the list of keympaps to be compiled in `qmk.json`, for example:
+
+```shell
+{
+    "userspace_version": "1.0",
+    "build_targets": [
+        ["bastardkb/charybdis/4x6", "my-keymap"]
+    ]
+}
+```
+
+We also recommend deleting the other keymaps if you don't use them, as it'll make the action run faster.
+
+# Creating your own keymap
+
+// TODO
+
+# Contributing your own keymap
+
+// TODO
+
+# Flashing your keyboard
+
+Once you compiled your `uf2` image, you can flash your keyboard.
+
+For how to flash your keyboard, take a look at the [how to flash your keyboard page][flashing].
+
+
+---
+
+[flashing]: {{site.baseurl}}/fw/flashing.html

fw/flashing.md

@@ -34,6 +34,8 @@ To flash your new image, you will need to go through a few steps:
 
 Below is detailed the exact procedure to follow. You need to flash either the right side only, or the right and left side separately - this is also detailed below.
 
+# Sourcing your firmware
+
 Sourcing your firmware can be done in a couple ways:
 
 - downloading it from the [release section on github][releases]
@@ -130,7 +132,7 @@ Unplug the USB connector and connect the other side, and then repeat the procedu
 If you use the `QK_BOOT` method, please note that your layout may now be mirrored! This is normal, ignore it and plug the USB back into the right side.
 
 ---- 
-[build]: https://github.com/Bastardkb/bastardkb-qmk?tab=readme-ov-file#building-from-source-advanced
+[build]: {{site.baseurl}}/fw/compile-firmware.html
 [releases]: https://github.com/Bastardkb/bastardkb-qmk/releases
 [keymaps]: {{site.baseurl}}/fw/default-keymaps.html
 [splitkb-whentoflash]: https://docs.splitkb.com/hc/en-us/articles/360011949679-When-do-I-need-to-flash-my-microcontroller