docs: add anchors to yaml paths (#8541)

* docs: add anchors to yaml paths * feat: add note about tooltip anchors and arrow to indicate that there is an action * docs: move tooltip tip to same box as cloud code tip
GoogleContainerTools · Aug 4, 2023 · 0da33e6 · 0da33e6
1 parent 2df4ccf
commit 0da33e6
Show file tree

Hide file tree

Showing 4 changed files with 88 additions and 30 deletions.
diff --git a/docs-v2/content/en/docs/references/yaml/_index.html b/docs-v2/content/en/docs/references/yaml/_index.html
@@ -8,7 +8,9 @@
 ---
 
 {{< alert title="💡 Tip" >}}
-The Cloud Code IDE extensions (see [install options]({{< relref "../../install/#managed-ide" >}})) provide authoring assistance for `skaffold.yaml` files in the form of schema based validation, diagnostics, quick documentation, code completions, and snippets, that can make it easier to create and edit these files. 
+The Cloud Code IDE extensions (see [install options]({{< relref "../../install/#managed-ide" >}})) provide authoring assistance for `skaffold.yaml` files in the form of schema based validation, diagnostics, quick documentation, code completions, and snippets, that can make it easier to create and edit these files.
+
+You can now navigate the `skaffold.yaml` reference from an inner element to its upper levels using the tooltip that appears on hover, clicking on the parent element you want to go: <div class="tooltip-img-continaer">![Tooltip with links to upper elements](/images/tooltip-click-note.png)</div>
 {{< /alert >}}
 
 <link href="https://fonts.googleapis.com/css?family=Roboto+Mono:400,700" rel="stylesheet">

diff --git a/docs-v2/content/en/docs/references/yaml/main.css b/docs-v2/content/en/docs/references/yaml/main.css
@@ -89,24 +89,17 @@ a.anchor{
     }
 }
 
