Complete Installation & Setup Guide

Introduction

Welcome to the complete installation guide! This tutorial will walk you through setting up this modern Astro blog from scratch. By the end, you’ll have a fully functional blog with dark mode, search, pagination, and more.

Quick Start

1. Clone the Repository

git clone https://github.com/yourusername/your-blog.git
cd your-blog

2. Install Dependencies

npm install

This will install all required packages including:

• Astro core framework
• Tailwind CSS for styling
• Pagefind for search
• Reading time plugin
• Remark/Rehype plugins

3. Start Development Server

npm run dev

Your blog is now running at http://localhost:4321 🎉

Project Structure

Understanding the project structure helps you navigate and customize effectively:

your-blog/
├── public/              # Static assets
│   ├── fonts/          # Custom fonts
│   ├── images/         # Images
│   └── robots.txt      # SEO crawler rules
├── src/
│   ├── components/     # Reusable components
│   │   ├── Header.astro
│   │   ├── Footer.astro
│   │   ├── TableOfContents.astro
│   │   ├── LinkButton.astro
│   │   └── SocialIcon.astro
│   ├── content/        # Content collections
│   │   ├── config.ts   # Content schema
│   │   └── posts/      # Blog posts (Markdown)
│   ├── layouts/        # Page layouts
│   │   ├── BaseLayout.astro
│   │   └── PostLayout.astro
│   ├── pages/          # Routes
│   │   ├── index.astro         # Homepage
│   │   ├── about.astro         # About page
│   │   ├── search.astro        # Search page
│   │   ├── posts/
│   │   │   ├── index.astro     # All posts
│   │   │   ├── [slug].astro    # Individual post
│   │   │   └── page/[page].astro  # Pagination
│   │   └── tags/
│   │       ├── index.astro     # All tags
│   │       └── [tag].astro     # Posts by tag
│   ├── styles/         # Global styles
│   │   └── global.css
│   ├── utils/          # Utility functions
│   │   └── reading-time.mjs
│   ├── config.ts       # Site configuration
│   └── constants.ts    # Constants (social links)
├── plugins/            # Markdown plugins
│   └── remark-admonitions.mjs
├── astro.config.mjs    # Astro configuration
├── package.json        # Dependencies
├── tailwind.config.mjs # Tailwind configuration
└── tsconfig.json       # TypeScript configuration

Configuration

Site Configuration

Edit src/config.ts to customize your site:

export const SITE = {
  title: "Your Blog Name",
  description: "Your blog description",
  url: "https://yoursite.com",
  author: "Your Name",
  showBackButton: true
};

Social Links

Update social media links in src/constants.ts:

export const SOCIALS = [
  {
    name: "Github",
    href: "https://github.com/yourusername",
    linkTitle: "Follow me on Github",
    icon: "github"
  },
  {
    name: "Twitter",
    href: "https://twitter.com/yourusername",
    linkTitle: "Follow me on Twitter",
    icon: "twitter"
  },
  {
    name: "LinkedIn",
    href: "https://linkedin.com/in/yourusername",
    linkTitle: "Connect with me on LinkedIn",
    icon: "linkedin"
  }
];

Share Buttons

Configure which social platforms appear on share buttons:

export const SHARE_LINKS = [
  {
    name: "Twitter",
    href: "https://twitter.com/intent/tweet?url=",
    linkTitle: "Share on Twitter",
    icon: "twitter"
  },
  {
    name: "Facebook",
    href: "https://www.facebook.com/sharer/sharer.php?u=",
    linkTitle: "Share on Facebook",
    icon: "facebook"
  },
  // Add or remove platforms as needed
];

Features Overview

✨ Dark Mode

Automatic theme switching with user preference persistence.

How it works:

• Detects system preference
• Remembers user choice via localStorage
• Toggle available in header
• Prevents flash of unstyled content

Customization: Edit colors in src/styles/global.css

:root {
  --color-accent: #ef4444;  /* Change accent color */
  --bg-primary: #ffffff;
  --text-primary: #1a1a1a;
}

:root.dark {
  --bg-primary: #0a0a0a;
  --text-primary: #e5e5e5;
}

🔍 Full-Text Search

Powered by Pagefind for instant client-side search.

Features:

• Instant search results
• Highlights matching text
• Works entirely offline after first load
• No backend required

Usage: Navigate to /search or use the search icon in header

📖 Table of Contents

Automatically generated sticky TOC for posts with 2+ headings.

How it works:

• Extracts H2 and H3 headings
• Generates anchor links
• Highlights current section
• Smooth scroll on click

Customization: Edit src/components/TableOfContents.astro

⏱️ Reading Time

Automatic estimation based on word count.

Formula: ~200 words per minute

Display: Shown in post header alongside date

🏷️ Tag System

Organize and filter posts by topics.

Features:

• Tag index page showing all tags
• Individual tag pages with filtered posts
• Tag counts
• Hover effects

Usage: Add tags to post frontmatter:

***
tags: ["javascript", "tutorial", "webdev"]
***

📄 Pagination

Clean pagination for post listings.

Configuration: 15 posts per page (customizable)

Routes:

• /posts - Page 1
• /posts/page/2 - Page 2
• /posts/page/3 - Page 3

