Replace the TOC menu in Docs, add a menu to Tutorials

pulumi · Oct 12, 2024 · 8048d0d · 8048d0d
1 parent 733908e
commit 8048d0d
Show file tree

Hide file tree

Showing 24 changed files with 257 additions and 53 deletions.
diff --git a/assets/css/bundle.css b/assets/css/bundle.css
diff --git a/assets/js/bundle.js b/assets/js/bundle.js
diff --git a/content/docs/iac/get-started/aws/begin.md b/content/docs/iac/get-started/aws/begin.md
@@ -18,7 +18,7 @@ aliases:
 
 Before you get started using Pulumi, let's run through a few quick steps to ensure your environment is set up correctly.
 
-### Install Pulumi
+## Install Pulumi
 
 {{< install-pulumi >}}
 {{% notes "info" %}}
@@ -28,9 +28,9 @@ All Windows examples in this tutorial assume you are running in PowerShell.
 
 Next, install the required language runtime, if you have not already.
 
-### Install Language Runtime
+## Install Language Runtime
 
-#### Choose Your Language
+### Choose Your Language
 
 {{< chooser language "javascript,typescript,python,go,csharp,java,yaml" / >}}
 
@@ -58,7 +58,7 @@ Next, install the required language runtime, if you have not already.
 {{< install-yaml >}}
 {{% /choosable %}}
 
-### Configure Pulumi to access your AWS account
+## Configure Pulumi to access your AWS account
 
 Pulumi requires cloud credentials to manage and provision resources. You must use an IAM user account that has **programmatic access** with rights to deploy and manage resources handled through Pulumi.
 

diff --git a/content/docs/iac/get-started/azure/begin.md b/content/docs/iac/get-started/azure/begin.md
@@ -18,7 +18,7 @@ aliases:
 
 Before you get started using Pulumi, let's run through a few quick steps to ensure your environment is set up correctly.
 
-### Install Pulumi
+## Install Pulumi
 
 {{< install-pulumi >}}
 {{% notes "info" %}}
@@ -28,9 +28,9 @@ All Windows examples in this tutorial assume you are running in PowerShell.
 
 Next, install the required language runtime, if you have not already.
 
-### Install Language Runtime
+## Install Language Runtime
 
-#### Choose Your Language
+### Choose Your Language
 
 {{< chooser language "typescript,python,go,csharp,java,yaml" / >}}
 
@@ -60,7 +60,7 @@ Next, install the required language runtime, if you have not already.
 
 Finally, configure Pulumi with Microsoft Azure.
 
-### Configure Pulumi to access your Microsoft Azure account
+## Configure Pulumi to access your Microsoft Azure account
 
 Pulumi requires cloud credentials to manage and provision resources. Pulumi can authenticate to Azure using a user account or service principal that has **Programmatic access** with rights to deploy and manage your Azure resources.
 

diff --git a/content/docs/iac/get-started/gcp/begin.md b/content/docs/iac/get-started/gcp/begin.md
@@ -18,7 +18,7 @@ aliases:
 
 Before you get started using Pulumi, let's run through a few quick steps to ensure your environment is set up correctly.
 
-### Install Pulumi
+## Install Pulumi
 
 {{< install-pulumi >}}
 {{% notes "info" %}}
@@ -28,9 +28,9 @@ All Windows examples in this tutorial assume you are running in PowerShell.
 
 Next, install the required language runtime, if you have not already.
 
-### Install Language Runtime
+## Install Language Runtime
 
-#### Choose Your Language
+### Choose Your Language
 
 {{< chooser language "javascript,typescript,python,go,csharp,java,yaml" / >}}
 
@@ -60,7 +60,7 @@ Next, install the required language runtime, if you have not already.
 
 Finally, configure Pulumi with Google Cloud.
 
-### Configure Pulumi to access your Google Cloud account
+## Configure Pulumi to access your Google Cloud account
 
 Pulumi requires cloud credentials to manage and provision resources. You must use an IAM user or service account that has **Programmatic access** with rights to deploy and manage your Google Cloud resources.
 

diff --git a/layouts/docs/list.html b/layouts/docs/list.html
@@ -3,7 +3,7 @@
         {{ if not .Params.noleftnav }}
         <div class="docs-main-nav-toggle-wrapper">
             <div class="docs-main-nav-wrapper">
