diff --git a/content/en/docs/contribute/style/style-guide.md b/content/en/docs/contribute/style/style-guide.md index 960efc01a7..adb842453e 100644 --- a/content/en/docs/contribute/style/style-guide.md +++ b/content/en/docs/contribute/style/style-guide.md @@ -449,7 +449,7 @@ Shortcodes inside include statements will break the build. You must insert them Use a single newline to separate block-level content like headings, lists, images, code blocks, and others. The exception is second-level headings, where it should be two newlines. Second-level headings follow the first-level (or the title) without any preceding paragraphs or texts. A two line spacing helps visualize the overall structure of content in a code editor better. -### Headings +### Headings and titles {#headings} People accessing this documentation may use a screen reader or other assistive technology (AT). [Screen readers](https://en.wikipedia.org/wiki/Screen_reader) are linear output devices, they output items on a page one at a time. If there is a lot of content on a page, you can use headings to give the page an internal structure. A good page structure helps all readers to easily navigate the page or filter topics of interest. @@ -459,7 +459,12 @@ Do | Don't Update the title in the front matter of the page or blog post. | Use first level heading, as Hugo automatically converts the title in the front matter of the page into a first-level heading. Use ordered headings to provide a meaningful high-level outline of your content. | Use headings level 4 through 6, unless it is absolutely necessary. If your content is that detailed, it may need to be broken into separate articles. Use pound or hash signs (`#`) for non-blog post content. | Use underlines (`---` or `===`) to designate first-level headings. -Use sentence case for headings. For example, **Extend kubectl with plugins** | Use title case for headings. For example, **Extend Kubectl With Plugins** +Use sentence case for headings in the page body. For example, +**Extend kubectl with plugins** | Use title case for headings in the page body. For example, **Extend Kubectl With Plugins** +Use title case for the page title in the front matter. For example, +`title: Kubernetes API Server Bypass Risks` | Use sentence case for page titles +in the front matter. For example, don't use +`title: Kubernetes API server bypass risks` {{< /table >}} ### Paragraphs