Bitdoze Astro Blog Theme

A modern, responsive blog theme for Astro with support for tags, categories, and series. This theme is designed to be fast, SEO-friendly, and easy to customize.

Features

• 🚀 Built with Astro - Benefit from Astro's speed and flexibility
• 📱 Fully Responsive - Looks great on all devices
• 🎨 Customizable - Easy to adapt to your brand
• 🔍 SEO Optimized - Meta tags, Open Graph, and JSON-LD
• 📝 Blog Ready - Support for posts, categories, tags, and series
• 🔎 Search Functionality - Client-side search with Fuse.js
• 📊 Pagination - For blog posts, categories, tags, and authors
• 📰 RSS Feed - Automatically generated RSS feed
• 🗺️ Sitemap - Automatically generated sitemap
• 🖋️ MDX Support - Use components in your markdown
• 🔤 Typography - Beautiful typography with Tailwind CSS
• 🌙 Icons - Easy icon usage with Astro Icon
• 💡 FOUC Prevention - Inline scripts to minimize flash of unstyled content and theme inconsistencies on load.

Project Structure

├── public/             # Static assets
├── src/
│   ├── assets/         # Images and other assets
│   ├── config/         # Site configuration
│   ├── content/        # Content collections (blog posts, authors, etc.)
│   ├── layouts/        # Layout components
│   ├── pages/          # Page components and routes
│   ├── styles/         # Global styles
│   └── utils/          # Utility functions
├── astro.config.mjs    # Astro configuration
├── package.json        # Dependencies and scripts

Key Directories and Files

• src/config/: Contains configuration files for the site, menus, and social links
• src/content/: Contains all content collections (blog posts, authors, pages)
• src/layouts/: Contains layout components used throughout the site
• src/pages/: Contains all page components and defines the routing structure

Components

The theme includes several reusable components:

• Layout.astro: Main layout component with header and footer
• PostLayout.astro: Layout for blog posts with metadata and content
• Header/Footer: Navigation and site information
• Pagination: For navigating through multiple pages of content
• Search: Client-side search functionality
• Author Card: Display author information
• Post Card: Display post previews in lists
• Tag/Category Cloud: Display and filter by tags or categories

Getting Started

Prerequisites

• Node.js 22.12.0 or newer
• npm 10.8.2 or newer

Installation

1. Clone this repository:

   git clone git@github.com:bitdoze/bitdoze-astro-theme.git my-blog
   cd my-blog

2. Install dependencies:

   npm install

3. Start the development server:

   npm run dev

4. Open your browser and visit http://localhost:4321

Configuration

Tailor the theme to your needs by updating the following configuration files:

1. Site URL:
   • Set the SITE_URL environment variable in production. It falls back to https://www.bitdoze.com for local builds.
2. Primary Site Metadata & Settings:
   • Update src/config/site.ts for essential site details such as:
     • title: The main title of your site.
     • description: A brief description for SEO and metadata.
     • author: Default author name.
     • brandName, logo, and logo dimensions.
     • Hero and footer descriptions.
     • ogImage: Path to your default OpenGraph image.
     • postsPerPage: Number of posts to display on paginated pages.
3. Menus:
   • Modify src/config/menu.json to define navigation links for the header and footer.
4. Social Media Links:
   • Update src/config/social.json with your social media profile URLs.
5. Contact Configuration (src/config/config.json):
   • Set params.contact_form_action to your form endpoint.
   • Add only the public address, email, and phone details you want displayed.

Creating Content

Blog Posts

Create a new .md or .mdx file in src/content/posts/ with the following frontmatter:

---
title: "Your Post Title"
meta_title: "SEO Title (optional)"
description: "Post description for SEO"
date: 2023-06-01
image: "../../assets/images/your-image.jpg"
authors: ["author-id"]
categories: ["category-name"]
tags: ["tag1", "tag2"]
series:
  name: "Series Name"
  position: 1
slug: "optional/custom-path"
canonical: "https://example.com/original-article/"
draft: false
---

Your post content goes here...

Authors

Create a new .md file in src/content/authors/ with the following frontmatter:

---
title: "Author Name"
meta_title: "Author Name - Astro Blog Theme"
image: "../../assets/images/authors/author-image.jpg"
description: "Author description"
social:
  facebook: "https://facebook.com/username"
  twitter: "https://twitter.com/username"
  website: "https://example.com"
---

Author bio goes here...

Customization

Styling

This theme uses Tailwind CSS v4 for styling, which emphasizes a CSS-first, minimal-configuration approach.

Key Styling Files:

• src/styles/global.css: This is the central file for Tailwind CSS setup and custom styles.

  • Tailwind's core styles (base, components, utilities) are imported via @import "tailwindcss";.
  • The @tailwindcss/typography plugin is included using @plugin "@tailwindcss/typography";.
  • You can customize the theme by modifying the CSS variables defined in this file, which control colors, fonts, and other aspects.
  • You can also add your own custom CSS rules here.

• astro.config.mjs: The @tailwindcss/vite plugin is integrated here, but typically requires no direct configuration for v4 unless you have very specific needs.

Advanced Customization (Optional):

While most styling can be managed through src/styles/global.css, if you need to make advanced Tailwind customizations (e.g., adding complex custom themes, other specific Tailwind plugins that require JS configuration, or modifying Tailwind's default settings extensively), you can create a tailwind.config.js file in the project root. The @tailwindcss/vite plugin should automatically detect and use this file. Refer to the official Tailwind CSS documentation for details on tailwind.config.js options.

Adding New Pages

Create a new .astro file in the src/pages/ directory. The file path will determine the URL.

Deployment

Build your site for production:

npm run build

Run the complete local verification suite:

npm run verify

This runs Astro type checking, unit tests, and the production build. Draft and future-dated posts are excluded from routes, search, RSS, series navigation, and homepage widgets.

The built site will be in the dist/ directory, ready to be deployed to your favorite hosting platform.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

• Built with Astro
• Styled with Tailwind CSS
• Icons from Astro Icon
• Search functionality with Fuse.js