Step 2: Advanced Features

Collections, formatting, stock images, and customization options

Tip

Prerequisites: Complete Step 1: Getting Started first. You should have a working local site before continuing.

What You’ll Learn

By the end of this guide, you’ll know how to:

✅ Create media collections (audio, images, video)
✅ Customize collection display with indexStyle
✅ Use stock images for development
✅ Customize CTAText and collection defaults
✅ Understand all available options

Time Required: 20-30 minutes

Creating Collections

Collections organize related content - blog posts, photo galleries, audio mixes, or videos.

Add a Collection

VS Code (Recommended)
CLI

The easiest way to create collections:

In the Explorer sidebar, find your .astrolock folder
Right-click on .astrolock
Select “Astrolock: Create New Collection”
Follow the interactive wizard

Collection name (e.g., "mixes", "photos"): photos
Display name (shown in menus): Photo Gallery

Content type:
  › Text - Blog posts and articles
    Audio - Music, podcasts, mixes
    Images - Photos and galleries
    Video - Tutorials, vlogs

File extension (e.g., jpg, mp3): jpg

When you finish, Astrolock automatically:

Creates content/photos/ directory
Registers the collection in .astrolock/astrolock.yaml
Creates content/photos/-index.md (collection index page)
Creates content/photos/sample-photos.md (example to get you started)

Run the collection wizard:

astrolock collection add

The wizard will ask:

Collection name (URL-friendly, e.g., 'gallery', 'mixes'): photos
Display name (shown in navigation): Photo Gallery

Choose content type:
  1) Text (blog posts, articles)
  2) Audio (music, podcasts, mixes)
  3) Images (photos, galleries)
  4) Video (tutorials, vlogs)

Choose (1-4): 3
File extension [jpeg]: jpg

✓ Collection 'photos' added to .astrolock/astrolock.yaml
✓ Created sample: content/photos/sample-photos.md

The wizard creates the collection configuration, directory structure, and a helpful sample file.

Tip

New in this version: Collections now come with a sample file showing you exactly how to format your content. Check content/[collection-name]/sample-[collection-name].md for guidance!

Collection Types

Use for: Blog posts, articles, documentation, pages

collections:
  blog:
    displayName: "Blog"
    contentType: "text"
    defaults:
      author: "Your Name"
      ctaText: "Read more"

Creating content:

VS Code
CLI

Right-click content/blog/ → “Create New Content” → Enter title

Use for: Music tracks, DJ mixes, podcasts, sound recordings

collections:
  mixes:
    displayName: "DJ Mixes"
    contentType: "audio"
    defaults:
      contentExtension: "mp3"

Creating content:

VS Code
CLI

Right-click content/mixes/ → “Create New Content” → Enter title

Use for: Photo galleries, portfolios, artwork, event photos

collections:
  gallery:
    displayName: "Photo Gallery"
    contentType: "images"
    defaults:
      contentExtension: "jpg"

Creating content:

VS Code
CLI

Right-click content/gallery/ → “Create New Content” → Enter title

Use for: Tutorials, vlogs, documentaries, product demos

collections:
  tutorials:
    displayName: "Video Tutorials"
    contentType: "video"
    defaults:
      contentExtension: "mp4"

Creating content:

VS Code
CLI

Right-click content/tutorials/ → “Create New Content” → Enter title

Customizing Collection Display

Index Style

Control how your collection’s index page looks with indexStyle:

posts (default)
content
portfolio

Standard blog layout with cards, pagination, and sidebar

collections:
  blog:
    features:
      indexStyle: "posts"

Best for: Blogs, news, time-based content

Shows paginated grid of posts with excerpts and metadata.

Custom landing page - renders body from content/{collection}/-index.md

collections:
  user-guide:
    features:
      indexStyle: "content"

Best for: Curated landing pages, documentation indexes

Create content/user-guide/-index.md with custom welcome text and structure.

Full-width masonry gallery showing all images

collections:
  gallery:
    contentType: "images"
    features:
      indexStyle: "portfolio"

Best for: Photography portfolios, visual showcases

Info

Archive Feature

Enable date-based browsing for time-sensitive content:

collections:
  blog:
    features:
      archive: true

This creates:

/blog/archive/ - Timeline of all posts
/blog/archive/2025/ - Posts from 2025
/blog/archive/2025/01/ - Posts from January 2025