-                <div id="docs-main-nav" class="docs-main-nav">
+                <div id="docs-main-nav" class="docs-main-nav sticky top-10">
                     {{ partial "docs/menu.html" (dict "page" .) }}
                 </div>
             </div>
@@ -44,8 +44,8 @@ <h1>{{ .Title }}</h1>
                 </section>
             </div>
             {{ if not .Params.norightnav }}
-            <div class="docs-table-of-contents docs-toc-desktop">
-                {{ partial "docs/table-of-contents.html" . }}
+            <div class="docs-toc mx-4 sticky top-10 h-full">
+                {{ partial "docs/toc.html" . }}
 
                 {{ partial "docs/feedback.html" . }}
 

diff --git a/layouts/docs/single.html b/layouts/docs/single.html
@@ -2,7 +2,7 @@
     <div class="docs-list-main">
         <div class="docs-main-nav-toggle-wrapper">
             <div class="docs-main-nav-wrapper">
-                <div id="docs-main-nav" class="docs-main-nav">
+                <div id="docs-main-nav" class="docs-main-nav sticky top-10">
                     {{ partial "docs/menu.html" (dict "page" .) }}
                 </div>
             </div>
@@ -42,8 +42,8 @@ <h1>{{ .Title }}</h1>
                 </section>
             </div>
 
-            <div class="docs-table-of-contents docs-toc-desktop">
-                {{ partial "docs/table-of-contents.html" . }}
+            <div class="docs-toc mx-4 sticky top-10 h-full">
+                {{ partial "docs/toc.html" . }}
 
                 {{ partial "docs/feedback.html" . }}
 

diff --git a/layouts/partials/docs/feedback.html b/layouts/partials/docs/feedback.html
@@ -1,5 +1,5 @@
-<div id="docsFeedbackContainer" class="hidden mt-4 border-t border-gray-300 pl-2 text-xs text-gray-600">
-    <div id="feedbackButtons">
+<div id="docsFeedbackContainer" class="hidden mt-8 border-t border-gray-200 pl-2 text-xs text-gray-600">
+    <div id="feedbackButtons" class="my-8">
         <p class="my-4">Was this page helpful?</p>
         <div class="flex items-center">
             <a id="docsFeedbackYes" data-track="feedback-yes" class="flex items-center cursor-pointer hover:text-gray-700">

diff --git a/layouts/partials/docs/table-of-contents.html b/layouts/partials/docs/table-of-contents.html
@@ -26,24 +26,7 @@ <h2 class="no-anchor">On this page</h2>
                 </label>
                 <div class="accordion-content flex">
                     <div class="content">
-                        <ul class="table-of-contents-list">
-                            {{/* This will be populated dynamically with all H2s and H3s on the page; see ts/misc.ts */}}
-                        </ul>
-                        {{ if strings.Contains $.Page.Permalink "registry/packages" }}
-                            {{ $path := (split .Page.Params.title_tag ".") }}
-                            {{- if eq (len $path) 3 -}}
-                                {{ $packageName := index $path 0 }}
-                                {{ $moduleName := index $path 1 }}
-                                {{ $resourceName := index $path 2 }}
-                                <div class="mt-6">
-                                    <pulumi-resource-links
-                                        package-name="{{ $packageName }}"
-                                        module-name="{{ $moduleName }}"
-                                        resource-name="{{ $resourceName }}"
-                                    ></pulumi-resource-links>
-                                </div>
-                            {{ end }}
-                        {{ end }}
+                        <pulumi-docs-toc></pulumi-docs-toc>
                     </div>
                 </div>
             </div>

diff --git a/layouts/partials/docs/toc.html b/layouts/partials/docs/toc.html
@@ -0,0 +1,6 @@
+<div class="hidden lg:block">
+    <div class="mt-8 mb-4 py-0">
+        <span class="text-xs font-bold text-gray-700">On this page</span>
+    </div>
+    <pulumi-docs-toc></pulumi-docs-toc>
+</div>
diff --git a/layouts/partials/tutorials/feedback.html b/layouts/partials/tutorials/feedback.html
@@ -1,5 +1,5 @@
-<div id="docsFeedbackContainer" class="hidden pl-2 text-xs text-gray-600">
-    <div id="feedbackButtons">
+<div id="docsFeedbackContainer" class="hidden mt-8 border-t border-gray-200 text-xs text-gray-600">
+    <div id="feedbackButtons" class="my-8">
         <p class="my-4">Was this page helpful?</p>
         <div class="flex items-center">
             <a id="docsFeedbackYes" data-track="feedback-yes" class="flex items-center cursor-pointer hover:text-gray-700">

