qmk_firmware/assets/documentation_best_practices.md.BtEjePaZ.js

import { _ as _export_sfc, c as createElementBlock, o as openBlock, a8 as createStaticVNode } from "./chunks/framework.DyMmIvSC.js";
const __pageData = JSON.parse('{"title":"Documentation Best Practices","description":"","frontmatter":{},"headers":[],"relativePath":"documentation_best_practices.md","filePath":"documentation_best_practices.md"}');
const _sfc_main = { name: "documentation_best_practices.md" };
const _hoisted_1 = /* @__PURE__ */ createStaticVNode('<h1 id="documentation-best-practices" tabindex="-1">Documentation Best Practices <a class="header-anchor" href="#documentation-best-practices" aria-label="Permalink to &quot;Documentation Best Practices&quot;">​</a></h1><p>This 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.</p><h1 id="page-opening" tabindex="-1">Page Opening <a class="header-anchor" href="#page-opening" aria-label="Permalink to &quot;Page Opening&quot;">​</a></h1><p>Your 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.</p><p>Example:</p><div class="language- vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang"></span><pre class="shiki shiki-themes github-light github-dark vp-code"><code><span class="line"><span># My Page Title</span></span>\n<span class="line"><span></span></span>\n<span class="line"><span>This 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&#39;s by drone.</span></span></code></pre></div><h1 id="headings" tabindex="-1">Headings <a class="header-anchor" href="#headings" aria-label="Permalink to &quot;Headings&quot;">​</a></h1><p>Your page should generally have multiple &quot;H1&quot; 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.</p><h1 id="styled-hint-blocks" tabindex="-1">Styled Hint Blocks <a class="header-anchor" href="#styled-hint-blocks" aria-label="Permalink to &quot;Styled Hint Blocks&quot;">​</a></h1><p>You can have styled hint blocks drawn around text to draw attention to it.</p><h3 id="important" tabindex="-1">Important <a class="header-anchor" href="#important" aria-label="Permalink to &quot;Important&quot;">​</a></h3><div class="language- vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang"></span><pre class="shiki shiki-themes github-light github-dark vp-code"><code><span class="line"><span>::: warning</span></span>\n<span class="line"><span>This is important</span></span>\n<span class="line"><span>:::</span></span></code></pre></div><p>Renders as:</p><div class="warning custom-block"><p class="custom-block-title">WARNING</p><p>This is important</p></div><h3 id="general-tips" tabindex="-1">General Tips <a class="header-anchor" href="#general-tips" aria-label="Permalink to &quot;General Tips&quot;">​</a></h3><div class="language- vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang"></span><pre class="shiki shiki-themes github-light github-dark vp-code"><code><span class="line"><span>::: tip</span></span>\n<span class="line"><span>This is a helpful tip.</span></span>\n<span class="line"><span>:::</span></span></code></pre></div><p>Renders as:</p><div class="tip custom-block"><p class="custom-block-title">TIP</p><p>This is a helpful tip.</p></div><h1 id="documenting-features" tabindex="-1">Documenting Features <a class="header-anchor" href="#documenting-features" aria-label="Permalink to &quot;Documenting Features&quot;">​</a></h1><p>If you create a new feature for QMK, create a documentation page for it. It doesn&#39;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:</p><div class="language-markdown vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">markdown</span><pre class="shiki shiki-themes github-light github-dark vp-code"><code><span class="line
const _hoisted_23 = [
  _hoisted_1
];
function _sfc_render(_ctx, _cache, $props, $setup, $data, $options) {
  return openBlock(), createElementBlock("div", null, _hoisted_23);
}
const documentation_best_practices = /* @__PURE__ */ _export_sfc(_sfc_main, [["render", _sfc_render]]);
export {
  __pageData,
  documentation_best_practices as default
};