Configuring Spaceship

This guide covers all configuration options available in Spaceship and how to customize your blog.

#Configuration File

All site settings are in site/config.ts. This TypeScript file provides type safety and autocompletion.

#Basic Site Information

export const SITE: SiteConfig = {
  author: 'Your Name',
  title: 'Your Blog Title',
  desc: 'Your blog description',
  website: 'https://yourdomain.com',
  lang: 'en-US',
  base: '/',
  ogImage: 'og.png',
  // ...
};

#Key Fields

author: Your name (appears in footer, meta tags)
title: Site title (browser tab, SEO)
desc: Site description (SEO, social sharing)
website: Full URL of your site
lang: Language code (e.g., ‘en-US’, ‘ru-RU’)
base: Base path if not hosting at root
ogImage: Default Open Graph image

social: {
  x: 'https://x.com/yourusername',
  github: 'https://github.com/yourusername',
  telegram: 'https://t.me/yourusername',
  facebook: 'https://facebook.com/yourusername',
}

You can add, remove, or modify social links. They appear in the homepage hero section.

#Homepage Configuration

#Hero Section

homeHeroDescription: 'Your bio or tagline that appears on the homepage';

#Post Counts

Control how many posts show on the homepage:

featuredPostsCount: 1,  // Number of featured posts
latestPostsCount: 3,    // Number of latest posts

Note: Featured posts are those with featured: true in frontmatter.

#Content Descriptions

blogDescription: 'Description shown on /posts page',
projectsDescription: 'Description shown on /projects page'

#CTA (Call-to-Action) Configuration

cta: {
  enabled: true,
  filePath: 'site/cta.md',
}

enabled: Global toggle for CTA blocks
filePath: Path to markdown file with CTA content

#Customizing CTA Content

Edit site/cta.md:

# 💼 Hire me if you like this post

I'm available for **freelance projects** and **full-time opportunities**.

Whether you need:

- A modern, performant website
- Technical consultation
- Code review and optimization

[Get in touch](mailto:your@email.com)

The CTA appears at the end of each post (unless disabled via frontmatter).

#Comments Configuration

Spaceship uses Giscus for comments powered by GitHub Discussions.

comments: {
  enabled: true,
  repo: 'username/repo',
  repoId: 'R_xxxxx',
  category: 'General',
  categoryId: 'DIC_xxxxx',
  mapping: 'pathname',
  reactionsEnabled: true,
  emitMetadata: false,
  inputPosition: 'bottom',
  theme: 'preferred_color_scheme',
  lang: 'en',
}

#Getting Giscus Configuration

Visit giscus.app
Enter your repository name
Configure options
Copy the configuration values

#Options Explained

enabled: Master toggle for comments
repo: GitHub repository (format: username/repo)
repoId: Repository ID from giscus.app
category: Discussion category name
categoryId: Category ID from giscus.app
mapping: How to map posts to discussions
- pathname: Use URL path (recommended)
- url: Use full URL
- title: Use post title
reactionsEnabled: Allow reactions on comments
theme: Color scheme
- preferred_color_scheme: Auto-match site theme
- light: Always light
- dark: Always dark
lang: Language code

#Requirements for Giscus

Public repository
GitHub Discussions enabled
- Go to repo Settings → Features → Discussions
giscus app installed
- Visit github.com/apps/giscus
- Install and grant access to your repo

#Analytics

googleAnalyticsId: 'G-XXXXXXXXXX';

Add your Google Analytics 4 measurement ID. Leave empty to disable.

#Content Collections

Content is organized in site/content/:

site/content/
├── posts/          # Blog posts
├── projects/       # Portfolio projects
├── appearances/    # Talks, podcasts, articles
└── about/          # About page content

#Posts Schema

See How to Publish Posts for full details.

#Projects Schema

---
title: 'Project Name'
description: 'Brief description'
link: 'https://project-url.com'
github: 'https://github.com/user/repo' # Optional
tags: ['astro', 'svelte']
types: ['commercial', 'open-source', 'social']
image: '/images/project.png' # Optional
order: 0 # Display order (lower = first)
directLink: true # Link directly to project vs detail page
---

#Appearances Schema

---
title: 'Talk Title'
event: 'Conference Name'
date: 2026-02-01
type: 'talk' # talk, podcast, article, workshop, video
media: 'video' # video, audio, text
link: 'https://youtube.com/watch?v=xxx'
description: 'Optional description'
language: 'English'
duration: '45 minutes'
---

#Styling & Theming

Spaceship uses CSS custom properties for theming. Edit src/styles/global.css:

:root {
  --color-primary: 220 100% 70%;
  --color-foreground: 0 0% 10%;
  /* ... more variables */
}

.dark {
  --color-primary: 220 100% 75%;
  --color-foreground: 0 0% 95%;
  /* ... dark mode overrides */
}

#Updating Spaceship

To get the latest features and bug fixes:

git remote add upstream https://github.com/alec-c4/spaceship.git
git fetch upstream
git merge upstream/main

Note: Be careful merging if you’ve customized code. Review conflicts carefully.

#Safe Update Strategy

Commit your changes first

Create a backup branch

git checkout -b backup-before-update
git checkout main

Merge upstream
```
git merge upstream/main
```
Test thoroughly with pnpm dev
If issues, restore from backup

#Deployment

#Vercel (Recommended)

Push to GitHub
Import project in Vercel
Framework: Astro
Build command: pnpm build
Output directory: dist

#Netlify

Push to GitHub
New site from Git
Build command: pnpm build
Publish directory: dist

#Cloudflare Pages

Push to GitHub
Create new project
Build command: pnpm build
Build output: dist

#Environment Variables

For production, you may want to set:

SITE_URL=https://yourdomain.com

This ensures correct URLs in RSS feeds, sitemaps, and social cards.

#Performance Tips

Optimize images before uploading
Use WebP/AVIF formats
Minimize custom components in MDX
Enable compression on your host
Use a CDN for static assets

#Troubleshooting

#Build Fails

pnpm install  # Reinstall dependencies
rm -rf node_modules .astro
pnpm install
pnpm build

#Port Already in Use

pnpm dev -- --port 3000  # Use different port

#Hot Reload Not Working

Check file watcher limits (Linux)

echo fs.inotify.max_user_watches=524288 | sudo tee -a /etc/sysctl.conf
sudo sysctl -p

Try clearing cache

rm -rf .astro
pnpm dev

#Customization Ideas

Integrate with:

ConvertKit
Buttondown
Revue
Substack

#Add Search

Spaceship includes basic search. Enhance with:

Algolia
Pagefind
Fuse.js

#Custom Components

Create reusable components in src/components/ and use them in MDX:

import MyComponent from '@/components/MyComponent.svelte';

<MyComponent client:load />

#Getting Help

Documentation: Check this guide and How to Publish Posts
Issues: GitHub Issues
Discussions: GitHub Discussions

Happy blogging with Spaceship! 🚀