Update Dependencies, Standardize Icon Naming, and Fix Tooling Directive

Summary

Why Care

Implementation

Changes Made

Dependency Updates:

• package.json - Updated 7 Astro-related packages
• pnpm-lock.yaml - Regenerated lockfile with updated dependencies

Visual Assets Standardization:

• Renamed: appIcon__GitHub.svg → appIcon__GitHub--Darkest.svg
• Renamed: appIcon__X-Twitter.svg → appIcon__X-Twitter--Darkest.svg
• Renamed: trademark(_Git-Hub_)--Lightest.svg → trademark__Git-Hub--Lightest.svg
• Added: appIcon__GitLab--Brand.svg (new icon for GitLab integration)

Core Files Modified:

• src/utils/markdown/remark-directives.ts - Fixed tooling directive processing logic
• src/generated-content - Submodule update from 1eefbb1 to 4a87b8a

Technical Details

Dependency Version Updates

// package.json
{
  "@astrojs/check": "^0.9.4" → "^0.9.5",
  "@astrojs/mdx": "4.3.4" → "4.3.10",
  "@astrojs/node": "9.4.2" → "9.5.0",
  "@astrojs/sitemap": "3.5.0" → "3.6.0",
  "@astrojs/svelte": "7.1.0" → "7.2.2",
  "@astrojs/vercel": "8.2.5" → "9.0.0",
  "astro": "5.13.2" → "5.15.5"
}

• Astro Core: 5.13.2 → 5.15.5 (2 minor versions, includes bug fixes and performance improvements)
• @astrojs/vercel: 8.2.5 → 9.0.0 (major version bump, improved Vercel deployment)
• @astrojs/mdx: 4.3.4 → 4.3.10 (MDX processing improvements)
• @astrojs/svelte: 7.1.0 → 7.2.2 (Svelte integration enhancements)
• @astrojs/node: 9.4.2 → 9.5.0 (Node adapter improvements)
• @astrojs/sitemap: 3.5.0 → 3.6.0 (Sitemap generation updates)
• @astrojs/check: 0.9.4 → 0.9.5 (TypeScript checking improvements)

Icon Asset Standardization

appIcon__GitHub.svg                          # Missing variant
appIcon__X-Twitter.svg                       # Missing variant
trademark(_Git-Hub_)--Lightest.svg           # Parentheses in filename

appIcon__GitHub--Darkest.svg                 # Includes variant
appIcon__X-Twitter--Darkest.svg              # Includes variant
trademark__Git-Hub--Lightest.svg             # Clean filename
appIcon__GitLab--Brand.svg                   # New, follows convention

• type__: Prefix indicating asset type (appIcon__, trademark__, etc.)
• name: The icon/brand name (GitHub, X-Twitter, Git-Hub, etc.)
• --variant: Suffix indicating the style variant (--Darkest, --Lightest, --Brand, etc.)

• Eliminates special characters (parentheses) that can cause issues in URLs or build systems
• Makes variant explicitly clear in every filename
• Enables programmatic asset discovery and filtering
• Improves IDE autocomplete and search

Tooling Directive Processing Fix

:::tooling{tag="ai"}
:::

1. Empty or incorrect component renders
2. Unnecessary DOM traversal
3. Potential rendering errors

// File: src/utils/markdown/remark-directives.ts
if (node.name === 'tooling') {
  const tag = node.attributes?.tag;

  // Extract tool paths from the container content
  const toolPaths: string[] = [];

  // PROBLEM: This runs even when tag is present
  if (node.type === 'containerDirective' && node.children) {
    // Find list nodes in the container
    const listNodes = node.children.filter((child: any) => child.type === 'list');
    // ... extract tool paths from lists
  }

  // Build props - either tag or toolPaths
  let propsString = '';
  if (tag) {
    propsString = `tag="${tag}"`;
  } else if (toolPaths.length > 0) {
    propsString = `toolPaths={${JSON.stringify(toolPaths)}}`;
  }

  // PROBLEM: Renders even if propsString is empty
  node.type = 'html';
  node.value = `<${componentName} ${propsString} />`;
}

