Essential tasks to complete after setting up your Astrolock site

Your First Steps

Congratulations on setting up your Astrolock site! This guide walks you through the essential tasks to make your site truly yours.

Time to complete: 20-30 minutes Difficulty: Beginner

Follow these steps in order for the best experience.

Prerequisites

Before you begin, verify that Astrolock is installed and working:

astrolock --version

If you see a version number, you’re ready to go. If not, complete the Installation Guide first.

1. Start Your Development Server

Before making any changes, start the development server so you can see your changes in real-time. The write command builds your site and watches for changes:

astrolock write

What this does:

Builds your Astrolock site
Starts a local web server
Watches for file changes and automatically rebuilds
Opens at http://localhost:4321

Open your browser to http://localhost:4321 to see your site. Keep this command running while you work through this guide.

Troubleshooting:

If port 4321 is already in use, the command will fail. Stop other processes using that port or specify a different port in your config.
Press Ctrl+C to stop the server at any time.

The navigation button appears in your site header. By default, it links to this guide. Update it to point somewhere useful for your visitors.

Edit Your Configuration

Open .astrolock/astrolock.yaml and find the navigation_button section:

navigation:
  main: [...]
  footer: [...]
  navigation_button:
    enable: true
    label: "Get Started"
    link: "/about"

Common Options

Link to your latest content:

navigation_button:
  enable: true
  label: "Latest Mix"
  link: "/mixes/latest"

Link to contact page:

navigation_button:
  enable: true
  label: "Get in Touch"
  link: "/contact"

Disable it entirely:

navigation_button:
  enable: false
  label: ""
  link: ""

Save the file and your browser will automatically refresh to show the changes.

3. Replace the Site Images

Your site comes with placeholder images that you should replace with your own.

Important: Keep the same filenames. The site references these images by their exact filenames.

Images to Replace

All site images are located in public/images/site/:

File	Size	Purpose
`logo.svg`	150x30px	Header logo (light mode)
`logo-darkmode.svg`	150x30px	Header logo (dark mode)
`favicon.png`	32x32px	Browser tab icon
`og-image.png`	1200x630px	Social media preview
`banner.png`	1920x600px	Homepage hero image
`call-to-action.png`	800x400px	CTA section image
`avatar.png`	400x400px	Author profile image
`avatar-sm.png`	100x100px	Small avatar (testimonials)
`image-placeholder.png`	800x450px	Default post image

How to Replace

Create your new images at the recommended sizes
Name them exactly the same as the originals (including the file extension)
Copy them to public/images/site/, replacing the existing files

# Example: Replace the banner
cp ~/my-images/hero-banner.png public/images/site/banner.png

# Replace the logo (keep .svg extension for best quality)
cp ~/my-images/my-logo.svg public/images/site/logo.svg
cp ~/my-images/my-logo-white.svg public/images/site/logo-darkmode.svg

Note: SVG files work best for logos as they scale perfectly at any size. If you only have PNG logos, you can use PNG files instead, but rename them to match (e.g., logo.svg even if it’s a PNG, or update your config to reference the PNG extension).

Creating Properly Sized Images

On macOS, you can resize images with sips:

# Resize an image to specific dimensions
sips -z 600 1920 source-image.png --out public/images/site/banner.png

# Resize maintaining aspect ratio
sips --resampleWidth 150 source-logo.svg --out public/images/site/logo.svg

4. Create Your First Blog Post

If you enabled the blog feature (enabled by default), create your first real post to replace the sample content.

Create the Post

astrolock content blog "My First Real Post"

What this does:

Creates src/content/blog/my-first-real-post.md
Pre-fills with frontmatter template
Uses the current date and time
Sets the slug based on the title

Edit the Post

Open the file and customize it:

---
title: "My First Real Post"
description: "A brief summary of what this post is about"
date: 2025-11-24T12:00:00Z
author: "your-name"
image: "/images/content/blog/my-first-post.jpg"
categories: ["announcements"]
tags: ["welcome", "first-post"]
draft: false
---

# My First Real Post

Write your content here using markdown...

## A Section Heading

- Bullet point one
- Bullet point two

**Bold text** and *italic text*.

