Bitdoze Astro Blog Theme

A modern, responsive blog theme for Astro with support for tags, categories, series, and featured posts. 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 - One logo-anchored accent ramp and swappable font tokens drive links, buttons, focus rings, and chips, and one config file (src/config/site.ts) owns identity, hero, homepage, footer, and page copy
• 🔍 SEO Optimized - Meta tags, Open Graph, and JSON-LD
• 📝 Blog Ready - Support for posts, categories, tags, and series
• ⭐ Featured Posts - An optional featured flag surfaces editor's picks in a three-column homepage grid
• 🧩 Homepage Sections - Hero, Featured, Latest, Learning paths, Explore, and Popular Topics, with the hero, featured, and latest posts deduped automatically
• 🔎 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 - Self-hosted display face for headings, system stack for body copy, balanced prose 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 (requires JavaScript; the index covers roughly the first 4,000 characters of each post body — full-text indexing is deferred, see src/pages/search.json.ts)
• Author Card: Display author information
• Post Card: Display post previews in lists, used by Latest, Featured, archives, and search
• Homepage Sections: FeaturedPosts, LearningPaths, and PopularTopics compose the homepage from real content and the homepage flags in src/config/site.ts
• Tag/Category Cloud: Display and filter by tags or categories

Getting Started

Work through the tasks below in order. Each step links to the reference section with the details.

1. Preview the theme. Run npm install && npm run dev and open http://localhost:4321. Try the theme toggle, a mobile viewport, the Featured Posts grid, and the MDX widget examples in src/content/posts/artificial-intelligence-guide.mdx, src/content/posts/vps-hosting-docker-and-caddy.mdx, and src/content/posts/developer-seo-checklist.mdx.
2. Create your site. The fastest path is GitHub's Use this template button; alternatively clone over HTTPS (git clone https://github.com/bitdoze/bitdoze-astro-theme.git my-blog). Install dependencies on Node 22.12 or newer (see Installation).
3. Rebrand. Update src/config/site.ts — identity, hero, homepage sections, footer titles, and listing/utility page copy — then src/config/menu.json and src/config/social.json (see Configuration).
4. Create your first content. Add a post, an author, a series, and an ordinary page (see Creating Content and Adding New Pages).
5. Remove demo content. Delete the demo posts, authors, and pages you do not need; empty collections render as empty lists rather than failing. The About page is a dedicated content entry at src/content/about/index.md — replace it rather than leaving the placeholder.
6. Configure contact, origin, and SEO defaults. Set a real contact endpoint (see Contact form), point SITE_URL at your production origin, and review the metadata defaults in src/config/site.ts.
7. Deploy and smoke-test. Build and deploy (see Deployment), then verify navigation, search, RSS, and the custom 404 page on the live host.
8. Update from a release. Read CHANGELOG.md before pulling a new version; releases call out any changed configuration or content contracts.

Prerequisites

• Node.js 22.12.0 or newer (declared in package.json engines and pinned in .node-version)
• npm 10.8.2 or newer

The theme targets Astro 7.x. When upgrading Astro, check CHANGELOG.md and update the official integrations together.

Installation

1. Create your site from this theme — use GitHub's Use this template button, or clone over HTTPS:

   git clone https://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. Content and copy are not scattered through components: site.ts is the single source for headings, sublines, section titles, and calls to action, and the sibling files own navigation, social links, and contact details.

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:
     • Identity: title, description, author, brandName, logo, and logo dimensions.
     • Hero: hero.title, hero.titleAccent, hero.primaryCta / hero.secondaryCta, hero.statsLabels, and heroDescription.
     • Homepage: the showFeaturedPosts / showTaxonomyCards / showPopularTopics toggles, plus section copy and limits (homepage.featured, homepage.latest, homepage.learningPaths), configured tags (homepage.popularTopics), and the Explore cards (homepage.explore).
     • Footer: column titles (footer.exploreTitle, footer.latestTitle).
     • Pages: headings, meta descriptions, and visible sublines for Blog, Categories, Tags, Authors, Series, Contact, Search, and 404 (pages.*).
     • ogImage, postsPerPage, favicons, and the noindex policy.
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.
   • The default "#" action keeps the form disabled with a visible notice — see Contact form.

Homepage

The homepage is composed from real content in this order:

