MinimalPress

A clean, minimalist blog theme built with Astro and vanilla CSS. Perfect for developers, writers, and content creators who want a fast, accessible, and beautiful blog.

🎨 Vibe-coded and inspired by Obsidian Minimal Theme - bringing the clean, focused aesthetic of Obsidian to the web.

Demo

✨ Features

Core Features

⚡ Lightning Fast - Static site generation with Astro (100/100 Lighthouse scores)
🎨 Beautiful Design - Clean, minimal interface focused on readability
🌓 Dark/Light Theme - System preference detection with manual toggle
📱 Fully Responsive - Mobile-first design that works on all devices
🔍 Full-text Search - Fast client-side search (coming soon)
📊 Reading Progress - Visual progress bar and reading time estimates

Content Features

📝 Markdown Support - Write in Markdown with full frontmatter support
🎯 SEO Optimized - Meta tags, Open Graph, Twitter Cards, sitemap, robots.txt
📖 Table of Contents - Auto-generated with scroll spy navigation
🔗 Smart Linking - Related posts and internal link suggestions
🏷️ Tag System - Organize and filter content by tags
🖼️ Image Optimization - Responsive images with lazy loading and lightbox

Developer Features

🛠️ TypeScript - Full type safety throughout the codebase
🎯 Focus Mode - Distraction-free reading experience
♿ Accessible - WCAG 2.1 AA compliant with full keyboard navigation
🚀 Performance - Optimized for Core Web Vitals
📦 Component Based - Modular architecture for easy customization
🔧 Easy Configuration - Central config file for all settings

🚀 Quick Start

Prerequisites

Node.js 18.14.1 or higher
npm or yarn package manager

Installation

Use this template (recommended)

# Clone the repository
git clone https://github.com/yourusername/minimalpress.git my-blog
cd my-blog

# Remove git history and start fresh
rm -rf .git
git init

Install dependencies
```
npm install
# or
yarn install
```
Start development server
```
npm run dev
# or
yarn dev
```
Open http://localhost:4321 to see your blog.

Build for production

npm run build
npm run preview # Preview the production build

📁 Project Structure

minimalpress/
├── src/
│   ├── components/          # Reusable Astro components
│   │   ├── Breadcrumb.astro
│   │   ├── ImageGallery.astro
│   │   ├── MobileMenu.astro
│   │   ├── OptimizedImage.astro
│   │   ├── RelatedPosts.astro
│   │   ├── Sidebar.astro
│   │   ├── TableOfContents.astro
│   │   ├── ThemeToggle.astro
│   │   └── ...
│   ├── content/
│   │   ├── config.ts        # Content collection schema
│   │   └── blog/            # Blog posts (Markdown/MDX)
│   │       ├── getting-started.md
│   │       └── guides/
│   │           └── configuration.md
│   ├── layouts/             # Page layouts
│   │   ├── BaseLayout.astro # Base HTML structure
│   │   └── BlogLayout.astro # Blog post layout
│   ├── pages/               # File-based routing
│   │   ├── index.astro      # Homepage/blog listing
│   │   ├── about.astro      # About page
│   │   └── blog/
│   │       └── [...slug].astro # Dynamic blog routes
│   ├── styles/
│   │   └── global.css       # Global styles & CSS variables
│   ├── utils/               # Utility functions
│   │   ├── navigation.ts    # Navigation helpers
│   │   └── seo.ts          # SEO utilities
│   └── config.ts           # Site configuration
├── public/                 # Static assets (images, fonts)
├── astro.config.mjs       # Astro configuration
├── package.json
└── tsconfig.json          # TypeScript configuration

✍️ Writing Content

Creating a Blog Post

Create new posts in src/content/blog/:

---
title: "Getting Started with MinimalPress"
description: "Learn how to create your first blog post"
date: 2024-01-20
tags: ["tutorial", "astro", "markdown"]
image: "/images/getting-started.jpg" # Optional cover image
author: "Your Name" # Optional, defaults to config
draft: false # Set to true to hide from production
canonical: "https://original-post-url.com" # Optional canonical URL
---

Your content here in **Markdown** format.

## Table of contents is automatically generated

Code blocks with syntax highlighting:

```javascript
const greeting = "Hello, MinimalPress!";
console.log(greeting);
```

Organizing Content

You can organize posts in folders:

src/content/blog/
├── getting-started.md
├── tutorials/
│   ├── astro-basics.md
│   └── markdown-guide.md
└── thoughts/
    └── why-minimal-design.md

Folders become part of the URL: /blog/tutorials/astro-basics

Frontmatter Options

Field	Type	Required	Description
`title`	string	Yes	Post title
`description`	string	Yes	Short description (meta description)
`date`	date	Yes	Publication date (YYYY-MM-DD)
`tags`	string[]	No	Array of tags
`image`	string	No	Cover image URL
`author`	string	No	Override default author
`draft`	boolean	No	Hide from production build
`updated`	date	No	Last update date
`canonical`	string	No	Canonical URL for cross-posted content
`noindex`	boolean	No	Exclude from search engines

🎨 Customization

Site Configuration

Edit src/config.ts to customize your site:

