docs: document formatting quirks of MkDocs and markdownlint (#3034)

Signed-off-by: Meg McRoberts <meg.mcroberts@dynatrace.com>
Signed-off-by: odubajDT <93584209+odubajDT@users.noreply.github.com>
Co-authored-by: odubajDT <93584209+odubajDT@users.noreply.github.com>
Co-authored-by: Moritz Wiesinger <moritz.wiesinger@dynatrace.com>

.github/actions/spelling/expect.txt

@@ -184,6 +184,7 @@ fieldpath
 fieldref
 flyout
 fontawesome
+Frontmatter
 ftp
 fullname
 functionref

docs/docs/contribute/docs/code-docs.md

@@ -0,0 +1,237 @@
+---
+comments: true
+---
+
+# Coding the docs
+
+Keptn documentation is written using the Markdown language,
+with each page written in a separate file.
+The following documents document the language:
+
+* [Markdown Guide](https://www.markdownguide.org/getting-started/#flavors-of-markdown)
+  discusses Markdown structure and background.
+* [Basic Syntax](https://www.markdownguide.org/basic-syntax/)
+  summarizes the standard Markdown syntax
+  that is supported by almost all Markdown variants.
+* [Markdown Cheat Sheet](https://www.markdownguide.org/cheat-sheet/)
+  is a handy reference for the most commonly used Markdown elements.
+
+Markdown supports many variants and the build tools we use
+impose a few special requirements that are discussed here.
+
+## Frontmatter requirements
+
+The top of each documentation source file should look like:
+
+```markdown
+---
+comments: true
+---
+
+# Coding the docs
+
+Beginning of information about the topic.
+
+```
+
+The elements are:
+
+* The `comments` block.
+  This allows readers to post comments to the published page.
+  More configuration can be put here depending on the requirements
+  for the page.
+
+* A level 1 header (`# title`)  with the title of the page
+  as it is displayed in the main canvas of the docs..
+  This must be preceded and followed by a single blank line.
+
+    The title displayed in the left sidebar
+    is determined by the title in the `mkdocs.yml` file.
+    Be sure that these two titles match.
+
+* Text that introduces the information for the page.
+  Do not use stacked headers, with a level 2 header (`## title`)
+  immediately following the level 1 header.
+
+## Comments
+
+To comment a line in the documentation, you can use
+standard HTML comments.
+Prepend the `<!--` string at the beginning of the line,
+and end the line with `-->`
+as in:
+
+```markdown
+<!-- This is a comment -->
+```
+
+## Indentation of nested lists and code blocks
+
+Paragraphs and code blocks that are nested under a list item
+must be indented two spaces from the text of the list item.
+If they are not,
+the indented material is rendered as flush-left
+and ordered lists do not increment the list item number correctly.
+
+For example, the formatting of the bullet list in the preceding section is:
+
+```markdown
+* This is the first list item.
+  With a second sentence in the same paragraph.
+
+* This is the second list item.
+
+    With a second paragraph that is still part of the
+    same list item.
+
+* This is the third list item.
+```
+
+Code blocks must be indented in the same way.
+
+## External links and internal cross-references
+
+Use the standard Markdown conventions for links:
+
+```markdown
+[display-string](target-link)
+```
+
+The syntax of the `target-link` is different
+for external links and internal documentation cross-references.
+
+We recommend putting the link code on a separate line in the source code.
+The markdownlint tool limits the number of characters on a line.
+Links are exempt from this check
+but markdownlint fails the line if it includes text before or after the link.
+This is not absolutely necessary if the link target is short
+but this convention prevents problems.
+
+### External links to and from documentation
+
+Links to and from the documentation set
+from outside the `NAV` path defined in the `mkdocs.yml` file
+use the full URL as displayed in the browser address bar
+for the page for the `target-link`.
+
+This syntax is used for:
+
+* Links from a documentation page to an external page
+* Links **to** files in the same repository as the documentation source
+  but outside the documentation `NAV` path
+* Links **from** files in the same repository as the documentation source
+  but outside the documentation `NAV` path,
+  such as `README.md` and `CONTRIBUTING.md` files
+
+    Links using a relative path to files outside the `NAV` path
+    resolve correctly but the targeted documentation page
+    does not include the contents block in the left frame.
+
+An example of the coding for an external link is:
+
+```markdown
+The Kubernetes
+[Pod](https://kubernetes.io/docs/concepts/workloads/pods/)
+documentation
+```
+
+### Internal cross references in the documentation set
+
+Internal cross-references between pages in the documentation set
+(which is the documentation `NAV` path as defined in the `mkdocs.yml` file)
+use a `target-link` that is a modified version
+of the URL displayed for the page in the rendered documentation.
+
+We suggest that you copy/paste the portion of the URL
+that follows `docs/docs` as the base for your `target-link`.
+You must then make the following modifications:
+
+* Specify the path name of the targeted file
+  relative to `docs/docs` directory
+  using the shell convention where `../` represents
+  the parent directory
+* Add the `.md` suffix to the file name
+* Remove the trailing / from the string
+* When referencing a sub-section of a page,
+  remove the `/` character between the page tag
+  and the `#` character that tags the referenced subsection.
+* When referencing a section of the docs,
+  add the `index.md` filename to the path
+
+Some examples may clarify this.
+
+#### Cross reference a file in another directory
+
+The full URL for the `Analysis` CRD reference page is:
+
+```markdown
+https://keptn.sh/stable/docs/reference/crd-reference/analysis/
+```
+
+To cross-reference this page
+from any page in the `docs/guide` directory
+(or other pages at that level), the code is:
+
+```markdown
+See the
+[Analysis](../reference/crd-reference/analysis.md)
+CRD reference page.
+```
+
+To form this cross-reference::
+
+* Copy/paste the part of the URL after `docs` as a base
+* Insert `../` to go up one directory from `guides` to `docs`,
+  before the path that goes down the `reference/crd-reference` path
+  to identify the file
+* Add the `.md` suffix to `Analysis` to form the actual source file name.
+* Remove the trailing `/` of the URL
+
+#### Cross-reference a sub-section of another page
+
+To get a link to the `Examples` subsection of the `Analysis` reference page,
+view the page in your browser and select `Examples`
+from the contents listing in the right frame.
+This gives you the following URL:
+
+```markdown
+https://keptn.sh/stable/docs/reference/crd-reference/analysis/#examples
+```
+
+To link to that sub-section, the code is:
+
+```markdown
+See
+[Examples](../reference/crd-reference/analysis.md#examples)
+```
+
+You see that the `/` in the URL before `#examples` has been removed.
+
+#### Cross-reference another file in the same directory
+
+Another CRD reference page (which is in the same directory)
+can reference the `Analysis` reference page
+like this:
+
+```markdown
+[Analysis](analysis.md)
+```
+
+#### Cross-reference another section
+
+The URL of the `Installation` section is:
+
+```markdown
+https://keptn.sh/stable/docs/installation/
+```
+
+To cross-reference this section from a file in the `guides` section
+(or other file at that level),
+use the relative file to the directory
+and specify the `index.md` file for the section:
+
+```markdown
+Follow the instructions in the
+[Installation](installation/index.md)
+section.
+```

docs/docs/contribute/docs/source-file-structure.md

@@ -8,10 +8,51 @@ The source files for the Keptn documentation
 are stored in the same GitHub repository as the source code for the software.
 This page explains how the documentation source files are organized.
 
-> **Note** The structure of the documentation
-  and the source code for the documentation is evolving.
-  You may find small discrepancies between
-  what is documented here and what is currently implemented.
+## Specifying the doc structure
+
+The documentation builds are controlled by the
+[mkdocs.yml](https://github.com/keptn/lifecycle-toolkit/blob/main/mkdocs.yml)
+file in the root directory of the Keptn repository.
+The documentation structure is defined under the `nav` section.
+The following snippet illustrates how this is structured:
+
+```yaml
+...
+nav:
+  - Home:
+      - index.md
+  - Documentation:
+      - docs/index.md
+    ...
+      - Use Cases:
+          - docs/use-cases/index.md
+          - Day 2 Operations: docs/use-cases/day-2-operations.md
+          - Keptn + HorizontalPodAutoscaler: docs/use-cases/hpa.md
+          - Keptn for non-Kubernetes deployments: docs/use-cases/non-k8s.md
+   ...
+```
+
+* The first level of the `nav:` section defines the tabs in the header bar of the page.
+* All nested items define sub-pages and their child pages inside the tabs.
+* The `Documentation` item defines the "Documentation" tab.
+* Each subitem to `Documentation` is a section of the docs
+  as displayed in the left frame.
+* Under each section are the individual pages,
+  listed in the order they are displayed in the left frame.
+  Each page line shows the title of the page
+  that will be displayed in the left frame
+  and the path to the source file.
+
+    Note that the page title displayed in the main canvas
+    is defined by the value of the H1 header in the page source file.
+    When creating a new page or modifying the title,
+    it is important to ensure that the title in the page source
+    and the title in the `mkdocs.yml` file match.
+
+> **Note** After adding a new page to the `mkdocs.yml` file,
+> you must stop and restart your local doc build
+> (make docs-serve)
+> before the new page shows in your local build.
 
 ## Primary documentation set
 
@@ -22,28 +63,28 @@ the `docs/docs` directory in the repository.
 
 The subdirectories with content are:
 
-- `assets`: This folder is used to save assets such as code examples that are used throughout the documentation.
+* `assets`: This folder is used to save assets such as code examples that are used throughout the documentation.
   Many subfolders also contain an `assets` folder,
   usually containing graphics files (.png, .jpg, etc)
   to keep such files closer to the content where they are referenced.
-- `components`: Information about how the different subcomponents of Keptn work
-- `contribute`: Contains information on how to contribute software, tests, and documentation to Keptn
-- `core-concepts`: A brief overview of Keptn, its features and use cases, and its history
-- `getting-started`: Hands-on exercises that demonstrate the capabilities of Keptn
-- `guides`: Guides and how-to material about using Keptn features
-- `installation`: Requirements and instructions for installing and enabling Keptn
-- `migrate`: Information to help users who are migrating to Keptn from Keptn v1
-- `reference`: Reference pages for the CRDs and APIs that Keptn provides
-- `use-cases`: Examples and exercises of using Keptn in specific scenarios
+* `components`: Information about how the different subcomponents of Keptn work
+* `contribute`: Contains information on how to contribute software, tests, and documentation to Keptn
+* `core-concepts`: A brief overview of Keptn, its features and use cases, and its history
+* `getting-started`: Hands-on exercises that demonstrate the capabilities of Keptn
+* `guides`: Guides and how-to material about using Keptn features
+* `installation`: Requirements and instructions for installing and enabling Keptn
+* `migrate`: Information to help users who are migrating to Keptn from Keptn v1
+* `reference`: Reference pages for the CRDs and APIs that Keptn provides
+* `use-cases`: Examples and exercises of using Keptn in specific scenarios
 
 ### Working with reference pages
 
 The Keptn documentation includes two reference sections
 that document the Keptn APIs and CRDs.
 For background information, see:
 
-- [Kubernetes API Concepts](https://kubernetes.io/docs/reference/using-api/api-concepts/)
-- [Kubernetes API Reference](https://kubernetes.io/docs/reference/kubernetes-api/)
+* [Kubernetes API Concepts](https://kubernetes.io/docs/reference/using-api/api-concepts/)
+* [Kubernetes API Reference](https://kubernetes.io/docs/reference/kubernetes-api/)
 
 #### API Reference
 
@@ -56,9 +97,9 @@ Descriptive text for the APIs is authored in the source code itself.
 Each operator has its own API with different versions.
 The source locations are:
 
-- [Lifecycle API](https://github.com/keptn/lifecycle-toolkit/tree/main/lifecycle-operator/apis/lifecycle)
-- [Metrics API](https://github.com/keptn/lifecycle-toolkit/tree/main/metrics-operator/api)
-- [Options API](https://github.com/keptn/lifecycle-toolkit/tree/main/lifecycle-operator/apis/options)
+* [Lifecycle API](https://github.com/keptn/lifecycle-toolkit/tree/main/lifecycle-operator/apis/lifecycle)
+* [Metrics API](https://github.com/keptn/lifecycle-toolkit/tree/main/metrics-operator/api)
+* [Options API](https://github.com/keptn/lifecycle-toolkit/tree/main/lifecycle-operator/apis/options)
 
 The text is coded in a limited form of markdown.
 
@@ -96,12 +137,12 @@ is stored under the `docs/contribute` directory.
 
 The subdirectories of the contribution guide are:
 
-- **general** (General information):
+* **general** (General information):
   Information that is applicable to all contributors,
   whether contributing software or documentation
-- **software** (Software contributions):
+* **software** (Software contributions):
   Information that is specific to software contributions
-- **docs** (Documentation contributions):
+* **docs** (Documentation contributions):
   Information that is specific to documentation contributions
 
 We also have *CONTRIBUTING.md* files located in the
@@ -134,9 +175,9 @@ of the `mkdocs.yml` file.
 Each subdirectory contains topical subdirectories for each chapter in that section.
 Each topical subdirectory may contain:
 
-- An *index.md* file that has the text for the section.
+* An *index.md* file that has the text for the section.
   If this is a subdirectory that contains subdirectories for other pages,
   the *index.md* file
   contains introductory content for the section.
-- An *assets* subdirectory where graphical files for that topic are stored.
+* An *assets* subdirectory where graphical files for that topic are stored.
   No *assets* subdirectory is present if the topic has no graphics.

mkdocs.yml

@@ -218,6 +218,7 @@ nav:
           - Build Documentation Locally: docs/contribute/docs/local-building.md
           - Linter Requirements: docs/contribute/docs/linter-requirements.md
           - Source File Structure: docs/contribute/docs/source-file-structure.md
+          - Coding the docs: docs/contribute/docs/code-docs.md
           - Spell Checker: docs/contribute/docs/spell-check.md
           - Published Doc Structure: docs/contribute/docs/publish.md
           - Word list: docs/contribute/docs/word-list.md