1. Hero — the newest published post, with proof counts and entry points.
2. Featured Posts — up to homepage.featured.limit posts flagged featured: true in a three-column grid, newest first (the hero post is skipped).
3. Popular Topics — configured tags with their most recent posts in a full-width band. Columns prefer posts not already shown in the hero or featured grid, then backfill so they still render on small archives; a post never appears in two columns.
4. Latest Articles — the newest remaining posts, excluding series and featured entries, with a link to the full archive.
5. Learning paths — series in position order plus the largest categories; each path needs at least two entries, with a link to all series.
6. Explore Content — links to categories, authors, and tags.

The hero, Popular Topics, and Learning paths render as full-width tinted bands, so the page alternates between white and tinted sections; the footer continues the same surface. Every section's copy, limits, tags, and toggles live in homepage in src/config/site.ts; the header and footer navigation live in src/config/menu.json, and social and contact details in src/config/social.json and src/config/config.json.

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
featured: true
---

Your post content goes here...

Set featured: true to surface a post in the homepage Featured Posts grid (up to three, newest first, never repeating the hero post). The section is controlled by homepage.showFeaturedPosts in src/config/site.ts.

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.
  • Brand tokens: --color-accent-50…950 is the brand ramp (anchored on the logo azure) used for links, buttons, focus rings, chips, and text selection, and --font-display is the heading face (Bricolage Grotesque, self-hosted in Layout.astro). Body copy stays on the system stack. Override either token in the @theme block to rebrand.
  • 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):

Tailwind CSS v4 is CSS-first and does not automatically detect a tailwind.config.js file. For most customization, stay in src/styles/global.css and use the CSS-first @theme directive:

@theme {
  --color-brand: #009cef;
}

If you need a legacy JavaScript config (for example, a Tailwind v3 plugin that requires JS configuration), load it explicitly with @config in src/styles/global.css:

@import "tailwindcss";
@config "../../tailwind.config.js";

Refer to the official Tailwind CSS documentation for details on @theme and @config.

Adding New Pages

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

Contact form

The contact page renders a deliverable form only after you configure a real endpoint. While params.contact_form_action in src/config/config.json stays at its default "#", the page shows a "not configured" notice and the submit button is disabled, so visitors cannot submit messages into the void.

To go live:

1. Set params.contact_form_action to an endpoint that accepts POST requests — your own backend or a form service.
2. Add only the public address, email, and phone details you want displayed.

This theme is static and ships no mailer. Handling submissions, success messages, and error recovery is the responsibility of the endpoint you configure.

Deployment

Build your site for production:

npm run build

The static output is written to the dist/ directory, ready to deploy to any static hosting platform. Build and serve on Node.js 22.12.0 or newer, matching the prerequisites.

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.

Three things to configure on your host before going live:

• Root-domain or subpath hosting. Root deployments work out of the box. Subpath deployments (for example example.com/blog/) are supported through Astro's base setting — navigation, taxonomy links, pagination, favicons, RSS autodiscovery, and search are base-aware, and this is covered by a /theme/ smoke build. One caveat: absolute links you write yourself inside Markdown content (for example [Blog](/blog/)) are not rewritten; prefer root-relative content links on root deployments.
• Custom 404. The theme ships src/pages/404.astro (content from src/content/pages/404.md). Configure your host to serve it for unknown routes with a real 404 status; astro preview behavior is not proof for every provider.
• Cache headers. The Cache-Control header the search endpoint sets on its response is not portable across CDNs; most static hosts strip response headers from flat files. Configure caching for HTML, hashed assets, and /search.json in your host's settings.

Performance

The theme stays lean by default: fully static pages, no client framework runtime, a system font stack for body copy plus one self-hosted variable display face for headings, syntax highlighting done at build time, responsive covers that lazy-load in cards (the article cover loads eagerly), and a click-to-load facade for YouTube embeds instead of immediate iframes.

Budget snapshot of the demo build, September 2026 (gzip estimates): shared CSS ~13 KB, and the client-side search bundle ~11 KB plus its JSON index (~33 KB for the 21-post demo — the index grows with the number and length of your posts). The search page carries that bundle and is heavier than ordinary pages. These are build-output snapshots, not Core Web Vitals results; measure your own deployment.

Security

Repository content — posts, pages, MDX, and configuration — is a trusted build input: it runs at build time like any other code in the project. Content from an external CMS or user submissions does not share that trust and needs its own validation and ingestion boundary before it reaches a build. To report a security issue, see SECURITY.md.

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