__capabilities.md (6568B)
1 # Documentation Capabilities 2 3 This 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 7 Unrelated 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 48 Newlines with `<br>`: 49 50 Line one<br> 51 Line two<br/> 52 Line three 53 54 Nested 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 62 Nested 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 70 Nested numbered: 71 72 1. The PR is complete and ready to merge 73 1. 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 78 Nested mixed: 79 80 1. Add it to the schema in `data/schemas/keyboards.jsonschema` 81 1. Add a mapping in `data/maps` 82 1. (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 105 1–4 106 107 Command+<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 131 This is an info box. 132 ::: 133 134 ::: tip 135 This is a tip. 136 ::: 137 138 ::: warning 139 This is a warning. 140 ::: 141 142 ::: danger 143 This is a dangerous warning. 144 ::: 145 146 ::: details 147 This is a details block. 148 ::: 149 150 ### Keyboard keys 151 152 <kbd>,</kbd> 153 154 <kbd>Right Alt</kbd>+<kbd>Right Shift</kbd> 155 156 1. Click <kbd>File</kbd> > <kbd>New</kbd> > <kbd>Makefile Project with Existing Code</kbd> 157 158 1. Click <kbd><kbd>File</kbd> > <kbd>Preferences ></kbd> > <kbd>Settings</kbd> </kbd> 159 160 1. 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 167 Inline code with tag: <code>test</code> 168 169 Inline code with backticks: `test` 170 171 This is preformatted 172 Indented by 4 spaces 173 The letters lined up 174 175 ```c 176 int c_code(void) { 177 return -1; 178 } 179 ``` 180 181 ```makefile 182 ifeq ($(BUILD),) 183 CHUNDER_REQUIRED = yes 184 endif 185 ``` 186 187 ```python 188 from pathlib import Path 189 190 p = 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 214 Indented 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 230 I<sup>2</sup>C 231 232 T<sub>0H</sub>, T<sub>0L</sub> 233 234 ### Tabs 235 236 Tabs are based on section headers, with `**` enclosing the tab title. 237 238 <!-- tabs:start --> 239 240 #### ** Tab one ** 241 242 Content one 243 244 <!-- tabs:start --> 245 246 ##### ** Nested one ** 247 248 Nested content one 249 250 ##### ** Nested two ** 251 252 Nested content two 253 254 <!-- tabs:end --> 255 256 #### ** Tab two ** 257 258 Content two 259 260 #### ** Tab three ** 261 262 Content three 263 264 <!-- tabs:end --> 265 266 ::::tabs 267 === tab a 268 a content 2 269 === tab b 270 b content 2 271 === tab c 272 :::tabs 273 == nested tab a 274 nested a content 2 275 == nested tab b 276 nested b content 2 277 ::: 278 :::: 279 280 ## Details sections 281 282 Expandable: 283 284 <details> 285 <summary>Some summary text that shows up before expanding</summary> 286 287 !> Embedded notification! 288 289 This 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)