diff --git a/layouts/partials/tutorials/toc.html b/layouts/partials/tutorials/toc.html
@@ -0,0 +1,6 @@
+<div class="hidden lg:block">
+    <div class="mt-8 mb-4 py-0">
+        <span class="text-xs font-bold text-gray-700">On this page</span>
+    </div>
+    <pulumi-docs-toc></pulumi-docs-toc>
+</div>
diff --git a/layouts/tutorials/module.html b/layouts/tutorials/module.html
@@ -83,7 +83,8 @@ <h2>Topics</h2>
                 </div>
             </div>
         </div>
-        <div class="sticky top-10 pt-8 max-h-75 xl:w-2/12 hidden xl:block">
+        <div class="sticky top-12 max-h-75 xl:w-2/12 hidden xl:block xl:pr-4">
+            {{ partial "tutorials/toc.html" }}
             {{ partial "tutorials/feedback.html" . }}
             {{ partial "tutorials/right-nav-ad.html" }}
         </div>

diff --git a/layouts/tutorials/single.html b/layouts/tutorials/single.html
@@ -65,7 +65,8 @@ <h2 class="mb-4">Prerequisites:</h2>
                 </div>
             </div>
         </div>
-        <div class="sticky top-10 pt-8 max-h-75 xl:w-2/12 hidden xl:block">
+        <div class="sticky top-12 max-h-75 xl:w-2/12 hidden xl:block xl:pr-4">
+            {{ partial "tutorials/toc.html" }}
             {{ partial "tutorials/feedback.html" . }}
             {{ partial "tutorials/right-nav-ad.html" }}
         </div>

diff --git a/layouts/tutorials/topic.html b/layouts/tutorials/topic.html
@@ -26,7 +26,8 @@ <h1>{{ .Title }}</h1>
                 </div>
             </div>
         </div>
-        <div class="sticky top-10 pt-8 max-h-75 xl:w-2/12 hidden xl:block">
+        <div class="sticky top-12 max-h-75 xl:w-2/12 hidden xl:block xl:pr-4">
+            {{ partial "tutorials/toc.html" }}
             {{ partial "tutorials/feedback.html" . }}
             {{ partial "tutorials/right-nav-ad.html" }}
         </div>