[A link to somewhere](https://example.com)

Add a Featured Image

Create the directory for your blog images:
```
mkdir -p public/images/content/blog
```

Copy your image to that directory:

cp ~/my-images/post-image.jpg public/images/content/blog/my-first-post.jpg

Reference it in the frontmatter:

image: "/images/content/blog/my-first-post.jpg"

Delete the Sample Post

Once you have your own content, remove the sample:

rm content/blog/welcome.md

5. Working with Media Collections

Astrolock supports four types of collections: images, audio, video, and text. Each type has specific features and display options optimized for that content type.

Check Your Collections

View your current collections:

cat .astrolock/astrolock.yaml

Look for the collections: section. If you haven’t added any collections yet, choose one of the examples below and add it to your config file.

Image Collections (Galleries, Portfolios)

Image collections are perfect for photography portfolios, galleries, or visual content.

Add an Image Collection

Edit .astrolock/astrolock.yaml:

collections:
  galleries:
    displayName: "Photo Galleries"
    contentType: "images"
    defaults:
      contentExtension: "jpg"
    features:
      archive: true

After saving, restart the dev server (Ctrl+C, then astrolock write).

Create a Gallery Item

astrolock content galleries "Summer Vacation 2025"

This creates content/galleries/summer-vacation-2025.md.

Add Your Images

Create the media directory:

mkdir -p public/images/content/galleries

Copy your image:
```
cp ~/photos/beach-sunset.jpg public/images/content/galleries/summer-vacation-2025.jpg
```
Critical: The image filename must exactly match the markdown filename (without the .md extension). For example:
- Markdown: summer-vacation-2025.md
- Image: summer-vacation-2025.jpg

Edit the frontmatter in content/galleries/summer-vacation-2025.md:

---
title: "Summer Vacation 2025"
description: "Photos from our beach trip"
date: 2025-11-24T12:00:00Z
author: "your-name"
categories: ["travel"]
tags: ["beach", "vacation", "2025"]
draft: false
---

A beautiful week at the beach...

Post vs Portfolio Display

Image collections can display as individual posts or as a portfolio grid.

Post style (default) - Each item is a full page:

collections:
  galleries:
    displayName: "Galleries"
    contentType: "images"
    features:
      indexStyle: "posts"

Portfolio style - Thumbnail grid view:

collections:
  galleries:
    displayName: "Portfolio"
    contentType: "images"
    features:
      indexStyle: "portfolio"

Audio Collections (Mixes, Podcasts)

Audio collections are ideal for DJ mixes, podcasts, music, or recordings.

Add an Audio Collection

Edit .astrolock/astrolock.yaml:

collections:
  mixes:
    displayName: "DJ Mixes"
    contentType: "audio"
    defaults:
      contentExtension: "mp3"
    features:
      archive: true
      genres: true

Restart the dev server after saving.

Create a Mix

astrolock content mixes "Friday Night Session"

Add Your Audio File

Create the media directory:
```
mkdir -p public/audio/content/mixes
```
Copy your audio file:
```
cp ~/music/friday-mix.mp3 public/audio/content/mixes/friday-night-session.mp3
```
Critical: Audio filename must exactly match the markdown filename (without the .md extension). For example:
- Markdown: friday-night-session.md
- Audio: friday-night-session.mp3

Edit content/mixes/friday-night-session.md:

---
title: "Friday Night Session"
description: "Live recorded set from the weekend"
date: 2025-11-24T20:00:00Z
author: "dj-name"
categories: ["live-sets"]
tags: ["house", "techno", "live"]
genres: ["house", "techno"]
draft: false
---

## Tracklist

1. Artist - Track Name
2. Artist - Another Track
3. Artist - More Music

## About This Mix

Recorded live at...

Using Genres

If you enabled genres, you can tag mixes by genre and browse by genre:

genres: ["house", "techno", "deep-house"]

This creates browseable pages at:

/mixes/genres/house/
/mixes/genres/techno/
/mixes/genres/deep-house/

Video Collections

Video collections work for tutorials, vlogs, or video content.

Note: Video support is basic - videos are embedded directly without a custom player.

Add a Video Collection

Edit .astrolock/astrolock.yaml:

collections:
  videos:
    displayName: "Videos"
    contentType: "video"
    defaults:
      contentExtension: "mp4"
    features:
      archive: true

Create a Video Item

astrolock content videos "How to Get Started"

Add Your Video File

Create the media directory:
```
mkdir -p public/video/content/videos
```

Copy your video:

cp ~/videos/tutorial.mp4 public/video/content/videos/how-to-get-started.mp4

Edit content/videos/how-to-get-started.md:

---
title: "How to Get Started"
description: "A quick tutorial video"
date: 2025-11-24T12:00:00Z
author: "your-name"
categories: ["tutorials"]
tags: ["beginner", "guide"]
draft: false
---

In this video, we'll cover the basics...

Text Collections (Documentation, Articles)

Text collections don’t have associated media files - they’re pure text content, perfect for documentation, articles, or long-form writing.

Add a Text Collection

Edit .astrolock/astrolock.yaml:

collections:
  articles:
    displayName: "Articles"
    contentType: "text"
    features:
      archive: true
      indexStyle: "posts"

Create an Article

astrolock content articles "Understanding the Basics"

Using indexStyle for Text Collections

Text collections support different display modes:

Posts style - Blog-like list with excerpts:

features:
  indexStyle: "posts"

Content style - Documentation-like sidebar navigation:

features:
  indexStyle: "content"

The “content” style is what the User Guide uses - it shows a sidebar with nested navigation.

Nested Folders for Organization

Text collections with indexStyle: "content" support nested folders:

content/articles/
├── -index.md              # Main index
├── getting-started/
│   ├── -index.md          # Section index
│   ├── installation.md
│   └── configuration.md
├── advanced/
│   ├── -index.md          # Section index
│   ├── customization.md
│   └── plugins.md
└── standalone-article.md

Each -index.md file defines the section:

---
title: "Getting Started"
description: "Begin your journey"
draft: false
---

Introduction to the Getting Started section...

The sidebar automatically reflects this folder structure.

6. Adding Page Features

Astrolock pages support several feature sections in their frontmatter. These work on the homepage and collection index pages.

The banner appears at the top of a page as a hero section.

Edit content/pages/-homepage.md:

banner:
  title: "Welcome to My Site"
  content: "A brief tagline or description"
  image: "/images/site/banner.png"
  button:
    enable: true
    label: "Browse Content"
    link: "/blog"

Features Section

Showcase key aspects of your site or content:

features:
  - title: "Quality Content"
    content: "We deliver high-quality content that informs and inspires."
    image: "/images/content/feature-quality.jpg"
    bulletpoints:
      - "Carefully curated"
      - "Regular updates"
      - "Community driven"
    button:
      enable: true
      label: "Learn More"
      link: "/about"

  - title: "Easy Navigation"
    content: "Find what you're looking for quickly."
    image: "/images/content/feature-nav.jpg"
    bulletpoints:
      - "Clean design"
      - "Fast and responsive"
      - "Mobile friendly"
    button:
      enable: false
      label: ""
      link: ""

Testimonials

Display feedback or quotes from your audience:

testimonials:
  enable: true
  title: "What People Say"
  description: "Feedback from our community"
  testimonials:
    - name: "Jane Doe"
      designation: "Regular Visitor"
      avatar: "/images/avatars/jane.jpg"
      content: "This site has become my go-to resource!"

    - name: "John Smith"
      designation: "Subscriber"
      avatar: "/images/avatars/john.jpg"
      content: "Amazing quality. I keep coming back for more."

    - name: "Alex Johnson"
      designation: "Creator"
      avatar: "/images/site/avatar-sm.png"
      content: "An inspiration to see such great work."

Call to Action (CTA)

Encourage visitor engagement with a prominent CTA section:

cta:
  enable: true
  title: "Ready to Get Started?"
  description: "Join our community and stay updated with the latest content."
  image: "/images/site/call-to-action.png"
  button:
    enable: true
    label: "Contact Us"
    link: "/contact"

Complete Homepage Example

Here’s a full homepage frontmatter with all features enabled:

---
title: "My Awesome Site"
description: "A site about amazing things"
draft: false

banner:
  title: "Welcome to My Awesome Site"
  content: "Discover amazing content created with passion"
  image: "/images/site/banner.png"
  button:
    enable: true
    label: "Get Started"
    link: "/about"

features:
  - title: "Feature One"
    content: "Description of the first feature"
    image: "/images/content/feature-1.jpg"
    bulletpoints:
      - "Point one"
      - "Point two"
      - "Point three"
    button:
      enable: true
      label: "Learn More"
      link: "/blog"

  - title: "Feature Two"
    content: "Description of the second feature"
    image: "/images/content/feature-2.jpg"
    bulletpoints:
      - "Another point"
      - "More details"
    button:
      enable: false
      label: ""
      link: ""

testimonials:
  enable: true
  title: "What People Say"
  description: "Hear from our community"
  testimonials:
    - name: "Happy User"
      designation: "Visitor"
      avatar: "/images/site/avatar-sm.png"
      content: "This site is amazing!"

cta:
  enable: true
  title: "Join Our Community"
  description: "Stay updated with the latest content"
  image: "/images/site/call-to-action.png"
  button:
    enable: true
    label: "Subscribe"
    link: "/contact"
---

Your page content goes here...

Using Features on Collection Index Pages

You can add these same features to collection index pages. Edit content/mixes/-index.md (or any collection’s -index.md):

---
title: "DJ Mixes"
description: "Browse our collection of mixes"
draft: false

banner:
  title: "DJ Mixes"
  content: "Hand-picked selections from our sessions"
  image: "/images/content/mixes-banner.jpg"
  button:
    enable: true
    label: "Latest Mix"
    link: "/mixes/latest"

cta:
  enable: true
  title: "Want More?"
  description: "Follow us for updates on new releases"
  image: "/images/content/mixes-cta.jpg"
  button:
    enable: true
    label: "Contact"
    link: "/contact"
---

7. Build and Deploy

Once you’re satisfied with your site, build it for production and deploy it.

Build for Production

astrolock build

What this does:

Generates optimized static files in dist/
Minifies CSS and JavaScript
Optimizes images
Creates production-ready HTML

Typical build time: 30-60 seconds for a small site

Preview the Build

Test the production build locally before deploying:

astrolock preview

Visit http://localhost:4321 to see exactly what will be deployed. This serves files from dist/ rather than building on the fly.

Deploy to Your Hosting

astrolock deploy <target>

Replace <target> with your configured deployment target (e.g., production, staging).

Note: You must configure deployment targets first. See the Deploy Guide for setup instructions.

Quick Reference

Task	Command
Start dev server	`astrolock write`
Create blog post	`astrolock content blog "Title"`
Create collection item	`astrolock content <collection> "Title"`
Build for production	`astrolock build`
Preview build	`astrolock preview`
Deploy	`astrolock deploy <target>`

Next Steps

Content Management Guide - Learn more about managing content
Working with Collections - Deep dive into collections
Deploy Guide - Set up deployment

Getting Help

Stuck? Check these resources:

Troubleshooting
Support
Run astrolock --help for command reference

Your First Steps

Your First Steps

Prerequisites

1. Start Your Development Server

2. Customize the Navigation Button

Edit Your Configuration

Common Options

3. Replace the Site Images

Images to Replace

How to Replace

Creating Properly Sized Images

4. Create Your First Blog Post

Create the Post

Edit the Post

Add a Featured Image

Delete the Sample Post

5. Working with Media Collections

Check Your Collections

Image Collections (Galleries, Portfolios)

Add an Image Collection

Create a Gallery Item

Add Your Images

Post vs Portfolio Display

Audio Collections (Mixes, Podcasts)

Add an Audio Collection

Create a Mix

Add Your Audio File

Using Genres

Video Collections

Add a Video Collection

Create a Video Item

Add Your Video File

Text Collections (Documentation, Articles)

Add a Text Collection

Create an Article

Using indexStyle for Text Collections

Nested Folders for Organization

6. Adding Page Features

Banner (Hero Section)

Features Section

Testimonials

Call to Action (CTA)

Complete Homepage Example

Using Features on Collection Index Pages

7. Build and Deploy

Build for Production

Preview the Build

Deploy to Your Hosting

Quick Reference

Next Steps

Getting Help