export const siteConfig = {
  name: "My Blog",
  description: "My personal blog about web development",
  url: "https://myblog.com",
  
  author: {
    name: "Your Name",
    email: "[email protected]",
    twitter: "@yourhandle",
    github: "yourusername",
    linkedin: "yourprofile",
  },
  
  // Navigation menu
  navigation: [
    { name: "Home", href: "/" },
    { name: "Blog", href: "/blog" },
    { name: "About", href: "/about" },
    { name: "Contact", href: "/contact" },
  ],
  
  // Features
  features: {
    darkMode: true,
    search: true,
    tableOfContents: true,
    readingTime: true,
  },
  
  // Blog settings
  blog: {
    postsPerPage: 10,
    sortBy: "date", // "date" or "title"
    sortOrder: "desc", // "asc" or "desc"
  }
};

Styling & Theming

MinimalPress uses vanilla CSS with CSS variables for a lightweight, customizable styling system.

Colors

Edit CSS variables in src/styles/global.css:

:root {
  /* Light theme */
  --bg: #ffffff;
  --text: #333333;
  --accent: #007acc;
  /* ... more variables */
}

.dark {
  /* Dark theme */
  --bg: #1a1a1a;
  --text: #e4e4e7;
  --accent: #4facfe;
  /* ... more variables */
}

Typography

Customize typography in src/styles/global.css:

.markdown-content {
  font-size: 18px;
  line-height: 1.8;
  letter-spacing: 0.01em;
}

.markdown-content h1 {
  font-size: 36px;
  font-weight: 700;
  margin: 48px 0 24px 0;
}

Adding Pages

Create new pages in src/pages/:

---
// src/pages/contact.astro
import BaseLayout from '../layouts/BaseLayout.astro';
---

<BaseLayout title="Contact" description="Get in touch">
  <h1>Contact Me</h1>
  <p>Your content here...</p>
</BaseLayout>

Components

Create reusable components in src/components/:

---
// src/components/MyComponent.astro
export interface Props {
  title: string;
  variant?: 'primary' | 'secondary';
}

const { title, variant = 'primary' } = Astro.props;
---

<div class={`component ${variant}`}>
  <h3>{title}</h3>
  <slot />
</div>

🚀 Deployment

Build Command

npm run build

Deploy to Vercel

Deploy to Netlify

Manual Deployment

Build the site
```
npm run build
```
Deploy the dist/ folder to your hosting provider:
- Vercel: vercel --prod
- Netlify: netlify deploy --prod
- GitHub Pages: Use GitHub Actions
- Any static host: Upload dist/ contents

Environment Variables

Create a .env file for local development:

# Analytics (optional)
PUBLIC_GA_ID=G-XXXXXXXXXX
PUBLIC_PLAUSIBLE_DOMAIN=yourdomain.com

# Comments (optional)
PUBLIC_GISCUS_REPO=username/repo
PUBLIC_GISCUS_REPO_ID=XXX
PUBLIC_GISCUS_CATEGORY=Comments

📋 Commands Reference

Command	Action
`npm run dev`	Start development server at `localhost:4321`
`npm run build`	Build production site to `./dist/`
`npm run preview`	Preview production build locally
`npm run astro ...`	Run Astro CLI commands
`npm run astro add`	Add integrations (e.g., `astro add sitemap`)
`npm run astro check`	Check for TypeScript errors

🔧 Advanced Configuration

Adding Integrations

# Add sitemap
npm run astro add sitemap

# Add RSS feed
npm run astro add rss

# Add image optimization
npm run astro add image

Custom Fonts

Add fonts to src/layouts/BaseLayout.astro:

<link rel="preconnect" href="https://fonts.googleapis.com">
<link href="https://fonts.googleapis.com/css2?family=Inter:wght@400;600;700&display=swap" rel="stylesheet">

Update CSS in src/styles/global.css:

body {
  font-family: 'Inter', -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
}

Analytics

Add analytics in src/layouts/BaseLayout.astro:

<!-- Google Analytics -->
{import.meta.env.PUBLIC_GA_ID && (
  <script async src={`https://www.googletagmanager.com/gtag/js?id=${import.meta.env.PUBLIC_GA_ID}`}></script>
  <script>
    window.dataLayer = window.dataLayer || [];
    function gtag(){dataLayer.push(arguments);}
    gtag('js', new Date());
    gtag('config', import.meta.env.PUBLIC_GA_ID);
  </script>
)}

🐛 Troubleshooting

Common Issues

Build fails with "Cannot find module"

rm -rf node_modules package-lock.json
npm install

Images not loading

Place images in public/ folder
Reference as /image.jpg (not ./image.jpg)

Styles not updating

Clear browser cache
Restart dev server
Check CSS variables in global.css

404 on deployed site

Check base in astro.config.mjs if deploying to subdirectory
Ensure all routes are generated during build

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Fork the repository
Create your feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

📝 License

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

🙏 Acknowledgments

Built with Astro
Styled with vanilla CSS and CSS variables
Icons from Heroicons
Inspired by minimal design principles

Made with ❤️ by the MinimalPress community

GitHub • Demo • Issues

Name		Name	Last commit message	Last commit date
Latest commit History 11 Commits
.claude		.claude
.github/workflows		.github/workflows
.vscode		.vscode
public		public
src		src
.gitignore		.gitignore
CLAUDE.md		CLAUDE.md
README.md		README.md
astro.config.mjs		astro.config.mjs
design-guide.json		design-guide.json
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json

serrexlabs/minimal_press

Folders and files

Latest commit

History

Repository files navigation