diff --git a/theme/src/scss/components/_docs-toc.scss b/theme/src/scss/components/_docs-toc.scss
@@ -0,0 +1,32 @@
+pulumi-docs-toc {
+    @apply sticky top-0;
+
+    ul {
+        li {
+            &.toc-level-h3 {
+                @apply ml-4;
+            }
+
+            a {
+                @apply text-gray-800;
+
+                &:hover {
+                    @apply text-blue-800;
+                    text-decoration: none !important;
+                }
+            }
+
+            &.active {
+                a {
+                    @apply text-blue-800;
+                }
+            }
+        }
+
+        // Select the first item in the list. (There will often be multiple --
+        // e.g., when more than one heading is visible on the page.
+        :nth-child(1 of li.active) {
+            @apply font-semibold;
+        }
+    }
+}
diff --git a/theme/src/scss/docs/_docs-main.scss b/theme/src/scss/docs/_docs-main.scss
@@ -141,9 +141,7 @@ body.section-registry {
             flex-basis: 32px;
             overflow-y: auto;
             height: calc(100vh - 38px);
-            position: sticky;
             left: 0;
-            top: 0;
 
             nav.main-nav div:first-of-type {
                 margin-top: 0;
@@ -730,6 +728,10 @@ body.section-registry {
         input:checked ~ label.hide {
             margin-bottom: 24px;
             display: flex;
+
+            .icon {
+                rotate: 180deg;
+            }
         }
 
         .heading:hover {

diff --git a/theme/src/scss/main.scss b/theme/src/scss/main.scss
@@ -73,6 +73,7 @@
 @import "components/choosable";
 @import "components/convert";
 @import "components/docs-nav";
+@import "components/docs-toc";
 @import "components/filter-select";
 @import "components/greenhouse-jobs-list";
 @import "components/install";
@@ -271,7 +272,7 @@ main {
     }
 }
 
-$sitenav-height: 90px;
+$sitenav-height: 58px;
 
 // A 16px offset makes it easier to position elements below the nav when it's pinned.
 $sitenav-offset: calc($sitenav-height + 16px);

diff --git a/theme/stencil/src/components.d.ts b/theme/stencil/src/components.d.ts
@@ -106,6 +106,8 @@ export namespace Components {
     interface PulumiDocsNav {
         "expandedMenuIDs": string;
     }
+    interface PulumiDocsToc {
+    }
     interface PulumiExample {
     }
     interface PulumiExamples {
@@ -320,6 +322,12 @@ declare global {
         prototype: HTMLPulumiDocsNavElement;
         new (): HTMLPulumiDocsNavElement;
     };
+    interface HTMLPulumiDocsTocElement extends Components.PulumiDocsToc, HTMLStencilElement {
+    }
+    var HTMLPulumiDocsTocElement: {
+        prototype: HTMLPulumiDocsTocElement;
+        new (): HTMLPulumiDocsTocElement;
+    };
     interface HTMLPulumiExampleElement extends Components.PulumiExample, HTMLStencilElement {
     }
     var HTMLPulumiExampleElement: {
@@ -478,6 +486,7 @@ declare global {
         "pulumi-datetime": HTMLPulumiDatetimeElement;
         "pulumi-developer-quotes": HTMLPulumiDeveloperQuotesElement;
         "pulumi-docs-nav": HTMLPulumiDocsNavElement;
+        "pulumi-docs-toc": HTMLPulumiDocsTocElement;
         "pulumi-example": HTMLPulumiExampleElement;
         "pulumi-examples": HTMLPulumiExamplesElement;
         "pulumi-filter-select": HTMLPulumiFilterSelectElement;
@@ -598,6 +607,8 @@ declare namespace LocalJSX {
     interface PulumiDocsNav {
         "expandedMenuIDs"?: string;
     }
+    interface PulumiDocsToc {
+    }
     interface PulumiExample {
     }
     interface PulumiExamples {
@@ -711,6 +722,7 @@ declare namespace LocalJSX {
         "pulumi-datetime": PulumiDatetime;
         "pulumi-developer-quotes": PulumiDeveloperQuotes;
         "pulumi-docs-nav": PulumiDocsNav;
+        "pulumi-docs-toc": PulumiDocsToc;
         "pulumi-example": PulumiExample;
         "pulumi-examples": PulumiExamples;
         "pulumi-filter-select": PulumiFilterSelect;
@@ -759,6 +771,7 @@ declare module "@stencil/core" {
             "pulumi-datetime": LocalJSX.PulumiDatetime & JSXBase.HTMLAttributes<HTMLPulumiDatetimeElement>;
             "pulumi-developer-quotes": LocalJSX.PulumiDeveloperQuotes & JSXBase.HTMLAttributes<HTMLPulumiDeveloperQuotesElement>;
             "pulumi-docs-nav": LocalJSX.PulumiDocsNav & JSXBase.HTMLAttributes<HTMLPulumiDocsNavElement>;
+            "pulumi-docs-toc": LocalJSX.PulumiDocsToc & JSXBase.HTMLAttributes<HTMLPulumiDocsTocElement>;
             "pulumi-example": LocalJSX.PulumiExample & JSXBase.HTMLAttributes<HTMLPulumiExampleElement>;
             "pulumi-examples": LocalJSX.PulumiExamples & JSXBase.HTMLAttributes<HTMLPulumiExamplesElement>;
             "pulumi-filter-select": LocalJSX.PulumiFilterSelect & JSXBase.HTMLAttributes<HTMLPulumiFilterSelectElement>;

diff --git a/theme/stencil/src/components/docs-toc/docs-toc.scss b/theme/stencil/src/components/docs-toc/docs-toc.scss
@@ -0,0 +1,3 @@
+pulumi-docs-toc {
+    display: block;
+}