Media & Metadata: Images, Social Previews, and Tags

beginner 10 minutes
authoring media seo metadata

Enhance your learning modules with rich media and optimize them for discovery through effective metadata and tagging strategies.

Working with Images

Images make your content more engaging and help illustrate complex concepts. Here's how to use them effectively.

Inline Images in Markdown

Use standard markdown image syntax:

![Alt text describing the image](https://example.com/path/to/image.png)

Image Best Practices

  1. Use descriptive alt text - Important for accessibility
  2. Host images externally - Use a CDN or HubSpot file manager
  3. Optimize file sizes - Compress images before uploading
  4. Use appropriate formats:
    • PNG for screenshots and diagrams
    • JPG for photos
    • SVG for icons and logos
    • WebP for modern browsers (with fallbacks)

Hosting Images in HubSpot

You can upload images to HubSpot's file manager and reference them:

  1. Navigate to Marketing > Files and Templates > Files
  2. Upload your image
  3. Copy the public URL
  4. Use the URL in your markdown

Example:

![Kubernetes Architecture](https://fs.hubspotusercontent00.net/hubfs/123456/kubernetes-arch.png)

Image Size Recommendations

  • Social preview images: 1200x630px (1.91:1 ratio)
  • Content images: Maximum width 1200px
  • Thumbnails: 400x300px
  • File size: Keep under 500KB when possible

Social Preview Images

Social preview images (Open Graph images) appear when your module is shared on social media platforms.

Setting a Social Preview Image

Add the social_image field to your front matter:

---
title: "Your Module Title"
slug: "your-module-slug"
social_image: "https://example.com/social-preview.png"
# ... other fields
---

Creating Effective Social Previews

A good social preview should:

  • Display the module title prominently
  • Include your brand logo or colors
  • Use high-contrast text that's readable at small sizes
  • Follow the 1200x630px dimension standard
  • Avoid text that's too small (minimum 40px font size)

Tools for Creating Social Previews

  • Canva - User-friendly design tool
  • Figma - Professional design software
  • Social Image Generator - Automated image generation
  • Custom HTML/CSS templates converted to images

SEO Metadata

Optimize your modules for search engines with proper metadata.

Meta Description

The description field in front matter becomes your meta description:

---
description: "Learn the fundamentals of Kubernetes networking including Services, Ingress, and network policies in this hands-on lab."
---

Meta Description Best Practices

  • Length: 150-160 characters for optimal display
  • Include keywords: Use terms people might search for
  • Make it compelling: Encourage clicks with actionable language
  • Be specific: Describe what learners will actually do or learn
  • Avoid duplication: Each module should have a unique description

Example Meta Descriptions

Good:

Learn to deploy, scale, and manage containerized applications with Kubernetes. Hands-on labs cover pods, services, and deployments.

Bad (too generic):

This module teaches Kubernetes.

Additional Metadata

While not directly in front matter, consider these SEO factors:

  • Title length: Keep titles under 60 characters
  • Heading structure: Use H2, H3 hierarchically
  • Keyword placement: Include target keywords naturally in content
  • Internal linking: Link to related modules

Tagging Strategy

Tags help users discover content and enable filtering/grouping of modules.

Tag Categories

Organize tags into logical categories:

Technology Tags:

  • kubernetes, docker, helm, istio

Topic Tags:

  • networking, storage, security, observability

Level Tags:

  • beginner, intermediate, advanced (though difficulty field handles this)

Special Purpose Tags:

  • authoring, onboarding, certification, troubleshooting

Tagging Best Practices

---
tags:
  - kubernetes          # Primary technology
  - networking          # Core topic
  - services           # Specific feature
  - hands-on           # Learning style
---

Tag Guidelines

  1. Use 3-5 tags per module - More than that dilutes effectiveness
  2. Be consistent - Use the same tag format across modules
  3. Use lowercase - Standardize on lowercase for cleanliness
  4. Use hyphens for multi-word tags - e.g., cloud-native, not cloud native
  5. Avoid redundancy - Don't tag with variations of the same concept

Reserved Tags

Some tags have special meaning in the platform:

  • archived: Hides module from main listings
  • featured: May be used for highlighting popular content
  • wip: Work in progress (consider using archived instead)

Content Blocks with Media

When creating courses and pathways, you can use content blocks to add rich media:

{
  "content_blocks": [
    {
      "id": "welcome-video",
      "type": "text",
      "title": "Course Introduction",
      "body_markdown": "![Course Overview](https://example.com/video-thumbnail.png)\n\nWatch the video above for an overview of what you'll learn."
    }
  ]
}

Testing Your Metadata

After syncing, verify your metadata:

Social Preview Testing

Use these tools to preview how your module appears when shared:

SEO Testing

  • Search for your module in HubSpot search
  • Check that title and description display correctly
  • Verify tags appear in module listings
  • Test filtering by tags

Image Optimization Tools

Before uploading images:

Accessibility Considerations

Always keep accessibility in mind:

  • Alt text: Describe the content and function of images
  • Color contrast: Ensure text on images is readable
  • Text alternatives: Don't rely solely on images to convey information
  • File names: Use descriptive names (e.g., kubernetes-service-types.png not img1.png)

Example: Complete Front Matter with Media

---
title: "Advanced Kubernetes Networking"
slug: "advanced-k8s-networking"
difficulty: "advanced"
estimated_minutes: 45
tags:
  - kubernetes
  - networking
  - advanced
  - network-policies
description: "Master Kubernetes networking with advanced topics including CNI plugins, network policies, and service mesh integration."
social_image: "https://fs.hubspotusercontent00.net/hubfs/123456/k8s-networking-social.png"
order: 15
version: "v1.30"
validated_on: "2025-10-13"
---

Next Steps

Now that you understand media and metadata:

Resources