Add carousel to tag page, remove tag from testimonials, case, studies, and services, and reorganize tag categories

Author: webstackdev

.cache/pages.json

@@ -37,14 +37,13 @@
   },
   {
     "tags": [
-      "apiDesign",
-      "cms",
-      "code",
-      "crm",
-      "graphql",
-      "online-learning",
-      "react",
-      "services",
+      "api-platforms-and-edge",
+      "cloud-infrastructure",
+      "legacy-systems-and-modernization",
+      "observability",
+      "platform-engineering-and-developer-experience",
+      "release-engineering",
+      "reliability-engineering",
       "typescript"
     ]
   }

.vscode/settings.json

@@ -75,6 +75,7 @@
     "MTTR",
     "nanostores",
     "navigations",
+    "ndots",
     "nektosact",
     "Neue",
     "Niklas",
@@ -94,6 +95,7 @@
     "Postg",
     "postgrest",
     "psql",
+    "Pulumi",
     "pylint",
     "qpart",
     "qparts",
@@ -130,6 +132,7 @@
     "tsdoc",
     "tseslint",
     "tshirt",
+    "Turborepo",
     "Tursa",
     "Turso",
     "tydata",

_TODO.md

@@ -88,6 +88,14 @@ if (window.matchMedia) {
 }
 ```
 
-## Tags cards
+Our site has tag pages that are categories for article content. Each of the individual tag pages should have a paragraph or two in the markdown field that describes what the tag (category) is about and covers. Right now at the top of the content area on each page, there are some bullet points or a brief description. Please refer to ./CONTENT.md for the voice and focus of content on the site. Then please do the following:
 
-Put the tags on the all-categories top level page into carousels by category
+1. Rewrite the content between the last frontmatter code fence (`---`) and the "Article Ideas" header as described above, into an introduction to this category.
+
+2. Rewrite the "TODO" in the "description" front matter to feature a brief description of the category that can be shown in tooltips when a user hovers over a tag name on an article page and that's used in SEO metadata like OpenGraph descriptions.
+
+3. In the "Cover Prompt" header, add four or five AI prompts that can be used to generate a cover image for this category. I don't have a defined visual style for the site yet except that it is technical, modern, interesting (so cartoon balloon speech tags are ok), and highly professional. The suggested AI prompts for image generation should be very detailed. I'm hoping to find a visual style from evaluating prompt suggestions for images.
+
+4. At the very bottom of the tag / category page, add a header named "Slug and displayName Suggestions" and add four or five alternate suggestions for the slug and displayName (alternatives to the `slug` and `displayName` already defined in frontmatter properties and the slug the directory the index.mdx file is named after).
+
+5. On most tag / category pages, ignore the content between the "Article Ideas" header and the "Cover Prompt" header. However, for api-platforms-and-edge, we are very weak on article ideas. Please add 8 more article ideas for this tag / category. It seems like maybe we should have something about swagger, and something about managing costs associated with API endpoints.

src/components/Carousel/@types/index.ts

@@ -15,10 +15,12 @@ type CollectionEntryMap = {
 
 export interface CarouselProps<T extends CollectionSlug = CollectionSlug> {
   title?: string
+  titleHref?: string
   limit?: number
   variant?: CarouselVariant
   currentSlug: string
   type: T
+  items?: Array<ItemType<T>>
 }
 
 export type ItemType<T extends CollectionSlug = CollectionSlug> = CollectionEntryMap[T]

src/components/Carousel/client/__tests__/index.spec.ts

@@ -60,7 +60,7 @@ vi.mock('@components/scripts/store', () => ({
 }))
 
 type CarouselComponentModule = WebComponentModule<CarouselElement>
-type ConcreteCarouselProps = Required<CarouselProps<'articles'>>
+type ConcreteCarouselProps = CarouselProps<'articles'>
 
 vi.mock('astro:content', () => ({
   getCollection: vi.fn(async () => sampleCollection),

src/components/Carousel/client/__tests__/selectors.spec.ts

@@ -76,7 +76,7 @@ vi.mock('embla-carousel-autoplay', () => ({
 
 type CarouselModule = WebComponentModule<CarouselElement>
 
-type ConcreteCarouselProps = Required<CarouselProps<'articles'>>
+type ConcreteCarouselProps = CarouselProps<'articles'>
 
 const defaultCarouselProps: ConcreteCarouselProps = {
   title: 'Featured Articles',

src/components/Carousel/index.astro

@@ -10,21 +10,25 @@ import { prepareItems } from './server'
 
 export interface Props {
   title?: string
+  titleHref?: string
   limit?: number
   variant?: CarouselVariant
   currentSlug: string
   type: CollectionSlug
+  items?: ItemType[]
 }
 
 const {
   title = 'Featured Content',
+  titleHref,
   limit = 3,
   variant = 'featured',
   currentSlug,
   type,
+  items: itemsOverride,
 } = Astro.props
 
-const allItems = await getCollection(collectionMap[type])
+const allItems = itemsOverride ?? (await getCollection(collectionMap[type]))
 const items = prepareItems(allItems, variant, currentSlug, limit)
 
 const carouselId = `carousel-${type}-${variant}-${currentSlug}`
@@ -36,7 +40,13 @@ const carouselId = `carousel-${type}-${variant}-${currentSlug}`
       <section class="max-w-6xl mx-auto px-4 sm:px-6 lg:px-8 py-16">
         <header class="text-center mb-12">
           <h2 id={`${carouselId}-title`} class="text-3xl md:text-4xl font-bold">
-            {title}
+            {titleHref ? (
+              <a href={titleHref} class="hover:text-primary transition-colors duration-200">
+                {title}
+              </a>
+            ) : (
+              title
+            )}
           </h2>
         </header>
 

src/components/Layout/Markdown/Tags/index.astro

@@ -1,24 +1,67 @@
 ---
+import { getCollection } from 'astro:content'
+
 export interface Props {
   tags: string[]
 }
 
 const { tags } = Astro.props
+
+const allTags = await getCollection('tags')
+
+type TagMeta = {
+  slug: string
+  displayName: string
+}
+
+const tagMetaByIdentifier = new Map<string, TagMeta>()
+
+for (const tagEntry of allTags) {
+  const meta: TagMeta = {
+    slug: tagEntry.data.slug,
+    displayName: tagEntry.data.displayName,
+  }
+
+  tagMetaByIdentifier.set(tagEntry.id, meta)
+  tagMetaByIdentifier.set(tagEntry.data.slug, meta)
+
+  if (tagEntry.id.endsWith('/index')) {
+    tagMetaByIdentifier.set(tagEntry.id.replace(/\/index$/, ''), meta)
+  }
+
+  tagMetaByIdentifier.set(`${tagEntry.data.slug}/index`, meta)
+  tagMetaByIdentifier.set(`${tagEntry.data.slug}/index.mdx`, meta)
+  tagMetaByIdentifier.set(`${tagEntry.data.slug}/index.md`, meta)
+}
+
+const resolveTagMeta = (rawTag: string) => {
+  return (
+    tagMetaByIdentifier.get(rawTag) ??
+    tagMetaByIdentifier.get(rawTag.replace(/\.(md|mdx)$/, '')) ??
+    tagMetaByIdentifier.get(rawTag.replace(/\/index$/, ''))
+  )
+}
 ---
 
 <ul class="flex flex-wrap gap-1 list-none p-0 m-0" aria-label="Article tags">
   {
-    tags.map(tag => (
-      <li>
-        <a
-          href={`/tags/${tag}`}
-          rel="tag"
-          itemprop="keywords"
-          class="inline-block px-2 py-0.5 bg-page-active rounded text-xs no-underline transition-colors hover:bg-spotlight hover:text-primary focus:bg-spotlight focus:text-primary"
-        >
-          {tag}
-        </a>
-      </li>
-    ))
+    tags.map(rawTag => {
+      const meta = resolveTagMeta(rawTag)
+      const href = meta ? `/tags/${meta.slug}` : `/tags/${rawTag}`
+      const label = meta ? meta.displayName : rawTag
+
+      return (
+        <li>
+          <a
+            href={href}
+            rel="tag"
+            itemprop="keywords"
+            class="inline-block px-2 py-0.5 bg-page-active rounded text-xs no-underline transition-colors hover:bg-spotlight hover:text-primary focus:bg-spotlight focus:text-primary"
+          >
+            {label}
+          </a>
+        </li>
+      )
+    })
   }
 </ul>

src/content.config.ts

@@ -10,41 +10,17 @@
  */
 import { defineCollection, reference, z, type SchemaContext } from 'astro:content'
 import { glob, file } from 'astro/loaders'
-import { existsSync, readdirSync } from 'node:fs'
-import { fileURLToPath } from 'node:url'
 /**
- * Wraps a collection schema with a refinement that enforces breadcrumb title length limits */
+ * Wraps a collection schema with a refinement that enforces breadcrumb title length limits
+ */
 import { withBreadcrumbTitleWarning } from '@lib/helpers/breadcrumbTitleLengthRefinement'
 
 /**
- * NOTE: In YAML, dates written without quotes around them are interpreted as Date objects */
-
-/** Only load markdown and MDX files that do not start with an underscore */
-const pattern = '**\/[^_]*.{md,mdx}'
-
-function fsExists(url: URL) {
-  return existsSync(fileURLToPath(url))
-}
-
-const getValidTags = () => {
-  const tagContentDir = fileURLToPath(new URL('./content/tags', import.meta.url))
-  const tagSlugs = readdirSync(tagContentDir, { withFileTypes: true })
-    .filter(entry => entry.isDirectory() && !entry.name.startsWith('_'))
-    .filter(entry => {
-      const indexMd = new URL(`./content/tags/${entry.name}/index.md`, import.meta.url)
-      const indexMdx = new URL(`./content/tags/${entry.name}/index.mdx`, import.meta.url)
-      return fsExists(indexMd) || fsExists(indexMdx)
-    })
-    .map(entry => entry.name)
-    .sort((a, b) => a.localeCompare(b, 'en'))
-
-  if (tagSlugs.length === 0) {
-    throw new Error('No tags found. Add markdown files under src/content/tags.')
-  }
-  return tagSlugs as [string, ...string[]]
-}
+ * NOTE: In YAML, dates written without quotes around them are interpreted as Date objects
+ */
 
-const validTags = getValidTags()
+const pattern = '**/index.{md,mdx}'
+const flatMarkdownPattern = '**/*.{md,mdx}'
 
 const createBaseCollectionSchema = ({ image }: SchemaContext) =>
   z.object({
@@ -55,7 +31,6 @@ const createBaseCollectionSchema = ({ image }: SchemaContext) =>
     featured: z.boolean().default(false),
     isDraft: z.boolean().default(false),
     publishDate: z.date(),
-    tags: z.array(z.enum(validTags)),
   })
 
 const createSocialCollectionSchema = () =>
@@ -87,6 +62,7 @@ const articlesCollection = defineCollection({
         author: reference('authors'),
         readingTime: z.string().optional(),
         showToc: z.boolean().default(true),
+        tags: reference('tags').array(),
       }),
       'articles'
     ),
@@ -188,7 +164,7 @@ const aboutCollection = defineCollection({
  * Authors
  */
 const authorsCollection = defineCollection({
-  loader: glob({ pattern, base: './src/content/authors' }),
+  loader: glob({ pattern: flatMarkdownPattern, base: './src/content/authors' }),
   schema: () =>
     z.object({
       id: z.string(),
@@ -222,7 +198,7 @@ const contactDataCollection = defineCollection({
  * Tags
  */
 const tagsCollection = defineCollection({
-  loader: glob({ pattern: '**/index.{md,mdx}', base: './src/content/tags' }),
+  loader: glob({ pattern, base: './src/content/tags' }),
   schema: ({ image }) =>
     z.object({
       slug: z.string(),
@@ -243,7 +219,6 @@ const testimonialCollection = defineCollection({
     z.object({
       name: z.string(),
       organization: z.string().optional(),
-      tags: z.array(z.enum(validTags)),
       avatar: z
         .object({
           src: z.string(),

src/content/articles/building-with-astro/index.mdx

@@ -5,7 +5,7 @@ cover: "./cover.webp"
 coverAlt: "Hero image for article"
 author: "kevin-brown"
 publishDate: 2024-01-15
-tags: ["typescript", "cms"]
+tags: []
 featured: true
 ---