auri.ee
keyboard stuff
1# Documentation Best Practices
2
3This page exists to document best practices when writing documentation for QMK. Following these guidelines will help to keep a consistent tone and style, which will in turn help other people more easily understand QMK.
4
5# Page Opening
6
7Your documentation page should generally start with an H1 heading, followed by a 1 paragraph description of what the user will find on this page. Keep in mind that this heading and paragraph will sit next to the Table of Contents, so keep the heading short and avoid long strings with no whitespace.
8
9Example:
10
11```
12# My Page Title
13
14This page covers my super cool feature. You can use this feature to make coffee, squeeze fresh oj, and have an egg mcmuffin and hashbrowns delivered from your local macca's by drone.
15```
16
17# Headings
18
19Your page should generally have multiple "H1" headings. Only H1 and H2 headings will included in the Table of Contents, so plan them out appropriately. Excess width should be avoided in H1 and H2 headings to prevent the Table of Contents from getting too wide.
20
21# Styled Hint Blocks
22
23You can have styled hint blocks drawn around text to draw attention to it.
24
25### Important
26
27```
28::: warning
29This is important
30:::
31```
32
33Renders as:
34
35::: warning
36This is important
37:::
38
39### General Tips
40
41```
42::: tip
43This is a helpful tip.
44:::
45```
46
47Renders as:
48
49::: tip
50This is a helpful tip.
51:::
52
53
54# Documenting Features
55
56If you create a new feature for QMK, create a documentation page for it. It doesn't have to be very long, a few sentences describing your feature and a table listing any relevant keycodes is enough. Here is a basic template:
57
58```markdown
59# My Cool Feature
60
61This page describes my cool feature. You can use my cool feature to make coffee and order cream and sugar to be delivered via drone.
62
63## My Cool Feature Keycodes
64
65|Long Name|Short Name|Description|
66|---------|----------|-----------|
67|KC_COFFEE||Make Coffee|
68|KC_CREAM||Order Cream|
69|KC_SUGAR||Order Sugar|
70```
71
72Place your documentation into `docs/features/<my_cool_feature>.md`, and add that file to the appropriate place in `docs/_sidebar.json`. If you have added any keycodes be sure to add them to `docs/keycodes.md` with a link back to your feature page.