Getting Started

Getting Started

Table of Contents

• Requirements
• Installation
• Running the project
• Available commands
• Project structure
• First steps after setup

Requirements

• Node.js ≥ 22.12.0
• pnpm (recommended) — or npm, yarn, or bun

Installation

Option 1: Create from template (recommended)

# pnpm
pnpm create astro@latest --template satnaing/astro-paper

# npm
npm create astro@latest -- --template satnaing/astro-paper

# yarn
yarn create astro --template satnaing/astro-paper

# bun
bun create astro@latest -- --template satnaing/astro-paper

This runs the Astro setup wizard, which handles cloning the template and installing dependencies.

Option 2: Clone from GitHub

git clone https://github.com/satnaing/astro-paper.git my-blog
cd my-blog
pnpm install

Option 3: Use as a GitHub template

Go to https://github.com/satnaing/astro-paper and click "Use this template" to create your own repository on GitHub.

Running the Project

# Start the dev server at http://localhost:4321
pnpm dev

# Build for production
pnpm build

# Preview the production build locally
pnpm preview

Available Commands

Command	Action
pnpm install	Install dependencies
pnpm dev	Start local dev server at localhost:4321
pnpm build	Type-check, build, run Pagefind indexing, copy search index to public/pagefind/
pnpm preview	Preview the production build locally
pnpm sync	Generate TypeScript types for Astro modules
pnpm astro ...	Run Astro CLI commands (e.g. astro add, astro check)
pnpm format	Format code with Prettier
pnpm lint	Lint code with ESLint

Note: pnpm build runs both astro build and the Pagefind indexer. The search index is required for the search feature to work in production.

Project Structure

/
├── public/
│   ├── pagefind/          # auto-generated by pnpm build; do not edit
│   ├── favicon.svg
│   └── default-og.jpg     # fallback OG image
├── src/
│   ├── assets/
│   │   ├── icons/         # SVG icons including social icons
│   │   └── images/        # static images used in posts/layouts
│   ├── components/        # Astro components (Header, Footer, Card, etc.)
│   ├── content/
│   │   ├── pages/         # standalone pages (e.g. about.md)
│   │   └── posts/         # blog posts (.md and .mdx files)
│   ├── i18n/              # UI string translations and date formatting
│   ├── layouts/           # page layouts (Layout.astro, PostLayout.astro)
│   ├── pages/             # Astro route pages (index, tags, archives, etc.)
│   ├── scripts/           # client-side scripts (theme toggle)
│   ├── styles/            # CSS (theme.css, global.css, typography.css)
│   ├── types/             # TypeScript types including config types
│   ├── utils/             # helper utilities
│   ├── config.ts          # internal resolved config (do not edit directly)
│   └── content.config.ts  # Astro content collection schema
├── astro-paper.config.ts  # your site configuration (edit this)
└── astro.config.ts        # Astro framework configuration

Key directories

• src/content/posts/ — all your blog posts go here. Supports .md and .mdx.
• src/content/pages/ — standalone content pages like about.md.
• astro-paper.config.ts — the main file you edit to configure your site. See Configuration.
• src/styles/theme.css — color scheme CSS variables. See Customization.
• public/ — static assets served as-is (no processing). Place your default-og.jpg here.

First Steps After Setup

1. Configure your site — Open astro-paper.config.ts and update site.url, site.title, site.description, site.author, and socials. See Configuration for all options.

2. Replace the default OG image — Swap public/default-og.jpg with your own fallback OG image (recommended size: 1200×640 px), or leave features.dynamicOgImage enabled to generate OG images automatically.

3. Update the About page — Edit src/content/pages/about.md with your own content.

4. Delete the sample posts — Remove the example posts in src/content/posts/ and add your own.

5. Add your favicon — Replace public/favicon.svg with your own.

6. Run a build — Run pnpm build to verify everything compiles, then pnpm preview to see the production site.