Type something to search...
to navigateto selectESC to close

Using the VS Code Extension

Manage your Astrolock site directly from Visual Studio Code

Tip

The VS Code extension makes Astrolock easier to use - manage your site with right-click menus instead of memorizing terminal commands.

What is the VS Code Extension?

The Astrolock VS Code extension adds right-click menu options to manage your site directly from the editor. No need to switch to the terminal or remember command syntax.

What you can do:

  • Create new collections with guided wizards
  • Add content to existing collections
  • Start/stop the development server
  • Run builds and deployments
  • All from right-click context menus

Installation

Prerequisites

You need:

  1. Visual Studio Code - Download from code.visualstudio.com
  2. Astrolock installed - See Installation Guide

Install the Extension

  1. Open VS Code
  2. Open the Extensions sidebar (Cmd+Shift+X on Mac, Ctrl+Shift+X on Windows/Linux)
  3. Search for “Astrolock”
  4. Click “Install”

If you have a .vsix file:

  1. Open VS Code
  2. Open Extensions sidebar
  3. Click the ... menu at the top
  4. Select “Install from VSIX…”
  5. Choose the .vsix file

Opening Your Site in VS Code

Multi-Folder Workspaces

If you manage multiple Astrolock sites, use a multi-folder workspace:

File → Add Folder to Workspace…

Add each site directory. The extension will detect all Astrolock sites in your workspace.

Info

The extension automatically detects which site you’re working with based on which folder you right-click in.

Single Site

Just open your site directory:

File → Open Folder…

Select your Astrolock site root directory (the one containing .astrolock/).

Creating Collections

Using the Context Menu

The easiest way to create a collection:

  1. In the Explorer sidebar, find your site’s .astrolock folder
  2. Right-click on the .astrolock folder
  3. Select “Astrolock: Create New Collection”

The wizard will ask:

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

Click through the prompts to create your collection.

What Gets Created

When you create a collection, Astrolock automatically:

  1. Creates the directory structure - content/[collection-name]/
  2. Registers it in .astrolock/astrolock.yaml
  3. Creates an index file - content/[collection-name]/-index.md
  4. Creates a sample file - content/[collection-name]/sample-[collection-name].md

The sample file shows you exactly how to structure your content.

Multi-Folder Workspaces

Warning

Important: In multi-folder workspaces, right-click on the specific site’s .astrolock folder to create the collection in that site.

Example workspace structure:

Workspace
├── my-personal-site/
│   └── .astrolock/          ← Right-click here for personal site
└── my-business-site/
    └── .astrolock/          ← Right-click here for business site

Creating Content

Using the Context Menu

To add content to a collection:

  1. In the Explorer, navigate to content/[collection-name]/
  2. Right-click on the collection folder
  3. Select “Astrolock: Create New Content”
Content title: Summer Vacation Photos

The content file will be created at:
content/photos/summer-vacation-photos.md

Create this content? [Yes]

The file opens automatically in the editor, ready to edit.

Quick Edit Workflow

  1. Right-click collection folder → Create content
  2. File opens with template frontmatter
  3. Edit the frontmatter and content
  4. Add your media file to public/[media-type]/content/[collection]/
  5. Save and preview in browser

Development Server

Starting the Server

Right-click anywhere in your site and select:

“Astrolock: Start Development Server (write)”

This runs astrolock write and opens a terminal showing the build progress.

Info

The server starts on http://localhost:4321 by default. Your browser won’t open automatically - you need to open it manually.

Stopping the Server

In the terminal running astrolock write, click the trash icon or press Ctrl+C.

Status Bar

When a server is running, you’ll see an indicator in the VS Code status bar (bottom of the window):

⚡ Astrolock: Running

Click it to see quick actions like stopping the server or opening the browser.

Building Your Site

Production Build

Right-click anywhere and select:

“Astrolock: Build Site (build)”

This creates the production-ready dist/ folder.

Build for Specific Target

If you have multiple deployment targets (staging, production):

“Astrolock: Build for Target”