-.stooltip {
+.stooltip__content {
     background-color: #555;
     border-radius: 5px;
-    color: #fff;
+    color: #FFF;
     display: inline-block;
     font-size: 9px;
     font-weight: 100;
-    left: 0;
-    opacity: 0;
     padding: 5px 6px;
-    position: absolute;
-    top: -15px;
-    transform: translateY(-50%);
-    transition: opacity 0.3s;
-    visibility: hidden;
 }
 
-.stooltip::before {
+.stooltip__content::before {
     background-color: #555;
     border-radius: 1px;
     bottom: -3px;
@@ -117,9 +110,43 @@ a.anchor{
     position: absolute;
     transform: rotate(45deg);
     width: 10px;
+    z-index: -1;
 }
 
-.stooltip__anchor:hover ~ .stooltip {
+.stooltip {
+    border-bottom: 10px solid transparent;
+    display: inline-block;
+    left: 0;
+    opacity: 0;
+    position: absolute;
+    top: -10px;
+    transform: translateY(-50%);
+    transition: opacity 0.3s;
+    visibility: hidden;
+}
+
+.stooltip__icon {
+    margin: 0 0 0 6px;
+}
+
+.key:hover > .stooltip {
     opacity: 1;
     visibility: visible;
+}
+
+.yaml-link {
+    color: #FFF;
+}
+
+.yaml-link:hover{
+    color: #72A1E5;
+}
+
+.yaml-link__separator {
+    cursor: default;
+}
+
+.tooltip-img-continaer {
+    margin: 10px 0 0;
+    max-width: 220px;
 }
diff --git a/docs-v2/content/en/docs/references/yaml/main.js b/docs-v2/content/en/docs/references/yaml/main.js
@@ -3,6 +3,18 @@ import { unsafeHTML } from 'https://unpkg.com/lit-html@1.1.2/directives/unsafe-h
 
 var version;
 let latest;
+
+class YamlLink {
+  constructor(url, label) {
+    this.url = `#${url}`;
+    this.label = label
+  }
+
+  render() {
+    return html`<a class="yaml-link" href="${this.url}">${this.label}</a>`;
+  }
+}
+
 (async function() {
   const versionParam = "?version=";
   const index = window.location.href.indexOf(versionParam);
@@ -31,15 +43,15 @@ let latest;
   const json = await response.json();
 
   render(html`
-    ${template(json.definitions, undefined, json.anyOf[0].$ref, 0, "", "")}
+    ${template(json.definitions, undefined, json.anyOf[0].$ref, 0, "", [])}
   `, table);
 
   if (location.hash) {
     table.querySelector(location.hash).scrollIntoView();
   }
 })();
 
-function* template(definitions, parentDefinition, ref, ident, parent, parentYamlPath) {
+function* template(definitions, parentDefinition, ref, ident, parent, parentLinks) {
   const name = ref.replace('#/definitions/', '');
   const allProperties = [];
   const seen = {};
@@ -63,9 +75,10 @@ function* template(definitions, parentDefinition, ref, ident, parent, parentYaml
   let index = -1;
   for (let [key, definition] of allProperties) {
     const path = parent.length == 0 ? key : `${parent}-${key}`;
-    const yamlPath = (definition.items && definition.items.$ref) ?
-        `${parentYamlPath}${key}[]`:
-        `${parentYamlPath}${key}`;
+    const propetyLabel = (definition.items && definition.items.$ref) ? `${key}[]`: `${key}`;
+    const yamlLink = new YamlLink(path, propetyLabel);
+    const pathLinks = [...parentLinks, yamlLink]
+    const renderedPath = getPathLinkList(pathLinks);
     index++;
 
     // Key
@@ -93,7 +106,7 @@ function* template(definitions, parentDefinition, ref, ident, parent, parentYaml
       yield html`
         <tr>
           <td>
-            <span class="${keyClass}" style="margin-left: ${ident * 20}px">${anchor(path, key)}:${tooltip(yamlPath)}</span>
+            <span class="${keyClass}" style="margin-left: ${ident * 20}px">${anchor(path, key)}:${tooltip(renderedPath)}</span>
             <span class="${valueClass}">${value}</span>
           </td>
           <td><span class="comment">#&nbsp;</span></td>
@@ -116,7 +129,7 @@ function* template(definitions, parentDefinition, ref, ident, parent, parentYaml
       yield html`
         <tr class="top">
           <td>
-            <span class="${keyClass}" style="margin-left: ${ident * 20}px">${anchor(path, key)}:${tooltip(yamlPath)}</span>
+            <span class="${keyClass}" style="margin-left: ${ident * 20}px">${anchor(path, key)}:${tooltip(renderedPath)}</span>
             <span class="${valueClass}">${value}</span>
           </td>
           <td class="comment">#&nbsp;</td>
@@ -131,7 +144,7 @@ function* template(definitions, parentDefinition, ref, ident, parent, parentYaml
       yield html`
         <tr class="top">
           <td>
-            <span class="${keyClass}" style="margin-left: ${ident * 20}px">${anchor(path, key)}:${tooltip(yamlPath)}</span>
+            <span class="${keyClass}" style="margin-left: ${ident * 20}px">${anchor(path, key)}:${tooltip(renderedPath)}</span>
             <span class="${valueClass}">${value}</span>
           </td>
           <td class="comment">#&nbsp;</td>
@@ -143,7 +156,7 @@ function* template(definitions, parentDefinition, ref, ident, parent, parentYaml
         <tr>
           <td>
             
-            <span class="${keyClass}" style="margin-left: ${(ident - 1) * 20}px">- ${anchor(path, key)}:${tooltip(yamlPath)}</span>
+            <span class="${keyClass}" style="margin-left: ${(ident - 1) * 20}px">- ${anchor(path, key)}:${tooltip(renderedPath)}</span>
             <span class="${valueClass}">${value}</span>
           </td>
           <td class="comment">#&nbsp;</td>
@@ -158,7 +171,7 @@ function* template(definitions, parentDefinition, ref, ident, parent, parentYaml
         <tr>
           <td>
           
-            <span class="${keyClass}" style="margin-left: ${ident * 20}px">${anchor(path, key)}:${tooltip(yamlPath)}</span>
+            <span class="${keyClass}" style="margin-left: ${ident * 20}px">${anchor(path, key)}:${tooltip(renderedPath)}</span>
           </td>
           <td class="comment">#&nbsp;</td>
           <td class="comment" rowspan="${1 + values.length}">
@@ -184,7 +197,7 @@ function* template(definitions, parentDefinition, ref, ident, parent, parentYaml
       yield html`
         <tr>
           <td>
-            <span class="${keyClass}" style="margin-left: ${ident * 20}px">${anchor(path, key)}:${tooltip(yamlPath)}</span>
+            <span class="${keyClass}" style="margin-left: ${ident * 20}px">${anchor(path, key)}:${tooltip(renderedPath)}</span>
           </td>
           <td class="comment">#&nbsp;</td>
           <td class="comment" rowspan="${1 + Object.keys(values).length}">
@@ -201,7 +214,7 @@ function* template(definitions, parentDefinition, ref, ident, parent, parentYaml
           <tr>
             <td>
               
-              <span class="key" style="margin-left: ${(ident + 1) * 20}px">${k}:${tooltip(yamlPath)}<span class="${valueClass}">${v}</span>
+              <span class="key" style="margin-left: ${(ident + 1) * 20}px">${k}:${tooltip(renderedPath)}<span class="${valueClass}">${v}</span>
               </span>
             </td>
             <td class="comment">#&nbsp;</td>
@@ -212,7 +225,7 @@ function* template(definitions, parentDefinition, ref, ident, parent, parentYaml
       yield html`
         <tr>
           <td>
-            <span class="${keyClass}" style="margin-left: ${ident * 20}px">${anchor(path, key)}:${tooltip(yamlPath)}</span>
+            <span class="${keyClass}" style="margin-left: ${ident * 20}px">${anchor(path, key)}:${tooltip(renderedPath)}</span>
             <span class="${valueClass}">${value}</span>
             <span class="${keyClass}">${getLatest(key === 'apiVersion' && latest === value)}</span>
           </td>
@@ -225,7 +238,7 @@ function* template(definitions, parentDefinition, ref, ident, parent, parentYaml
     // This definition references another definition
     if (definition.$ref) {
       yield html`
-        ${template(definitions, definition, definition.$ref, ident + 1, path, `${yamlPath}.`)}
+        ${template(definitions, definition, definition.$ref, ident + 1, path, pathLinks)}
       `;
     }
 
@@ -236,7 +249,7 @@ function* template(definitions, parentDefinition, ref, ident, parent, parentYaml
         yield html ``;
       } else {
         yield html`
-          ${template(definitions, definition, definition.items.$ref, ident + 1, path, `${yamlPath}.`)}
+          ${template(definitions, definition, definition.items.$ref, ident + 1, path, pathLinks)}
         `;
       }
     }
@@ -248,9 +261,25 @@ function getLatest(isLatest) {
 }
 
 function anchor(path, label) {
-    return html`<a class="anchor" id="${path}"></a><a class="key stooltip__anchor" href="#${path}">${label}</a>`
+    return html`<a class="anchor" id="${path}"></a><a class="key stooltip__anchor" href="#${path}">${label}</a>`;
 }
 
-function tooltip(text) {
-  return html`<span class="stooltip">${text}</span>`;
+function tooltip(content) {
+  return html`<span class="stooltip"><span class="stooltip__content">${content}<span class="stooltip__icon"><i class="fas fa-arrow-left"></i></span></span>`;
+}
+
+function getPathLinkList(yamlLinks) {
+  return html`${joinTemplates(yamlLinks.map((yamlLink) => yamlLink.render()), html`<span class="yaml-link__separator">.</span>`)}`;
+}
+
+function joinTemplates(templates=[html``], separator=html` `) {
+  const joinedTemplates = [];
+
+  for (const template of templates) {
+    joinedTemplates.push(template);
+    joinedTemplates.push(separator);
+  }
+  joinedTemplates.pop();
+
+  return joinedTemplates;
 }
diff --git a/docs-v2/static/images/tooltip-click-note.png b/docs-v2/static/images/tooltip-click-note.png