logo

qmk_firmware

custom branch of QMK firmware git clone https://anongit.hacktivis.me/git/qmk_firmware.git

__capabilities.md (6568B)

    

  1. # Documentation Capabilities
  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.
  5. ## Overall capabilities
  7. Unrelated to styling, high-level tech.
  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]
  19. <!-- Comments should not show up -->
  21. <!-- Nor should
  22.      multiline
  23.      
  24.      comments with
  25.      
  26.      newlines show up -->
  27.      
  28.      
  29. ### Dividing lines
  31. ---
  33. <hr>
  35. <hr/>
  37. ### Images
  39. ![QMK Color Wheel with HSV Values](https://i.imgur.com/vkYVo66.jpg)
  41. ![QMK Light](./public/badge-community-light.svg)
  42. ![QMK Dark](./public/badge-community-dark.svg)
  44. <img src="./public/color-wheel.svg" alt="HSV Color Wheel" width="250"/>
  46. ### Lists
  48. Newlines with `<br>`:
  50. Line one<br>
  51. Line two<br/>
  52. Line three
  54. Nested dotted:
  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.
  62. Nested dashed:
  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.
  70. Nested numbered:
  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:
  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`
  87. ### Emoji {#emoji}
  89. #### Direct:
  91. 👍🎉 First off, thanks for taking the time to read this and contribute! 🎉👍
  93. #### As colon-name-colon:
  95. :heavy_check_mark: : works and was tested
  97. :o: : does not apply
  99. :x: : not supported by MCU
  101. ### XML Entities
  103. [`clueboard`](https://github.com/qmk/qmk_firmware/tree/master/keyboards/clueboard)  &larr; This is the organization folder, there's no `rules.mk` file
  105. 1&ndash;4
  107. Command+<code>&#96;</code>
  109. ## Styling
  111. ### CSS-ish
  113. <b style="font-size:150%">This is 150% of normal sizing, and bold!</b>
  116. ### Tables
  118. | Column A | Column B |
  119. |----------|----------|
  120. | Left     | Right    |
  122. ### Indented sections
  124. > Indent without any sort of marker
  126. ?> Query, this?
  128. !> Notification, damnit!
  130. ::: info
  131. This is an info box.
  132. :::
  134. ::: tip
  135. This is a tip.
  136. :::
  138. ::: warning
  139. This is a warning.
  140. :::
  142. ::: danger
  143. This is a dangerous warning.
  144. :::
  146. ::: details
  147. This is a details block.
  148. :::
  150. ### Keyboard keys
  152. <kbd>,</kbd>
  154. <kbd>Right Alt</kbd>+<kbd>Right Shift</kbd>
  156. 1. Click <kbd>File</kbd> > <kbd>New</kbd> > <kbd>Makefile Project with Existing Code</kbd>
  158. 1. Click <kbd><kbd>File</kbd> > <kbd>Preferences ></kbd> > <kbd>Settings</kbd> </kbd>
  160. 1. Hit Ctrl-<code>&#96;</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.
  162.    This should start the terminal in the workspace's folder (so the `qmk_firmware` folder), and then you can compile your keyboard. 
  165. ### Code Blocks
  167. Inline code with tag: <code>test</code>
  169. Inline code with backticks: `test`
  171.     This is preformatted
  172.     Indented by 4 spaces
  173.     The letters lined up
  175. ```c
  176. int c_code(void) {
  177.     return -1;
  178. }
  179. ```
  181. ```makefile
  182. ifeq ($(BUILD),)
  183.      CHUNDER_REQUIRED = yes
  184. endif
  185. ```
  187. ```python
  188. from pathlib import Path
  190. p = Path('/path/to/qmk_firmware')
  191. ```
  193. ```json
  194. {
  195.     "a": "b",
  196.     "c": 4,
  197.     "d": {
  198.         "e": [
  199.             0, 1, 2, 3
  200.         ]
  201.     }
  202. }
  203. ```
  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. ```
  214. Indented code as part of a list:
  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.   ```
  224. ### Sub/Superscript
  226. <sub>This is subscripted, apparently.</sub>
  228. <sup>This is superscripted, apparently.</sup>
  230. I<sup>2</sup>C
  232. T<sub>0H</sub>, T<sub>0L</sub>
  234. ### Tabs
  236. Tabs are based on section headers, with `**` enclosing the tab title.
  238. <!-- tabs:start -->
  240. #### ** Tab one **
  242. Content one
  244. <!-- tabs:start -->
  246. ##### ** Nested one **
  248. Nested content one
  250. ##### ** Nested two **
  252. Nested content two
  254. <!-- tabs:end -->
  256. #### ** Tab two **
  258. Content two
  260. #### ** Tab three **
  262. Content three
  264. <!-- tabs:end -->
  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. ::::
  280. ## Details sections
  282. Expandable:
  284. <details>
  285.     <summary>Some summary text that shows up before expanding</summary>
  287. !> Embedded notification!
  289. This is some inner content.
  290. </details>
  292. ## Embed
  294. [example embed](__capabilities_inc.md ':include')
  296. <!--@include: ./__capabilities_inc.md-->
  298.   [1]: https://en.wikipedia.org/wiki/Eclipse_(software)