docs(ui): full copy-edit of title & description page (#12582)

Signed-off-by: Anton Gilgur <agilgur5@gmail.com>

.spelling

@@ -234,7 +234,9 @@ v3.3
 v3.3.
 v3.4
 v3.4.
+v3.4.4
 v3.5
+v3.6
 validator
 vendored
 versioned

docs/fields.md

@@ -331,7 +331,7 @@ Workflow is the definition of a workflow resource
 
 - [`timeouts-workflow.yaml`](https://github.com/argoproj/argo-workflows/blob/main/examples/timeouts-workflow.yaml)
 
-- [`title-and-descriptin-with-markdown.yaml`](https://github.com/argoproj/argo-workflows/blob/main/examples/title-and-descriptin-with-markdown.yaml)
+- [`title-and-description-with-markdown.yaml`](https://github.com/argoproj/argo-workflows/blob/main/examples/title-and-description-with-markdown.yaml)
 
 - [`volumes-emptydir.yaml`](https://github.com/argoproj/argo-workflows/blob/main/examples/volumes-emptydir.yaml)
 
@@ -755,7 +755,7 @@ WorkflowSpec is the specification of a Workflow.
 
 - [`timeouts-workflow.yaml`](https://github.com/argoproj/argo-workflows/blob/main/examples/timeouts-workflow.yaml)
 
-- [`title-and-descriptin-with-markdown.yaml`](https://github.com/argoproj/argo-workflows/blob/main/examples/title-and-descriptin-with-markdown.yaml)
+- [`title-and-description-with-markdown.yaml`](https://github.com/argoproj/argo-workflows/blob/main/examples/title-and-description-with-markdown.yaml)
 
 - [`volumes-emptydir.yaml`](https://github.com/argoproj/argo-workflows/blob/main/examples/volumes-emptydir.yaml)
 
@@ -1194,7 +1194,7 @@ CronWorkflowSpec is the specification of a CronWorkflow
 
 - [`timeouts-workflow.yaml`](https://github.com/argoproj/argo-workflows/blob/main/examples/timeouts-workflow.yaml)
 
-- [`title-and-descriptin-with-markdown.yaml`](https://github.com/argoproj/argo-workflows/blob/main/examples/title-and-descriptin-with-markdown.yaml)
+- [`title-and-description-with-markdown.yaml`](https://github.com/argoproj/argo-workflows/blob/main/examples/title-and-description-with-markdown.yaml)
 
 - [`volumes-emptydir.yaml`](https://github.com/argoproj/argo-workflows/blob/main/examples/volumes-emptydir.yaml)
 
@@ -3682,7 +3682,7 @@ MetricLabel is a single label for a prometheus metric
 
 - [`steps-inline-workflow.yaml`](https://github.com/argoproj/argo-workflows/blob/main/examples/steps-inline-workflow.yaml)
 
-- [`title-and-descriptin-with-markdown.yaml`](https://github.com/argoproj/argo-workflows/blob/main/examples/title-and-descriptin-with-markdown.yaml)
+- [`title-and-description-with-markdown.yaml`](https://github.com/argoproj/argo-workflows/blob/main/examples/title-and-description-with-markdown.yaml)
 </details>
 
 ### Fields
@@ -4849,7 +4849,7 @@ ObjectMeta is metadata that all persisted resources must have, which includes al
 
 - [`timeouts-workflow.yaml`](https://github.com/argoproj/argo-workflows/blob/main/examples/timeouts-workflow.yaml)
 
-- [`title-and-descriptin-with-markdown.yaml`](https://github.com/argoproj/argo-workflows/blob/main/examples/title-and-descriptin-with-markdown.yaml)
+- [`title-and-description-with-markdown.yaml`](https://github.com/argoproj/argo-workflows/blob/main/examples/title-and-description-with-markdown.yaml)
 
 - [`volumes-emptydir.yaml`](https://github.com/argoproj/argo-workflows/blob/main/examples/volumes-emptydir.yaml)
 
@@ -5451,7 +5451,7 @@ A single application container that you want to run within a pod.
 
 - [`timeouts-workflow.yaml`](https://github.com/argoproj/argo-workflows/blob/main/examples/timeouts-workflow.yaml)
 
-- [`title-and-descriptin-with-markdown.yaml`](https://github.com/argoproj/argo-workflows/blob/main/examples/title-and-descriptin-with-markdown.yaml)
+- [`title-and-description-with-markdown.yaml`](https://github.com/argoproj/argo-workflows/blob/main/examples/title-and-description-with-markdown.yaml)
 
 - [`volumes-emptydir.yaml`](https://github.com/argoproj/argo-workflows/blob/main/examples/volumes-emptydir.yaml)
 
@@ -6180,7 +6180,7 @@ PersistentVolumeClaimSpec describes the common attributes of storage devices and
 
 - [`timeouts-workflow.yaml`](https://github.com/argoproj/argo-workflows/blob/main/examples/timeouts-workflow.yaml)
 
-- [`title-and-descriptin-with-markdown.yaml`](https://github.com/argoproj/argo-workflows/blob/main/examples/title-and-descriptin-with-markdown.yaml)
+- [`title-and-description-with-markdown.yaml`](https://github.com/argoproj/argo-workflows/blob/main/examples/title-and-description-with-markdown.yaml)
 
 - [`volumes-emptydir.yaml`](https://github.com/argoproj/argo-workflows/blob/main/examples/volumes-emptydir.yaml)
 

docs/title-and-description.md

@@ -1,25 +1,79 @@
 # Title and Description
 
-If you add specific title and description annotations to your workflow they will show up on the workflow lists. It will also work with markdown.
+> v3.4.4 and after
+
+You can add the `workflows.argoproj.io/title` and `workflows.argoproj.io/description` annotations to a Workflow to display in the workflow lists:
 
 ```yaml
 apiVersion: argoproj.io/v1alpha1
 kind: Workflow
 metadata:
   name: my-wf
   annotations:
-    workflows.argoproj.io/title: '**Build and test**'
+    workflows.argoproj.io/title: 'Build and test' # defaults to `metadata.name` if not specified
+    workflows.argoproj.io/description: 'SuperDuperProject PR #6529: Implement frobbing (aff39ee)'
+```
+
+The above manifest will render as a row like the below image:
+![Title and Description Example](assets/workflow-title-and-description.png)
+
+## Embedded Markdown
+
+> v3.6 and after
+
+You can also embed [Markdown](https://www.markdownguide.org/basic-syntax/) into the annotations:
+
+```yaml
+apiVersion: argoproj.io/v1alpha1
+kind: Workflow
+metadata:
+  name: my-wf
+  annotations:
+    workflows.argoproj.io/title: '**Build and test**' # defaults to `metadata.name` if not specified
     workflows.argoproj.io/description: '`SuperDuperProject` PR #6529: Implement frobbing (aff39ee)'
 ```
 
-Examples by row:
+The above manifest will render as a row like the below image:
+![Markdown Example](assets/workflow-title-and-description-markdown.png)
 
-- markdown title, markdown description using [`remark-gfm`](https://github.com/remarkjs/remark-gfm) to auto turn URLs into links
-- no title or description, defaults to `workflow.metadata.name`
-- markdown title, no description
-- no title, markdown description (title defaults to `workflow.metadata.name`)
-- markdown title, markdown description (description includes URL that auto turns into anchor
-- markdown title, markdown description, includes markdown URL
-- markdown title, markdown description, includes markdown URL (pr link goes to `github.com`)
+Below are a few more examples:
+
+```yaml
+# 1. markdown title, markdown description using [`remark-gfm`](https://github.com/remarkjs/remark-gfm) to convert URLs into anchor links
+metadata:
+  annotations:
+    workflows.argoproj.io/title: '**feat: Allow markdown in workflow title and description. Fixes #10126**'
+    workflows.argoproj.io/description: https://github.com/argoproj/argo-workflows/pull/10553
+
+# 2. no title (defaults to `metadata.name`), no description
+metadata:
+  name: wonderful-poochenheimer
+
+# 3. markdown titile, no description
+metadata:
+  annotations:
+    workflows.argoproj.io/title: '**Build and test and test**'
+
+# 4. no title (defaults to `metadata.name`), markdown description
+metadata:
+  name: delightful-python
+  annotations:
+    workflows.argoproj.io/description: '`SuperDuperProject` PR #6529: Implement frobbing (aff39ee)'
+
+# 5. markdown title, multi-line markdown description with URL converted into an anchor link
+metadata:
+  annotations:
+    workflows.argoproj.io/title: '**Test Title**'
+    workflows.argoproj.io/description: |
+      `This is a simple hello world example.`
+      You can also run it in Python: https://couler-proj.github.io/couler/examples/#hello-world
+
+# 6. markdown title, markdown description with a markdown link
+metadata:
+  annotations:
+    workflows.argoproj.io/title: '**Build and test**'
+    workflows.argoproj.io/description: '`SuperDuperProject` PR [#6529](https://github.com): Implement frobbing (aff39ee)'
+```
 
-![Workflow Title And Description](assets/workflow-title-and-description.png)
+The above examples will render as rows like the below image:
+![More Markdown Examples](assets/workflow-title-and-description-markdown-complex.png)

examples/title-and-descriptin-with-markdown.yaml → examples/title-and-description-with-markdown.yaml

@@ -5,10 +5,12 @@ metadata:
   labels:
     workflows.argoproj.io/archive-strategy: "false"
   annotations:
-    workflows.argoproj.io/title: "**Test Title**"
+    # both annotations are available since v3.4.4
+    # embedded markdown is available since v3.6
+    workflows.argoproj.io/title: "**Test Title**" # defaults to `metadata.name` if not specified
     workflows.argoproj.io/description: |
       `This is a simple hello world example.`
-      You can also run it in Python: https://couler-proj.github.io/couler/examples/#hello-world
+      This is an embedded link to the docs: https://argo-workflows.readthedocs.io/en/latest/title-and-description/
 spec:
   entrypoint: whalesay
   templates: