New "how to contribute to docs" instructions

[RichieEscarez]

Need to author the instructions about how to contribute to knative.dev, including all the missing Hugo/Docsy/site requirements. When and where to add:

• General info about site:
  - Hugo
  - Docsy
  - Markdown processor info
  - Netlify
  - knative/website repo

• front matter

  ---
  title: “The file’s title (do not include another H1 title in the body).”
  linkTitle: “optional short title”
  weight: 10
  type: “docs”
  ---
  

  • ‘title’ and ‘type: “docs”’ are required.
  • ‘weight’ is also required and allows you to defined
    where that element shows relative to other content in the Nav tree (otherwise elements are
    alphabetical). More info: https://gohugo.io/content-management/front-matter/#predefined
  • ‘linkTitle’ is optional and allows you to provide an
    alternative (shorter) title for the Nav tree.

• Redirect URLs for moved and renamed source files (add aliases to frontmatter): Ensure that all content affected by the nav changes gets a "redirect" #1925

• Dynamic variables. Use them to reduce release maintenance and ensure content accuracy. The following variable are dynamically populated based on the URL of the content in knative.dev:

  • add the corresponding branchname by using the {{< branch >}} variable (shortcode)
  • add the corresponding version number by using the {{< version >}} variable (shortcode)

  See examples in the smoketest page

• SEO (filename (no capital letters, no product names), titles (sentence case), cross links)

• Document linking conventions - all ./ are required for "same directory" relative links

• If there is more than a single .md file in a sub folder, then that folder must include and use an _index.md (to define that "section").

  (ie. need to mention that if you want to add that
  second file to a folder, then you must also add (create) the required
  "section definition" (using an _index.md file).

• Using shortcodes:

  • Optional: Add the following to the frontmatter of a file to show/hide an in-page TOC (uses the "landingtoc" partial)
    By default, the in-page TOC shows in empty/blank _index.md section files to list all the sub-topics in that section.
    - add showlandingtoc: "true" to add the in-page TOC
    - add showlandingtoc: "false" to prevent the in-page TOC from showing on a blank page or non docs type page (for example, a page in the /community section)

  • Nested shortcodes are NOT supported - results in mixed content (.md + HTML) in the markdown that gets processed to HTML (so code (ie HTML or Markdown) is rendered (not just text))

  • {{% readfile file="FILENAME.md" %}} shortcode:

    • In the blank _index.md pages that can automatically generate and render an in-page nav tree. Make clear which files are "included" and rendered on the site using the readfile shortcode.
      ie. add a comment in the included file

      <!-- This file is rendered in knative.dev using the "readfile" shortcode. 
      See the _index.md file in this directory. -->
      

    • Dynamically add code: {{< readfile file="code-written-in.go" code="true" lang="go" >}}

      See examples in the smoketest page

• How to build knative.dev locally: Run https://github.com/knative/website/blob/master/scripts/localbuild.sh

Other "docs contributor" related items:

• Create "getting started" checklist for code contributors #1032
• Determine what a "maintainer" content section might look like #1009
• Docs contrib - make clear the expectations per branch (master vs release-x.x) #1282
• How to build the docs website (knative.dev) locally? #1239
• [WIP] Need "Docs release process" content #1344

Recent items:

• Auto PR staging: https://app.netlify.com/sites/knative/deploys

• How Prow chooses reviewers: https://github.com/kubernetes/test-infra/tree/master/prow/plugins/approve/approvers#blunderbuss-selection-mechanism

• GitHub troubleshooting: Add troubleshooting information to contributor docs #2755

[knative-housekeeping-robot]

Issues go stale after 90 days of inactivity.
Mark the issue as fresh by adding the comment /remove-lifecycle stale.
Stale issues rot after an additional 30 days of inactivity and eventually close.
If this issue is safe to close now please do so by adding the comment /close.

Send feedback to Knative Productivity Slack channel or file an issue in knative/test-infra.

/lifecycle stale

[evankanderson]

/kind good-first-issue

[github-actions]

This issue is stale because it has been open for 90 days with no
activity. It will automatically close after 30 more days of
inactivity. Reopen the issue with /reopen.Mark the issue as
fresh by adding the comment /remove-lifecycle stale.

[github-actions]

This issue is stale because it has been open for 90 days with no
activity. It will automatically close after 30 more days of
inactivity. Reopen the issue with /reopen.Mark the issue as
fresh by adding the comment /remove-lifecycle stale.

[RichieEscarez]

Two items remain:

• Nested shortcodes are NOT supported - results in mixed content (.md + HTML) in the markdown that gets processed to HTML (so code (ie HTML or Markdown) is rendered (not just text)) (today, this is mentioned only here https://github.com/knative/website/blob/main/layouts/shortcodes/readfile.md)
• How Prow chooses reviewers: https://github.com/kubernetes/test-infra/tree/master/prow/plugins/approve/approvers#blunderbuss-selection-mechanism

[abrennan89]

I think it's safe to close this now since we've moved to mkdocs. Anything left to be added should probably just be opened as a new task. I don't think prow auto-selects reviewers anymore anyway.