Merge pull request #4155 from mrbobbytables/fix-markdown-formatting

Update contributor guide formatting to be Hugo compatible.

7 files changed, 124 insertions, 90 deletions

diff --git a/contributors/guide/README.md b/contributors/guide/README.md
index d6040224..e95d3704 100644
--- a/contributors/guide/README.md
+++ b/contributors/guide/README.md
@@ -4,7 +4,6 @@ weight: 1
 slug: "guide" 
 ---
 
-
 <!-- 
 Contributing to this document? 
 Please use semantic line feeds for readability: http://rhodesmill.org/brandon/2012/one-sentence-per-line/ 
@@ -17,35 +16,38 @@ Feel free to browse the [open issues](https://github.com/kubernetes/community/is
 
 Welcome to Kubernetes! 
 
--   [Before you get started](#before-you-get-started)
-    -   [Sign the CLA](#sign-the-cla)
-    -   [Code of Conduct](#code-of-conduct)
-    -   [Setting up your development
-        environment](#setting-up-your-development-environment)
-    -   [Community Expectations and Roles](#community-expectations-and-roles)
-        -   [Thanks](#thanks)
--   [Your First Contribution](#your-first-contribution)
-    -   [Find something to work on](#find-something-to-work-on)
-        -   [Find a good first topic](#find-a-good-first-topic)
-        -   [Learn about SIGs](#learn-about-sigs)
-        -   [SIG-specific contributing guidelines](#sig-specific-contributing-guidelines)
-        -   [File an Issue](#file-an-issue)
--   [Contributing](#contributing)
-    -   [Communication](#communication)
-    -   [GitHub workflow](#github-workflow)
-    -   [Open a Pull Request](#open-a-pull-request)
-    -   [Code Review](#code-review)
-    -   [Testing](#testing)
-    -   [Security](#security)    
-    -   [Documentation](#documentation)
-    -   [Issues Management or Triage](#issues-management-or-triage)
--   [Kubernetes Contributor Playground](#kubernetes-contributor-playground)
-    -   [Youtube playlist](#youtube-playlist)
--   [Community](#community)
-    -   [Communication](#communication-1)
-    -   [Events](#events)
-        -   [Meetups](#meetups)
-    -   [Mentorship](#mentorship)
+- [Welcome](#welcome)
+- [Before you get started](#before-you-get-started)
+  - [Sign the CLA](#sign-the-cla)
+  - [Code of Conduct](#code-of-conduct)
+  - [Setting up your development environment](#setting-up-your-development-environment)
+  - [Community Expectations and Roles](#community-expectations-and-roles)
+- [Your First Contribution](#your-first-contribution)
+  - [Find something to work on](#find-something-to-work-on)
+    - [Find a good first topic](#find-a-good-first-topic)
+      - [Issue Assignment in Github](#issue-assignment-in-github)
+    - [Learn about SIGs](#learn-about-sigs)
+      - [SIG structure](#sig-structure)
+      - [Find a SIG that is related to your contribution](#find-a-sig-that-is-related-to-your-contribution)
+    - [SIG-specific contributing guidelines](#sig-specific-contributing-guidelines)
+    - [File an Issue](#file-an-issue)
+- [Contributing](#contributing)
+    - [Communication](#communication)
+  - [GitHub workflow](#github-workflow)
+  - [Open a Pull Request](#open-a-pull-request)
+  - [Code Review](#code-review)
+  - [Testing](#testing)
+  - [Security](#security)
+  - [Documentation](#documentation)
+  - [Issues Management or Triage](#issues-management-or-triage)
+- [Kubernetes Contributor Playground](#kubernetes-contributor-playground)
+  - [Youtube playlist](#youtube-playlist)
+- [Community](#community)
+  - [Communication](#communication-1)
+  - [Events](#events)
+    - [Meetups](#meetups)
+  - [Mentorship](#mentorship)
+- [Advanced Topics](#advanced-topics)
 
 # Before you get started
 
@@ -146,8 +148,8 @@ If you are not sure about the correct SIG for an issue, you can try SIG-contribu
 ### SIG-specific contributing guidelines
 Some SIGs have their own `CONTRIBUTING.md` files, which may contain extra information or guidelines in addition to these general ones.
 These are located in the SIG-specific community directories:
+
 - [`/sig-apps/CONTRIBUTING.md`](/sig-apps/CONTRIBUTING.md)
-- [`/sig-aws/CONTRIBUTING.md`](/sig-aws/CONTRIBUTING.md)
 - [`/sig-cli/CONTRIBUTING.md`](/sig-cli/CONTRIBUTING.md)
 - [`/sig-multicluster/CONTRIBUTING.md`](/sig-multicluster/CONTRIBUTING.md)
 - [`/sig-storage/CONTRIBUTING.md`](/sig-storage/CONTRIBUTING.md)
diff --git a/contributors/guide/bug-bounty.md b/contributors/guide/bug-bounty.md
index 32b72819..60f48b43 100644
--- a/contributors/guide/bug-bounty.md
+++ b/contributors/guide/bug-bounty.md
@@ -1,7 +1,7 @@
 ---
 title: "Bug Bounty Programs"
 weight: 1
-slug: "bounties"
+slug: "bug-bounty"
 ---
 
 This program is a **work in progress**. This tracks the currently proposed program, but the bug
diff --git a/contributors/guide/github-workflow.md b/contributors/guide/github-workflow.md
index 8174aaf8..1963b206 100644
--- a/contributors/guide/github-workflow.md
+++ b/contributors/guide/github-workflow.md
@@ -1,7 +1,7 @@
 ---
 title: "GitHub Workflow"
 weight: 1
-slug: "github"
+slug: "github-workflow"
 ---
 
 ![Git workflow](git_workflow.png)
@@ -173,38 +173,35 @@ _If you have upstream write access_, please refrain from using the
 `Revert` button in the GitHub UI for creating the PR, because GitHub
 will create the PR branch inside the main repository rather than inside your fork.
 
-1. Create a branch and sync it with upstream.
+- Create a branch and sync it with upstream.
 
-```sh
-# create a branch
-git checkout -b myrevert
-
-# sync the branch with upstream
-git fetch upstream
-git rebase upstream/master
-```
+  ```sh
+  # create a branch
+  git checkout -b myrevert
 
-2. If the commit you wish to revert is a:
+  # sync the branch with upstream
+  git fetch upstream
+  git rebase upstream/master
+  ```
+- If the commit you wish to revert is a:<br>
+  - **merge commit:**
 
-- merge commit:
+    ```sh
+    # SHA is the hash of the merge commit you wish to revert
+    git revert -m 1 SHA
+    ```
 
-```sh
-# SHA is the hash of the merge commit you wish to revert
-git revert -m 1 SHA
-```
-
-- single commit:
+  - **single commit:**
 
-```sh
-# SHA is the hash of the single commit you wish to revert
-git revert SHA
-```
+    ```sh
+    # SHA is the hash of the single commit you wish to revert
+    git revert SHA
+    ```
 
-3. This will create a new commit reverting the changes.
-Push this new commit to your remote.
+- This will create a new commit reverting the changes. Push this new commit to your remote.
 
 ```sh
 git push ${your_remote_name} myrevert
 ```
 
-4. [Create a Pull Request](#7-create-a-pull-request) using this branch.
+- [Create a Pull Request](#7-create-a-pull-request) using this branch.
\ No newline at end of file
diff --git a/contributors/guide/non-code-contributions.md b/contributors/guide/non-code-contributions.md
index 43fd10e2..4ec2838c 100644
--- a/contributors/guide/non-code-contributions.md
+++ b/contributors/guide/non-code-contributions.md
@@ -1,7 +1,7 @@
 ---
 title: "Non-code Contributions"
 weight: 1
-slug: "non-code" 
+slug: "non-code-contributions"
 ---
 
 *This section is new and in progress. Expect this document to change often.*
diff --git a/contributors/guide/pull-requests.md b/contributors/guide/pull-requests.md
index d2e252c8..c403c974 100644
--- a/contributors/guide/pull-requests.md
+++ b/contributors/guide/pull-requests.md
@@ -7,27 +7,28 @@ slug: "pull-requests"
 This doc explains the process and best practices for submitting a pull request to the [Kubernetes project](https://github.com/kubernetes/kubernetes) and its associated sub-repositories. It should serve as a reference for all contributors, and be useful especially to new and infrequent submitters.
 
 - [Before You Submit a Pull Request](#before-you-submit-a-pull-request)
-  * [Run Local Verifications](#run-local-verifications)
+  - [Run Local Verifications](#run-local-verifications)
 - [The Pull Request Submit Process](#the-pull-request-submit-process)
-  * [The Testing and Merge Workflow](#the-testing-and-merge-workflow)
-  * [Marking Unfinished Pull Requests](#marking-unfinished-pull-requests)
-  * [Comment Commands Reference](#comment-commands-reference)
-  * [Automation](#automation)
-  * [How the e2e Tests Work](#how-the-e2e-tests-work)
-- [Why was my Pull Request closed?](#why-was-my-pull-request-closed)
-- [Why is my Pull Request not getting reviewed?](#why-is-my-pull-request-not-getting-reviewed)
+  - [The Testing and Merge Workflow](#the-testing-and-merge-workflow)
+  - [Marking Unfinished Pull Requests](#marking-unfinished-pull-requests)
+  - [Pull Requests and the Release Cycle](#pull-requests-and-the-release-cycle)
+  - [Comment Commands Reference](#comment-commands-reference)
+  - [Automation](#automation)
+  - [How the e2e Tests Work](#how-the-e2e-tests-work)
+- [Why was my pull request closed?](#why-was-my-pull-request-closed)
+- [Why is my pull request not getting reviewed?](#why-is-my-pull-request-not-getting-reviewed)
 - [Best Practices for Faster Reviews](#best-practices-for-faster-reviews)
-  * [0. Familiarize yourself with project conventions](#0-familiarize-yourself-with-project-conventions)
-  * [1. Is the feature wanted? File a Kubernetes Enhancement Proposal](#1-is-the-feature-wanted-file-a-kubernetes-enhancement-proposal)
-  * [2. Smaller Is Better: Small Commits, Small Pull Requests](#2-smaller-is-better-small-commits-small-pull-requests)
-  * [3. Open a Different Pull Request for Fixes and Generic Features](#3-open-a-different-pull-request-for-fixes-and-generic-features)
-  * [4. Comments Matter](#4-comments-matter)
-  * [5. Test](#5-test)
-  * [6. Squashing and Commit Titles](#6-squashing-and-commit-titles)
-  * [7. KISS, YAGNI, MVP, etc.](#7-kiss-yagni-mvp-etc)
-  * [8. It's OK to Push Back](#8-its-ok-to-push-back)
-  * [9. Common Sense and Courtesy](#9-common-sense-and-courtesy)
-  * [10. Trivial Edits](#10-trivial-edits)
+  - [0. Familiarize yourself with project conventions](#0-familiarize-yourself-with-project-conventions)
+  - [1. Is the feature wanted? File a Kubernetes Enhancement Proposal](#1-is-the-feature-wanted-file-a-kubernetes-enhancement-proposal)
+  - [2. Smaller Is Better: Small Commits, Small Pull Requests](#2-smaller-is-better-small-commits-small-pull-requests)
+  - [3. Open a Different Pull Request for Fixes and Generic Features](#3-open-a-different-pull-request-for-fixes-and-generic-features)
+  - [4. Comments Matter](#4-comments-matter)
+  - [5. Test](#5-test)
+  - [6. Squashing and Commit Titles](#6-squashing-and-commit-titles)
+  - [7. KISS, YAGNI, MVP, etc.](#7-kiss-yagni-mvp-etc)
+  - [8. It's OK to Push Back](#8-its-ok-to-push-back)
+  - [9. Common Sense and Courtesy](#9-common-sense-and-courtesy)
+  - [10. Trivial Edits](#10-trivial-edits)
 
 # Before You Submit a Pull Request
 
@@ -62,7 +63,7 @@ The Kubernetes merge workflow uses labels, applied by [commands](https://prow.k8
 
 _Example:_ To apply a SIG label, you would type in a comment:
 ```
-/sig aws
+/sig apps
 ```
 
 *NOTE: For pull requests that are in progress but not ready for review,
@@ -228,7 +229,7 @@ We want every pull request to be useful on its own, so use your best judgment on
 
 As a rule of thumb, if your pull request is directly related to Feature-X and nothing else, it should probably be part of the Feature-X pull request. If you can explain why you are doing seemingly no-op work ("it makes the Feature-X change easier, I promise") we'll probably be OK with it. If you can imagine someone finding value independently of Feature-X, try it as a pull request. (Do not link pull requests by `#` in a commit description, because GitHub creates lots of spam. Instead, reference other pull requests via the pull request your commit is in.)
 
-## 3. Open a Different pull request for Fixes and Generic Features
+## 3. Open a Different Pull Request for Fixes and Generic Features
 
 **Put changes that are unrelated to your feature into a different pull request.**
 
diff --git a/contributors/guide/release-notes.md b/contributors/guide/release-notes.md
index 0b3223c4..1c217cd6 100644
--- a/contributors/guide/release-notes.md
+++ b/contributors/guide/release-notes.md
@@ -1,7 +1,7 @@
 ---
 title: "Adding Release Notes"
 weight: 1
-slug: "adding-release-notes" 
+slug: "release-notes"
 ---
 
 On the kubernetes/kubernetes repository, release notes are required for any pull request with user-visible changes, such as bug-fixes, feature additions, and output format changes.
diff --git a/contributors/guide/style-guide.md b/contributors/guide/style-guide.md
index 38acb36c..3b81ef5b 100644
--- a/contributors/guide/style-guide.md
+++ b/contributors/guide/style-guide.md
@@ -1,7 +1,7 @@
 ---
 title: "Documentation Style Guide"
 weight: 1
-slug: "documentation-style-guide" 
+slug: "style-guide"
 ---
 
 This style guide is for content in the Kubernetes github [community repository].
@@ -10,21 +10,23 @@ It is an extension of the [Kubernetes documentation style-guide].
 These are **guidelines**, not rules. Use your best judgement.
 
 - [Cheatsheet](#cheatsheet)
-- [Content design, formatting, and language](#content-formatting-and-language)
-  - [Contact information](#contact-information)
-  - [Dates and times](#dates-and-times)
-  - [Diagrams, images and other assets](#diagrams-images-and-other-assets)
+  - [Cheatsheet: Content Design, Formatting, and Language](#cheatsheet-content-design-formatting-and-language)
+  - [Cheatsheet: Markdown](#cheatsheet-markdown)
+- [Content Design, Formatting, and Language](#content-design-formatting-and-language)
+  - [Contact Information](#contact-information)
+  - [Dates and Times](#dates-and-times)
+  - [Diagrams, Images and Other Assets](#diagrams-images-and-other-assets)
   - [Document Layout](#document-layout)
-  - [Formatting text](#formatting-text)
-  - [Language, grammar, and tone](#language-grammar-and-tone)
-  - [Moving a document](#moving-a-document)
+  - [Formatting Text](#formatting-text)
+  - [Language, Grammar and Tone](#language-grammar-and-tone)
+  - [Moving a Document](#moving-a-document)
   - [Punctuation](#punctuation)
   - [Quotation](#quotation)
-- [Markdown formatting](#markdown-and-formatting)
+- [Markdown Formatting](#markdown-formatting)
   - [Code Blocks](#code-blocks)
   - [Emphasis](#emphasis)
   - [Headings](#headings)
-  - [Horizontal Lines](#horizontal-lines)
+  - [Horizontal Rules](#horizontal-rules)
   - [Line Length](#line-length)
   - [Links](#links)
   - [Lists](#lists)
@@ -38,9 +40,11 @@ These are **guidelines**, not rules. Use your best judgement.
 ### Cheatsheet: Content Design, Formatting, and Language
 
 **[Contact Information:](#contact-information)**
+
 - Use official Kubernetes contact information.
 
 **[Dates and Times:](#dates-and-times)**
+
 - Format dates as `month day, year`. (December 13, 2018)
 - When conveying a date in numerical form, use [ISO 8601] Format: `yyyy-mm-dd`.
 - Use the 24 hour clock when referencing time.
@@ -53,6 +57,7 @@ These are **guidelines**, not rules. Use your best judgement.
   - `http://www.thetimezoneconverter.com/?t=<TIME REFERENCE>&tz=<TZ REFERENCE>`
 
 **[Diagrams, Images and Other Assets:](#diagrams-images-and-other-assets)**
+
 - Images and other assets should be stored in the same directory as the document
   that is referencing it.
 - Filenames should be lowercase and descriptive of what they are referencing.
@@ -61,6 +66,7 @@ These are **guidelines**, not rules. Use your best judgement.
 - Use the [Kubernetes icon set] for architectural diagrams.
 
 **[Document Layout:](#document-layout)**
+
 - Documents should follow the general template of:
   - Document metadata (if appropriate).
   - Title in `H1` (a single `#`).
@@ -71,6 +77,7 @@ These are **guidelines**, not rules. Use your best judgement.
 - Large content or topic shifts should be separated with a horizontal rule.
 
 **[Formatting Text:](#formatting-text)**
+
 - API objects:
   - Follow the established [API naming convention] when referring to API Objects.
   - Do not split API object names into their components.
@@ -84,6 +91,7 @@ These are **guidelines**, not rules. Use your best judgement.
   - Object field names.
 
 **[Language, Grammar and Tone:](#language)**
+
 - Documentation should be written in English.
 - Prefer an active voice and present tense when possible.
 - Use simple and direct language.
@@ -97,12 +105,14 @@ These are **guidelines**, not rules. Use your best judgement.
   document unless it is commonly known. (example: TCP/IP)
 
 **[Moving a Document:](#moving-a-document)**
+
 - Use `[git-mv]` to move documents.
 - Commit moved documents separately from any other changes.
 - When a document has moved, leave a tombstone file with a removal date in its
   place.
 
 **[Punctuation:](#punctuation)**
+
 - Do not use punctuation in headings.
 - End full sentences with a period.
   - **Exception:** When a sentence ends with a URL or if the text would be
@@ -123,6 +133,7 @@ These are **guidelines**, not rules. Use your best judgement.
 ### Cheatsheet: Markdown
 
 **[Code Blocks:](#code-blocks)**
+
 - When possible, reference the language at the beginning of a Code Block.
 - When a code block is used to reference a shell, do not include the command
   prompt (`$`).
@@ -130,11 +141,13 @@ These are **guidelines**, not rules. Use your best judgement.
 - Separate commands from output.
 
 **[Emphasis:](#emphasis)**
+
 - Use two asterisks (`**`) for **Bold** text.
 - Use an underscore (`_`) for _Italics_.
 - Use two tildes (`~~`) for ~~Strikethrough~~.
 
 **[Headings:](#headings)**
+
 - Use a single `H1` (`#`) Heading per document.
   - **Exception:** `H1` may be used multiple times in the same document when
     there is a large content shift or "chapter" change.
@@ -149,13 +162,16 @@ These are **guidelines**, not rules. Use your best judgement.
 - Avoid using links in headings.
 
 **[Horizontal Rules:](#horizontal-lines)**
+
 - Use three dashes (`---`) to denote a horizontal rule.
 - Use a horizontal rule (`---`) to logically separate large sections.
 
 **[Line Length:](#line-length)**
+
 - Prefer an 80 character line limit.
 
 **[Links:](#links)**
+
 - Prefer using reference style links over inline style links.
 - When linking within the same directory, use a relative link.
 - When linking to a document outside of the current directory, use the absolute
@@ -166,6 +182,7 @@ These are **guidelines**, not rules. Use your best judgement.
   - sigs.k8s.io -> github.com/kubernetes-sigs
 
 **[Lists:](#lists)**
+
 - Capitalize the first character of each entry unless the item is explicitly
   case sensitive.
 - End each entry with a period if it is a sentence or phrase.
@@ -177,11 +194,13 @@ These are **guidelines**, not rules. Use your best judgement.
   two times.
 
 **[Metadata:](#metadata)**
+
 - If the document is intended to be surfaced on the Contributor Site; include a
   yaml metadata header at the beginning of the document.
 - Metadata must include the `title` attribute.
 
 **[Tables:](#tables)**
+
 - Use tables for structured information.
 - Tables do not need to adhere to the suggested line length.
 - Avoid long inline links.
@@ -387,6 +406,7 @@ external appearance.
   - Tombstones function as a pointer and give users a time to update their own
     documentation and bookmarks. Their usefulness is time-bounded and should be
     removed when they would logically no longer serve their purpose.
+
     ```markdown
     This file has moved to https://git.k8s.io/community/contributors/guide/README.md.
 
@@ -430,6 +450,7 @@ external appearance.
     highlighting. This can be enabled by supplying the name of the language
     after the three back-ticks (`` ``` ``) at the start of a code block.
   - **Good example:**
+
     `````
     ```go
     import (
@@ -439,6 +460,7 @@ external appearance.
     ```
     `````
   - **Bad example:**
+
     `````
     ```
     import (
@@ -453,10 +475,12 @@ external appearance.
     command prompt. The exception to this is when a code block is being used
     for raw shell output such as debug logs.
   - **Good example:**
+  
     ```
     kubectl get pods -o wide
     ```
   - **Bad example:**
+  
     ```
     $ kubectl get pods -o wide
     ```
@@ -464,6 +488,7 @@ external appearance.
   - Separating the command from the output makes both the command and output
     more generally readable.
   - **Good example:**
+
     ```
     kubectl get pods
     ```
@@ -472,6 +497,7 @@ external appearance.
     nginx    1/1       Running   0          13s    10.200.0.4   worker0
     ```
   - **Bad example:**
+
     ```
     kubectl get pods
     NAME     READY     STATUS    RESTARTS   AGE    IP           NODE
@@ -544,12 +570,14 @@ relative links. However, how and what they're being linked to can vary widely.
     large or covers many topics, place the link at the end of the logical
     chapter or section.
   - **Example:**
+  
     ```
     See the [Code of Conduct] for more information.
 
     [code of conduct]: https://git.k8s.io/community/code-of-conduct.md
     ```
   - **Example:**
+
     ```
     See the [Code of Conduct][coc] for more information.
 
@@ -561,10 +589,12 @@ relative links. However, how and what they're being linked to can vary widely.
   - When the file is referenced multiple times within the same document,
     consider using a reference link for a quicker shorthand reference.
   - **Example:**
+
     ```
     See the [Code of Conduct](code-of-conduct.md) for more information
     ```
   - **Example:**
+
     ```
     See the [Code of Conduct][coc] for more information
 
@@ -576,6 +606,7 @@ relative links. However, how and what they're being linked to can vary widely.
     the link to the target or destination document will remain intact and not
     have to be updated.
   - **Example:**
+
     ```
     See the [Coding Convention] doc for more information.
 
@@ -592,6 +623,7 @@ relative links. However, how and what they're being linked to can vary widely.
     | https://sigs.k8s.io | https://github.com/kubernetes-sigs |
 
   - **Example:**
+
     ```
     The super cool [prow tool] resides in the test-infra repo under the kubernetes organization
 
@@ -626,6 +658,7 @@ relative links. However, how and what they're being linked to can vary widely.
     site generators such as [Jekyll] and [Hugo].
   - The metadata header is a yaml block between two sets of `---`.
   - **Example:**
+
     ```
     ---
     title: Super Awesome Doc
@@ -640,6 +673,7 @@ relative links. However, how and what they're being linked to can vary widely.
 
 - Use tables for structured information.
   - **Example:**
+
     ```
     |    Column 1    |    Column 2    |    Column 3    |
     |:--------------:|:--------------:|:--------------:|