Install: Replace HTML/Markdown titles with Hugo front matter

[RichieEscarez]

OPEN ITEMS & TRACKING

See other open items listed in the parent tracking issue: #724

Install docs section (in order of priority)

Assigned - @samodell

release-0.3 branch

• ./install/Knative-with-Minishift.md
• ./install/Knative-with-IKS.md
• ./install/Knative-with-Docker-for-Mac.md
• ./install/Knative-with-Gardener.md
• ./install/Knative-custom-install.md
• ./install/README.md (included in _index.md)
• ./install/getting-started-knative-app.md
• ./install/Knative-with-Minikube.md
• ./install/Knative-with-PKS.md
• ./install/Knative-with-AKS.md
• ./install/Knative-with-GKE.md
• ./install/Knative-with-OpenShift.md
• ./install/Knative-with-any-k8s.md
• ./install/check-install-version.md
• ./install/Knative-with-ICP.md

master branch

Hopefully we can cherry pick commits from 0.3.

release-0.2 branch

No change, just point to GitHub repo

release-0.1 branch

No change, just point to GitHub repo

COPY OF DETAILS FROM #724:

What is changing?

To migrate from a repo to a formal Knative Documentation Site requires that each page in our doc set include "front matter" (specifically for content that we want "exposed and visible", for example rendered in the navigation and tracked in a dynamic Hugo sitemap.xml).

Hugo front matter

For the Knative site, there are two known required front matter variables (we will use YAML):

• title: ""
• weight:

GOAL
Get the first draft of the Knative docs site up and then iterate on fixes from there. Site progress and status.

ACTION
How to add Knative front matter:

1. Choose from one of the Issues below that track the status and open items for a given section:

   1. In the Issue that you choose, check each file that you want to claim (to notify others of status and avoid duplicate work).
   2. Open a PR to share your status. Tip: Add and remove the Hold label (/hold) to indicate that you have in-flight changes and when you are ready for a review.

2. Add the following YAML front template to the very top of the file, moving everything else down:

   ---
   title: "COPY_H1/(#)_TITLE_HERE"
   #linkTitle: "OPTIONAL_ALTERNATE_NAV_TITLE"
   weight: TWO_DIGIT_INTEGER_HERE
   ---
   

   Leave one line gap/white space between the closing --- YAML front matter tag and the topic text.

3. Move the main topic title that currently exists in the topic, into the title: "" variable. The title variable displays both the topic title and adds the file to the left navigation bar. Remember to delete the HTML or Markdown title/line after you move the text (otherwise two duplicate titles will render)

4. If you want use an alternate title that displays in the navigation menu (for example, a short concise version), uncomment the linkTitle: variable and add the alternate/short title there.

5. The weight variable specifies the position of the topic in the left navigation tree (where a folder and corresponding _index.html file define that section or branch in the nav tree).

   • If you have a understanding of the info architecture and user flow, you should order each file that you add front matter to. If you start with the file that you want at the top of the navigation (lower numbers at top, high weights show below), then start with weight of 5 (weight= 5) and increment by 5's (10, 15....) from there (this allows a gap of 4 so that other files can be inserted between if necessary).

   • If you are unsure of the order that your content should display, you can simply increment each file that you add front matter to by 5 (5, 10, ....). Then we can revisit the order at a later time. Please comment and then create an issue explaining that you have do so (so this action item is not lost).

Example:
In the following example, the # Contributing to Knative markdown title is replaced with Hugo front matter:

$ git diff content/
diff --git a/content/en/contributing/CONTRIBUTING.md b/content/en/contributing/CONTRIBUTING.md
index d75c7de..9651946 100644
--- a/content/en/contributing/CONTRIBUTING.md
+++ b/content/en/contributing/CONTRIBUTING.md
@@ -1,4 +1,7 @@
-# Contributing to Knative
+---
+title: "Contributing to Knative"
+linkTitle: "Contributing" 
+weight: 10
+---

So, you want to hack on Knative? Yay!

see staged file in GitHub fork