From 991109b81245a361752e8dcb00936281aa416f29 Mon Sep 17 00:00:00 2001
From: Sam Richard <snugug@google.com>
Date: Fri, 23 Aug 2024 14:36:44 -0400
Subject: [PATCH] =?UTF-8?q?=F0=9F=90=9B(site)=20Include=20tutorial=20links?=
 =?UTF-8?q?=20and=20software=20in=20docs=20(#774)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

* Add tutorials to section nav

* Add software to documentation pages

---------

Co-authored-by: Sam Richard <samrichard@google.com>
---
 site/lib/documentation.ts                  | 22 ++++++++++++++++--
 site/src/components/SectionNav.svelte      | 27 +++++++++++++++++++++-
 site/src/layouts/views/Documentation.astro | 16 ++++++++++---
 site/src/pages/[lang]/[landing].astro      |  5 +++-
 4 files changed, 63 insertions(+), 7 deletions(-)

diff --git a/site/lib/documentation.ts b/site/lib/documentation.ts
index 23fecc2e..e07c0080 100644
--- a/site/lib/documentation.ts
+++ b/site/lib/documentation.ts
@@ -1,11 +1,11 @@
 import type { Tag } from '$types/sanity';
-import { documentation, landings } from '$lib/sanity';
+import { documentation, landings, tutorials } from '$lib/sanity';
 
 /**
  * Build documentation sections
  * @param {Tag} category
  * @param {string} lang
- * @return {object}
+ * @return {object[]}
  */
 export function buildSection(category: Tag, lang: string = 'en') {
   const sections = documentation
@@ -29,6 +29,23 @@ export function buildSection(category: Tag, lang: string = 'en') {
   return [landing, sections].flat();
 }
 
+/**
+ * Build documentation tutorials
+ * @param {Tag} category
+ * @param {string} lang
+ * @return {object[] | null}
+ */
+export function buildTutorials(category: Tag, lang: string = 'en') {
+  const tuts = tutorials
+    .filter((l) => l._lang === lang)
+    .filter((l) => l.category.slug === category.slug)
+    .map((l) => ({
+      title: l.title,
+      href: l._path,
+    }));
+  return tuts.length > 0 ? tuts : null;
+}
+
 /**
  * Build documentation topics
  * @param {string[]} paths Array of paths
@@ -37,6 +54,7 @@ export function buildSection(category: Tag, lang: string = 'en') {
 export function buildTopics(paths: string[]) {
   return documentation
     .filter((d) => paths.includes(d._path))
+    .sort((a, b) => a.title.localeCompare(b.title))
     .sort((a, b) => a.weight - b.weight)
     .map((d) => ({
       title: d.title,
diff --git a/site/src/components/SectionNav.svelte b/site/src/components/SectionNav.svelte
index 6a61bcc1..49b947e2 100644
--- a/site/src/components/SectionNav.svelte
+++ b/site/src/components/SectionNav.svelte
@@ -6,6 +6,8 @@
 
   export let title: string;
   export let links: Array<Link>;
+  export let tutorials: Array<Link>;
+  export let ttitle: string;
   export let active: string;
 
   const buttonTitle = 'Open section navigation';
@@ -20,7 +22,9 @@
 >
   <div class="section-nav--header">
     <div class="section-nav--text">
-      <p id="section-nav--title" class="section-nav--title type--h5">{title}</p>
+      <h2 id="section-nav--title" class="section-nav--title type--h5">
+        {title}
+      </h2>
       <svg role="img" aria-hidden="true" class="icon section-nav--expand">
         <use href="/images/icons/sprite.svg#expand-more" />
       </svg>
@@ -43,6 +47,20 @@
         </li>
       {/each}
     </ul>
+    {#if tutorials}
+      <h3 class="ttitle type--h6">{ttitle}</h3>
+      <ul class="tutorials">
+        {#each tutorials as link}
+          <li class="section-nav--item">
+            <a
+              href={link.href}
+              data-active={active === link.href ? true : null}
+              class="section-nav--link type--secondary-nav">{link.title}</a
+            >
+          </li>
+        {/each}
+      </ul>
+    {/if}
   </div>
 </nav>
 
@@ -165,4 +183,11 @@
       }
     }
   }
+
+  .ttitle {
+    padding-inline: var(--inline);
+    padding-block: math.div($block, 3) * 2;
+    margin: 0;
+    line-height: 1;
+  }
 </style>
diff --git a/site/src/layouts/views/Documentation.astro b/site/src/layouts/views/Documentation.astro
index b4dbc7bc..b5e1cfc9 100644
--- a/site/src/layouts/views/Documentation.astro
+++ b/site/src/layouts/views/Documentation.astro
@@ -1,11 +1,13 @@
 ---
 import Doc from '$layouts/doc.astro';
-import { buildSection } from '$lib/documentation';
+import { buildSection, buildTutorials } from '$lib/documentation';
 import { buildTOC } from '$lib/portabletext';
 
 import TOC from '$components/TOC.svelte';
 import SectionNav from '$components/SectionNav.svelte';
 import Text from '$components/Text.astro';
+import Software from '$components/Software.svelte';
+
 import type { Documentation, Microcopy } from '$types/sanity';
 
 export interface Props {
@@ -16,6 +18,7 @@ export interface Props {
 const { doc, microcopy } = Astro.props;
 
 const section = buildSection(doc.category, doc._lang);
+const tutorials = buildTutorials(doc.category, doc._lang);
 const toc = buildTOC(doc.body);
 ---
 
@@ -30,13 +33,20 @@ const toc = buildTOC(doc.body);
     active={doc._path}
     title={doc.category.title}
     links={section}
+    tutorials={tutorials}
+    ttitle="Tutorials"
     client:visible
     slot="subnav"
   />
   <!-- Main content area -->
   <Text body={doc.body} slot="content" />
   <!-- Extras sidebar -->
-  <Fragment slot="extras">
+  <div slot="extras">
+    {
+      doc.software && (
+        <Software software={doc.software} microcopy={microcopy.meta.tools} />
+      )
+    }
     {toc.length > 0 && <TOC toc={toc} client:idle title={microcopy.meta.toc} />}
-  </Fragment>
+  </div>
 </Doc>
diff --git a/site/src/pages/[lang]/[landing].astro b/site/src/pages/[lang]/[landing].astro
index 08f6899b..219f8126 100644
--- a/site/src/pages/[lang]/[landing].astro
+++ b/site/src/pages/[lang]/[landing].astro
@@ -2,7 +2,7 @@
 import Section from '$layouts/section.astro';
 
 import { landings, microcopy as micro } from '$lib/sanity';
-import { buildSection, buildTopics } from '$lib/documentation';
+import { buildSection, buildTopics, buildTutorials } from '$lib/documentation';
 
 import SectionNav from '$components/SectionNav.svelte';
 import Text from '$components/Text.astro';
@@ -34,6 +34,7 @@ export function getStaticPaths() {
 const { landing, microcopy } = Astro.props;
 
 const section = buildSection(landing.category, landing._lang);
+const tutorials = buildTutorials(landing.category, landing._lang);
 const topics = buildTopics(section.map((s) => s.href));
 
 let color = 'var(--primary-blue)';
@@ -60,6 +61,8 @@ switch (landing.category.slug) {
     active={landing._path}
     title={landing.category.title}
     links={section}
+    tutorials={tutorials}
+    ttitle="Tutorials"
     client:visible
     slot="subnav"
   />