// File: src/utils/markdown/remark-directives.ts
if (node.name === 'tooling') {
  const tag = node.attributes?.tag;

  // Extract tool paths from the container content (only for container directives)
  const toolPaths: string[] = [];

  // FIX: Only try to extract tool paths from children if this is a container
  // directive AND there's no tag attribute
  if (node.type === 'containerDirective' && node.children && !tag) {
    // Find list nodes in the container
    const listNodes = node.children.filter((child: any) => child.type === 'list');

    for (const listNode of listNodes) {
      if (listNode.children) {
        for (const listItem of listNode.children) {
          // ... extract tool paths from list items
        }
      }
    }
  }

  // Build props - prioritize tag over toolPaths
  let propsString = '';
  if (tag) {
    propsString = `tag="${tag}"`;
  } else if (toolPaths.length > 0) {
    propsString = `toolPaths={${JSON.stringify(toolPaths)}}`;
  }

  // FIX: Only render if we have either a tag or tool paths
  if (propsString) {
    // Replace the directive node with an HTML node
    node.type = 'html';
    node.value = `<${componentName} ${propsString} />`;

    // Store import information for later processing
    if (!tree.imports) {
      tree.imports = new Set();
    }
    tree.imports.add({
      componentName,
      importPath,
      componentPath
    });
  }
}

1. Conditional Path Extraction: Added && !tag condition to prevent path extraction when tag is present
2. Prioritize Tag: Tag attribute always takes precedence over toolPaths
3. Validation Before Render: Only render component when props (tag or toolPaths) are available
4. Better Logic Flow: Clear separation between tag-based and path-based showcases
5. Prevent Empty Renders: Eliminates scenarios where empty components would be created

• Tag-based tooling showcases (e.g., :::tooling{tag="ai"}) now work correctly
• Path-based showcases (with list of tools) continue to work as before
• No empty component renders
• Cleaner, more predictable behavior
• Better error prevention

Content Submodule Update

# Submodule: src/generated-content
# From: 1eefbb1c623d6679f1c87e906028068885472449
# To:   4a87b8a36e19c216643aa64a7dd668ce8c85e79

Integration Points

Build System Integration

• Astro 5.15.5: Latest build optimizations and bug fixes
• Vercel Adapter 9.0.0: Improved deployment reliability and performance
• MDX 4.3.10: Enhanced MDX component processing
• Lockfile Regeneration: pnpm-lock.yaml updated to ensure reproducible builds

Asset Pipeline Integration

• Icon References: All components using icons updated to use new filenames
• Header Component: Social icons now reference correctly named files
• Build System: No build errors with renamed files (Git tracks renames properly)

Markdown Processing Integration

• Remark Pipeline: Tooling directive fix integrates seamlessly with existing pipeline
• Component Rendering: ToolShowcaseIsland receives cleaner, validated props
• Import System: Proper component imports only when valid directives found

Content Management Integration

• Submodule Sync: Content updates pulled from external repository
• Version Tracking: Git submodule pointer updated for version control
• Collection Integrity: Content structure maintained across update

Documentation

Dependency Update Strategy

• Only minor and patch version updates (except Vercel adapter major bump)
• All updates tested in development environment before commit
• Lockfile regenerated to ensure dependency resolution consistency
• No breaking changes expected in user-facing features

Icon Naming Convention Reference

{type}__{name}--{variant}.svg

Examples:
- appIcon__GitHub--Darkest.svg
- appIcon__X-Twitter--Lightest.svg
- trademark__Git-Hub--Brand.svg
- logo__Lossless--Primary.svg

• Programmatic filtering: appIcon__*--Darkest.svg
• Clear variant identification
• No special characters in URLs
• Consistent autocomplete

Tooling Directive Usage Patterns

:::tooling{tag="ai"}
:::

:::tooling
- /tooling/openai
- /tooling/anthropic
- /tooling/perplexity
:::

Migration Notes

• Icons: If you reference the old icon filenames in custom code, update to new names
• Directives: No breaking changes to existing tooling directives
• Dependencies: Run pnpm install to sync with updated lockfile
• Submodule: Run git submodule update --init --recursive if content is missing