Choose which target from the list.

Configuration

Extension Settings

Open VS Code Settings (Cmd+, or Ctrl+,) and search for “Astrolock” to see available options:

  • Astrolock: CLI Path - Custom path to astrolock CLI (if not in PATH)
  • Astrolock: Terminal Name - Name for integrated terminal (default: “Astrolock”)
  • Astrolock: Auto-detect Sites - Automatically detect Astrolock sites in workspace

Keyboard Shortcuts

You can add custom keyboard shortcuts for common actions:

Code → Preferences → Keyboard Shortcuts (or Cmd+K Cmd+S)

Search for “Astrolock” to see all available commands.

Add these to your keybindings.json:

[
  {
    "key": "cmd+shift+a w",
    "command": "astrolock.write",
    "when": "astrolock.siteDetected"
  },
  {
    "key": "cmd+shift+a b",
    "command": "astrolock.build",
    "when": "astrolock.siteDetected"
  },
  {
    "key": "cmd+shift+a c",
    "command": "astrolock.collection.add",
    "when": "astrolock.siteDetected"
  }
]

Working with Multiple Sites

The extension fully supports multi-folder workspaces:

How It Works

  1. The extension detects all folders containing .astrolock/astrolock.yaml
  2. Context menu actions use the folder you right-clicked on
  3. Each site maintains its own terminal, status, and configuration

Best Practices

Create a workspace file:

File → Save Workspace As…

Save as my-sites.code-workspace. Next time, open this workspace file to load all your sites at once.

Organize by site:

├── personal-blog/
│   ├── .astrolock/
│   └── content/
├── business-site/
│   ├── .astrolock/
│   └── content/
└── client-portfolio/
    ├── .astrolock/
    └── content/

Each site is independent. Right-click on the specific site to work with it.

Troubleshooting

Check that:

  1. .astrolock/astrolock.yaml exists in your site root
  2. The folder is added to your VS Code workspace
  3. Reload VS Code window: Cmd+Shift+P → “Reload Window”

Try:

  1. Make sure you’re right-clicking on a folder (not a file)
  2. Check that the extension is enabled: Extensions sidebar → Astrolock → Enabled
  3. Reload VS Code window

Common causes:

  1. Astrolock not in PATH - Set custom CLI path in extension settings
  2. Not in site directory - Make sure you opened the correct folder
  3. Dependencies missing - Run yarn install or npm install in your site

View error details:

View → Output → Select “Astrolock” from dropdown

The extension uses the folder you right-clicked on. Make sure you’re right-clicking on the correct site’s folders, not a parent directory.

Workaround:

Close the workspace, open just the single site you want to work on.

Tips for Non-Technical Users

You Don’t Need to Use the Terminal

Everything you need for daily content management can be done with right-click menus:

  • Creating collections → Right-click .astrolock/
  • Adding content → Right-click collection folder
  • Starting preview → Right-click anywhere → “Start Development Server”

Finding Your Collections

All your collections are in the content/ folder. Each subfolder is a collection:

content/
├── blog/           ← Right-click here to add blog posts
├── photos/         ← Right-click here to add photos
└── mixes/          ← Right-click here to add mixes

Editing Content

Just click any .md file in your collections to edit it. The top section (between ---) is metadata, everything below is your content.

Adding Media Files

When you create media content (audio, images, video), you need to add the actual media file:

  1. Find the folder: public/[audio|images|video]/content/[collection-name]/
  2. Copy your media file there
  3. Name it to match your content file name

Example:

  • Content file: content/photos/vacation.md
  • Image file: public/images/content/photos/vacation.jpg

Next Steps

Tip

You now know how to use the VS Code extension! Try creating a collection and adding some content using the right-click menus.

Continue learning:

Common workflows:

1. Right-click .astrolock/ → Create Collection
2. Right-click collection/ → Create Content
3. Edit the .md file that opens
4. Add media file to public/ folder
5. Right-click → Start Development Server
6. Open http://localhost:4321 in browser