Customization: Edit POSTS_PER_PAGE in src/pages/posts/index.astro

🎨 Admonitions

6 types of callout boxes for emphasis.

Types:

• :::note - General information (Blue)
• :::tip - Helpful suggestions (Green)
• :::info - Factual information (Cyan)
• :::warning - Cautions (Orange)
• :::danger - Critical warnings (Red)
• :::success - Positive outcomes (Green)

Usage: See Admonitions Guide

🔗 Social Share

Share buttons for major platforms.

Platforms:

• Twitter
• Facebook
• LinkedIn
• WhatsApp
• Telegram
• Copy link

Location: Below post content, above footer navigation

⬅️➡️ Post Navigation

Previous/Next post links for easy browsing.

Features:

• Chronological order
• Shows post titles
• Hover animations
• Mobile responsive

Customization

Colors & Themes

Edit src/styles/global.css:

:root {
  /* Accent color */
  --color-accent: #ef4444;
  
  /* Backgrounds */
  --bg-primary: #ffffff;
  --bg-surface: #f5f5f5;
  --bg-header: rgba(255, 255, 255, 0.8);
  
  /* Text */
  --text-primary: #1a1a1a;
  --text-secondary: #666666;
  
  /* Borders */
  --border-color: #e5e5e5;
}

Fonts

Adding custom fonts:

1. Place font files in public/fonts/
2. Update src/styles/global.css:

@font-face {
  font-family: 'YourFont';
  src: url('/fonts/YourFont.woff2') format('woff2');
  font-weight: 400;
  font-style: normal;
  font-display: swap;
}

body {
  font-family: 'YourFont', system-ui, sans-serif;
}

Navigation

Edit src/components/Header.astro:

const navItems = [
  { name: 'about', href: '/about' },
  { name: 'posts', href: '/posts' },
  { name: 'tags', href: '/tags' },
  { name: 'contact', href: '/contact' }, // Add new item
];

Building for Production

Local Build

Test your production build locally:

npm run build
npm run preview

Visit http://localhost:4321 to preview

Deployment

Vercel (Recommended)

1. Push code to GitHub
2. Import project in Vercel
3. Deploy with default settings

Automatic deployments on every push!

Netlify

1. Push code to GitHub
2. Import project in Netlify
3. Build settings:
   • Build command: npm run build
   • Publish directory: dist

GitHub Pages

# Build
npm run build

# Deploy dist folder

Post-Deployment Checklist

After deploying, complete these tasks:

1. Google Search Console

• Verify ownership (Guide)
• Submit sitemap
• Request indexing

2. SEO Setup

• Update src/config.ts with production URL
• Create public/favicon.svg
• Add Open Graph image
• Test with Google Rich Results

3. Analytics (Optional)

• Set up Google Analytics
• Configure Vercel Analytics
• Add privacy policy

4. Performance

• Test with PageSpeed Insights
• Optimize images
• Check mobile responsiveness

Troubleshooting

Build Errors

“Module not found”

rm -rf node_modules package-lock.json
npm install

TypeScript errors

npm run build -- --verbose

Search Not Working

Fix:

npm run build
npm run preview

Reading Time Not Showing

Ensure plugin is enabled in astro.config.mjs:

import { remarkReadingTime } from './src/utils/reading-time.mjs';

export default defineConfig({
  markdown: {
    remarkPlugins: [
      remarkReadingTime  // ← Must be here
    ]
  }
});

Then rebuild:

npm run build

Dark Mode Not Persisting

Check localStorage:

// In browser console
localStorage.getItem('theme')

Should return 'dark' or 'light'

Advanced Features

Custom Pages

Create new pages in src/pages/:

***
import BaseLayout from '../layouts/BaseLayout.astro';
import Header from '../components/Header.astro';
import Footer from '../components/Footer.astro';
***

<BaseLayout title="New Page">
  <Header />
  <main>
    <h1>Your Content</h1>
  </main>
  <Footer />
</BaseLayout>

Content Collections

Add new collections in src/content/config.ts:

const projectsCollection = defineCollection({
  type: 'content',
  schema: z.object({
    title: z.string(),
    description: z.string(),
    link: z.string().url(),
  })
});

export const collections = {
  posts: postsCollection,
  projects: projectsCollection,  // New collection
};

API Routes

Create API endpoints in src/pages/api/:

// src/pages/api/hello.ts
export async function GET() {
  return new Response(JSON.stringify({
    message: 'Hello World'
  }), {
    headers: { 'Content-Type': 'application/json' }
  });
}

Performance Tips

Image Optimization

Use Astro’s Image component:

***
import { Image } from 'astro:assets';
import myImage from '../assets/image.jpg';
***

<Image src={myImage} alt="Description" />

Code Splitting

Astro automatically splits code. No configuration needed!

Lazy Loading

Images are lazy-loaded by default.

Getting Help

Resources

• 📚 Astro Documentation
• 💬 Astro Discord
• 🐛 GitHub Issues

Common Issues

Check the Troubleshooting section above or search existing issues.

Community Support

Join the Astro Discord for real-time help from the community!

Next Steps

Now that your blog is installed:

1. ✅ Create your first post
2. ✅ Learn about admonitions
3. ✅ Set up Google verification
4. ✅ Customize colors and fonts
5. ✅ Deploy to production