auri.ee
keyboard stuff
1# Documentation Capabilities
2
3This page lays out the capabilities used by the QMK Firmware documentation, in order to aid future transitions to other page generators. Focuses mainly on things other than normal Markdown, as it's assumed that markdown generators should still function accordingly.
4
5## Overall capabilities
6
7Unrelated to styling, high-level tech.
8
9* Title anchors -- `:id=some-anchor-name`, used for direct linking to sections
10 * Links to anchors:
11 * Style 1: [early initialization](platformdev_chibios_earlyinit.md?id=board-init)
12 * Style 2: [early initialization](platformdev_chibios_earlyinit.md#board-init)
13 * Links to anchors on the same page, i.e. [Emoji](#emoji)
14* Specifying CNAME for root domain -- `docs.qmk.fm`
15* Moved pages, see `index.html`
16* Text search
17* Footnotes [like this][1]
18
19<!-- Comments should not show up -->
20
21<!-- Nor should
22 multiline
23
24 comments with
25
26 newlines show up -->
27
28
29### Dividing lines
30
31---
32
33<hr>
34
35<hr/>
36
37### Images
38
39
40
41
42
43
44<img src="./public/color-wheel.svg" alt="HSV Color Wheel" width="250"/>
45
46### Lists
47
48Newlines with `<br>`:
49
50Line one<br>
51Line two<br/>
52Line three
53
54Nested dotted:
55
56* The PR is complete and ready to merge
57* GitHub checks for the PR are green whenever possible
58 * A "red" check may be disregarded by maintainers if the items flagged are unrelated to the change proposed in the PR
59 * Modifications to existing files should not need to add license headers to pass lint, for instance.
60 * If it's not directly related to your PR's functionality, prefer avoiding making a change.
61
62Nested dashed:
63
64- The PR is complete and ready to merge
65- GitHub checks for the PR are green whenever possible
66 - A "red" check may be disregarded by maintainers if the items flagged are unrelated to the change proposed in the PR
67 - Modifications to existing files should not need to add license headers to pass lint, for instance.
68 - If it's not directly related to your PR's functionality, prefer avoiding making a change.
69
70Nested numbered:
71
721. The PR is complete and ready to merge
731. GitHub checks for the PR are green whenever possible
74 1. A "red" check may be disregarded by maintainers if the items flagged are unrelated to the change proposed in the PR
75 1. Modifications to existing files should not need to add license headers to pass lint, for instance.
76 1. If it's not directly related to your PR's functionality, prefer avoiding making a change.
77
78Nested mixed:
79
801. Add it to the schema in `data/schemas/keyboards.jsonschema`
811. Add a mapping in `data/maps`
821. (optional and discouraged) Add code to extract/generate it to:
83 * `lib/python/qmk/info.py`
84 * `lib/python/qmk/cli/generate/config_h.py`
85 * `lib/python/qmk/cli/generate/rules_mk.py`
86
87### Emoji {#emoji}
88
89#### Direct:
90
91👍🎉 First off, thanks for taking the time to read this and contribute! 🎉👍
92
93#### As colon-name-colon:
94
95:heavy_check_mark: : works and was tested
96
97:o: : does not apply
98
99:x: : not supported by MCU
100
101### XML Entities
102
103[`clueboard`](https://github.com/qmk/qmk_firmware/tree/master/keyboards/clueboard) ← This is the organization folder, there's no `rules.mk` file
104
1051–4
106
107Command+<code>`</code>
108
109## Styling
110
111### CSS-ish
112
113<b style="font-size:150%">This is 150% of normal sizing, and bold!</b>
114
115
116### Tables
117
118| Column A | Column B |
119|----------|----------|
120| Left | Right |
121
122### Indented sections
123
124> Indent without any sort of marker
125
126?> Query, this?
127
128!> Notification, damnit!
129
130::: info
131This is an info box.
132:::
133
134::: tip
135This is a tip.
136:::
137
138::: warning
139This is a warning.
140:::
141
142::: danger
143This is a dangerous warning.
144:::
145
146::: details
147This is a details block.
148:::
149
150### Keyboard keys
151
152<kbd>,</kbd>
153
154<kbd>Right Alt</kbd>+<kbd>Right Shift</kbd>
155
1561. Click <kbd>File</kbd> > <kbd>New</kbd> > <kbd>Makefile Project with Existing Code</kbd>
157
1581. Click <kbd><kbd>File</kbd> > <kbd>Preferences ></kbd> > <kbd>Settings</kbd> </kbd>
159
1601. Hit Ctrl-<code>`</code> (Grave) to bring up the terminal or go to <kbd><kbd>View</kbd> > <kbd>Terminal</kbd></kbd> (command `workbench.action.terminal.toggleTerminal`). A new terminal will be opened if there isn‘t one already.
161
162 This should start the terminal in the workspace's folder (so the `qmk_firmware` folder), and then you can compile your keyboard.
163
164
165### Code Blocks
166
167Inline code with tag: <code>test</code>
168
169Inline code with backticks: `test`
170
171 This is preformatted
172 Indented by 4 spaces
173 The letters lined up
174
175```c
176int c_code(void) {
177 return -1;
178}
179```
180
181```makefile
182ifeq ($(BUILD),)
183 CHUNDER_REQUIRED = yes
184endif
185```
186
187```python
188from pathlib import Path
189
190p = Path('/path/to/qmk_firmware')
191```
192
193```json
194{
195 "a": "b",
196 "c": 4,
197 "d": {
198 "e": [
199 0, 1, 2, 3
200 ]
201 }
202}
203```
204
205```diff
206 #undef RGBLIGHT_LED_COUNT
207+#undef RGBLIGHT_EFFECT_STATIC_GRADIENT
208+#undef RGBLIGHT_EFFECT_RAINBOW_SWIRL
209 #define RGBLIGHT_LED_COUNT 12
210 #define RGBLIGHT_HUE_STEP 8
211 #define RGBLIGHT_SAT_STEP 8
212```
213
214Indented code as part of a list:
215
216* [QMK Toolbox](https://github.com/qmk/qmk_toolbox/releases) (recommended GUI)
217* [Teensy Loader](https://www.pjrc.com/teensy/loader.html)
218* [Teensy Loader Command Line](https://www.pjrc.com/teensy/loader_cli.html) / `:teensy` target in QMK (recommended command line)
219 ```
220 teensy_loader_cli -v -mmcu=<mcu> <filename>
221 ```
222
223
224### Sub/Superscript
225
226<sub>This is subscripted, apparently.</sub>
227
228<sup>This is superscripted, apparently.</sup>
229
230I<sup>2</sup>C
231
232T<sub>0H</sub>, T<sub>0L</sub>
233
234### Tabs
235
236Tabs are based on section headers, with `**` enclosing the tab title.
237
238<!-- tabs:start -->
239
240#### ** Tab one **
241
242Content one
243
244<!-- tabs:start -->
245
246##### ** Nested one **
247
248Nested content one
249
250##### ** Nested two **
251
252Nested content two
253
254<!-- tabs:end -->
255
256#### ** Tab two **
257
258Content two
259
260#### ** Tab three **
261
262Content three
263
264<!-- tabs:end -->
265
266::::tabs
267=== tab a
268a content 2
269=== tab b
270b content 2
271=== tab c
272:::tabs
273== nested tab a
274nested a content 2
275== nested tab b
276nested b content 2
277:::
278::::
279
280## Details sections
281
282Expandable:
283
284<details>
285 <summary>Some summary text that shows up before expanding</summary>
286
287!> Embedded notification!
288
289This is some inner content.
290</details>
291
292## Embed
293
294[example embed](__capabilities_inc.md ':include')
295
296<!--@include: ./__capabilities_inc.md-->
297
298 [1]: https://en.wikipedia.org/wiki/Eclipse_(software)