Tip

Perfect for blogs and news sites where readers browse by date.

Stock Images for Development

Add placeholder images to test layouts before your real media is ready.

Quick Setup

Import stock images for a collection:

astrolock import stock-images user-guide

The command:

Reads your .astrolock/stock-images.yaml configuration
Copies placeholder images to public/images/stock/{collection}/
Uses them as fallback images for content without media files

Example stock-images.yaml:

collections:
  user-guide:
    source: /path/to/stock/photos
    count: 12

Stock images automatically appear when:

Content has no featured image specified
The actual media file is missing
During development and testing

Warning

Stock images are for development only. Replace with real images before publishing.

Customizing CTAText

Change the “Read more” / “Listen now” / “View gallery” button text for each collection:

collections:
  blog:
    defaults:
      ctaText: "Read the full article"

  mixes:
    defaults:
      ctaText: "Listen to this mix"

  gallery:
    defaults:
      ctaText: "View photos"

You can also override CTAText per-item in the frontmatter:

---
title: "Special Post"
ctaText: "Check this out!"
---

Collection Defaults

Set default values applied to all content in a collection:

collections:
  mixes:
    displayName: "DJ Mixes"
    contentType: "audio"
    defaults:
      author: "DJ Awesome"
      contentExtension: "mp3"
      ctaText: "Listen now"
      categories: ["mixes"]

When you create new content with astrolock content mixes "Title", these defaults are automatically applied.

Option	Description
`author`	Default author name
`contentExtension`	File extension (mp3, jpg, mp4, etc.)
`ctaText`	Call-to-action button text
`categories`	Default categories
`tags`	Default tags
`theme`	Theme to use (astrobuild, rockem, etc.)
`maxSimilarItems`	Number of similar items to show (default: 6)

Complete Configuration Example

Here’s a full example showing multiple collections with different options:

collections:
  # Text collection for blog
  blog:
    displayName: "Blog"
    contentType: "text"
    defaults:
      author: "Your Name"
      ctaText: "Read more"
    features:
      archive: true
      indexStyle: "posts"
    plugins:
      - stock-images

  # Images collection for portfolio
  portfolio:
    displayName: "Portfolio"
    contentType: "images"
    defaults:
      contentExtension: "jpg"
      ctaText: "View project"
    features:
      archive: false
      indexStyle: "portfolio"
    plugins:
      - stock-images

  # Audio collection for mixes
  mixes:
    displayName: "DJ Mixes"
    contentType: "audio"
    defaults:
      author: "DJ Name"
      contentExtension: "mp3"
      ctaText: "Listen now"
    features:
      archive: true
      indexStyle: "posts"

Reference Documentation

For complete details on all available options:

Collections Configuration →

Complete list of collection options
Features and plugins
Archive and indexStyle details
Theme configuration

Frontmatter References →

Text frontmatter → - Blog posts and articles
Audio frontmatter → - Music and podcasts
Images frontmatter → - Photos and galleries
Video frontmatter → - Video content

VS Code Extension →

Right-click workflows for collections and content
Context menu reference
Troubleshooting

CLI Commands →

astrolock collection add - Create collections
astrolock content - Create content items
astrolock import stock-images - Add placeholder images

Next Steps

Tip

You now understand Astrolock’s advanced features! You can create any type of collection and customize how it displays.

Continue Learning

VS Code Extension Guide → Master the right-click workflows:

Creating collections with context menus
Managing content visually
Development server controls
Multi-folder workspace support

Step 3: Deployment → Learn how to:

Set up deployment targets
Deploy to AWS, Netlify, or Vercel
Manage multiple environments (staging, production)

Import Tools → Bulk import existing content:

Rekordbox DJ mixes
Apple Photos albums
Lightroom exports
Media folders

Common Tasks

Create a new collection:

VS Code
CLI

Right-click .astrolock/ → “Create New Collection”

Add content to a collection:

VS Code
CLI

Right-click collection folder → “Create New Content”

Import stock images:

astrolock import stock-images {collection}

Edit collection settings: Open .astrolock/astrolock.yaml and edit the collections section

Change indexStyle:

collections:
  your-collection:
    features:
      indexStyle: "posts" # or "content" or "portfolio"