Understanding PROJECT_FOLDER and USER_FOLDER layouts
Directory Structure
Astrolock operates with two key directories: the PROJECT_FOLDER (Astrolock source code) and the USER_FOLDER (user’s site).
PROJECT_FOLDER (Astrolock Source)
This is where Astrolock itself lives. Developers working on Astrolock modify files here.
astrolock/ # PROJECT_FOLDER
├── cli/ # Bashly CLI source
│ ├── bashly.yml # Command definitions (THE source of truth)
│ ├── commands/ # Command implementations
│ │ ├── configure/ # Site setup wizard steps
│ │ ├── content/ # Content CRUD operations
│ │ ├── collection/ # Collection management
│ │ ├── deploy/ # Deployment to platforms
│ │ ├── import/ # Content import tools
│ │ └── site/ # Build/preview commands
│ └── lib/ # Shared bash functions
│ ├── colors.sh # Terminal colors
│ ├── json.sh # JSON manipulation
│ ├── validation.sh # Input validation
│ └── templates.sh # GENERATED - embedded JSON templates
│
├── src/ # Astro site source
│ ├── config/ # Default site configuration (templates)
│ ├── content/ # Default/example content
│ │ ├── blog/ # Example blog posts
│ │ ├── authors/ # Example author profiles
│ │ ├── pages/ # Static pages (about, contact)
│ │ ├── user-guide/ # User documentation
│ │ └── developer-guide/ # Developer documentation
│ ├── layouts/ # Astro layouts
│ │ ├── partials/ # Header, Footer, Sidebar
│ │ └── shortcodes/ # MDX components (Notice, Tabs, etc.)
│ ├── components/ # Reusable UI components
│ ├── pages/ # Route definitions (Astro pages)
│ │ ├── [collection]/ # Dynamic collection routes
│ │ └── index.astro # Homepage
│ └── lib/ # TypeScript utilities
│ ├── config/ # Config loaders (getSiteConfig, etc.)
│ └── media/ # Media file utilities
│
├── plugins/ # Standalone tools
│ ├── docker-runner/ # Docker image configuration
│ │ └── Dockerfile # Image definition
│ ├── rekordbox/ # Rekordbox XML import
│ ├── stock-images/ # Stock image generator
│ └── json-generator/ # JSON template generation
│
├── bin/ # Generated executables
│ └── astrolock # GENERATED - compiled CLI (gitignored)
│
├── terraform/ # Infrastructure as code
│ └── aws/ # AWS modules
│ ├── astrolock_backend/ # Backend infrastructure (S3, DynamoDB)
│ └── astrolock_site/ # Site infrastructure (S3, CloudFront)
│
├── .context/ # Development documentation
│ └── docs/ # Implementation plans & notes
│
├── Makefile # Build orchestration
├── package.json # Node.js dependencies
└── astro.config.mjs # Astro configurationKey Directories Explained
- cli/
- src/
- plugins/
- bin/
The Bashly CLI source. All user-facing commands are defined in bashly.yml and implemented in commands/. Run bashly generate after changes to rebuild bin/astrolock.
The Astro site source. This generates the static HTML/CSS/JS. Contains default content that users can override.
Standalone tools that aren’t required for site generation. These are “loose” utilities for specific workflows like importing from Rekordbox or generating stock images.
Generated executables. The astrolock CLI is compiled here by Bashly. This folder is gitignored - regenerate with bashly generate.
The Bashly CLI source. All user-facing commands are defined in bashly.yml and implemented in commands/. Run bashly generate after changes to rebuild bin/astrolock.
The Astro site source. This generates the static HTML/CSS/JS. Contains default content that users can override.
Standalone tools that aren’t required for site generation. These are “loose” utilities for specific workflows like importing from Rekordbox or generating stock images.
Generated executables. The astrolock CLI is compiled here by Bashly. This folder is gitignored - regenerate with bashly generate.
USER_FOLDER (User’s Site)
This is where a user’s site lives. Created by astrolock init.
my-site/ # USER_FOLDER
├── .astrolock/ # Astrolock-specific configuration
│ ├── astrolock.yaml # UNIFIED configuration file (all settings)
│ ├── rekordbox.yaml # Plugin-specific settings (optional)
│ ├── lightroom.yaml # Plugin-specific settings (optional)
│ ├── apple-photos.yaml # Plugin-specific settings (optional)
│ └── terraform/ # Infrastructure definitions
│ └── aws/ # Terraform for this site
│ ├── targets/ # Environment-specific configs
│ │ ├── live/ # Production environment
│ │ └── stage/ # Staging environment
│ ├── main.tf # Module reference
│ └── variables.tf # Variable definitions
│
├── content/ # User's content (markdown files)
│ ├── blog/ # Blog posts
│ │ ├── -index.md # Blog index page content
│ │ └── my-post.md # Individual posts
│ ├── authors/ # Author profiles
│ ├── pages/ # Static pages
│ │ ├── about.md
│ │ └── contact.md
│ └── {collections}/ # User-defined media collections
│ ├── -index.md # Collection index page
│ └── item-slug.md # Individual items
│
├── public/ # Static assets (served as-is)
│ ├── images/
│ │ └── site/ # Sit erelated images
│ │ ├── logo.svg # Basic logo SVG
│ │ ├── ...
│ │ └── content/ # Content-related images
│ │ ├── blog/ # Blog post images
│ │ └── {collection}/ # Per-collection images
│ ├── audio/
│ │ └── content/
│ │ └── {collection}/ # Audio files (mp3, wav)
│ └── video/
│ └── content/
│ └── {collection}/ # Video files (mp4)
│
└── dist/ # GENERATED - built site output
├── index.html
├── blog/
└── ...Key Directories Explained
- .astrolock/
- content/
- public/
Astrolock-specific configuration that’s separate from site content.
The astrolock.yaml file contains ALL site configuration in a single, unified format including:
- Site settings (title, URL, branding)
- Content collections configuration
- Navigation menus
- Social links
- Theme settings
- Deployment targets
- Plugin configurations
See User Guide: Reference for configuration details.
All site content as markdown files. Each collection has its own folder. The -index.md file in each folder controls the collection’s index page.
Static assets served directly. Media files should follow the {type}/content/{collection}/ convention for automatic discovery.
Astrolock-specific configuration that’s separate from site content.
The astrolock.yaml file contains ALL site configuration in a single, unified format including:
- Site settings (title, URL, branding)
- Content collections configuration
- Navigation menus
- Social links
- Theme settings
- Deployment targets
- Plugin configurations
See User Guide: Reference for configuration details.
All site content as markdown files. Each collection has its own folder. The -index.md file in each folder controls the collection’s index page.
Static assets served directly. Media files should follow the {type}/content/{collection}/ convention for automatic discovery.
Info
The dist/ folder is generated output from astrolock build. This is what gets deployed. It’s gitignored - regenerate with each build.
Environment Variables
When running Astrolock commands from a USER_FOLDER, these environment variables tell Astro where to find user content:
| Variable | Purpose | Default |
|---|---|---|
ASTROLOCK_CONFIG_DIR | User’s .astrolock directory | ./.astrolock |
ASTROLOCK_CONTENT_DIR | User’s content directory | ./content |
ASTROLOCK_PUBLIC_DIR | User’s public assets directory | ./public |
Tip
These are set automatically by the CLI when running from a user site directory. The unified astrolock.yaml configuration file is located at $ASTROLOCK_CONFIG_DIR/astrolock.yaml.
File Naming Conventions
- Use lowercase with hyphens:
my-blog-post.md - The filename becomes the URL slug:
/blog/my-blog-post/ - Special:
-index.mdis the collection index page
- Match the content file name:
my-mix.md→my-mix.mp3 - Place in the correct type folder:
public/audio/content/{collection}/
- Primary config:
.astrolock/astrolock.yaml(YAML format, all settings) - Plugin configs:
.astrolock/{plugin-name}.yaml(optional, plugin-specific) - All configuration is now in YAML format for better readability