🌻 Bloomfolio

A modern, customizable portfolio template built with Astro 7 and DaisyUI 5. A beautiful, fast, and highly customizable portfolio template for developers, designers, and creatives.

✨ Features

🎨 6 Built-in Themes - Light, Dark, Synthwave, Retro, Valentine, and Dim
📝 6 Content Collections - Blog, Projects, Work, Education, Hackathons, and About
🎨 Keystatic CMS - Visual content editor with live preview, GitHub integration, and Astro 7 support
🔒 Type-Safe Content - Full TypeScript support with validated schemas
📱 Fully Responsive - Mobile-first design with DaisyUI components
⚡ Fast & Optimized - Server rendering with automatic image optimization
🎭 Smooth Transitions - Page transitions using Astro's View Transitions API
📦 Markdoc Support - Enhanced markdown with custom Spotify, YouTube, and Twitter tags
🎯 Configuration-Driven - Customize everything through a central config file
🌸 FAB Flower Menu - Expandable floating action button for extra links (desktop)
📱 Mobile Dock Navigation - Bottom navigation bar for mobile devices
⭐ Featured Projects - Highlight your best work on the homepage
🏷️ Project Categories - Organize projects by custom categories (managed via Keystatic CMS)
📐 3 Projects Page Layouts - Grid, Horizontal Tabs, or Sidebar layout (configurable in General Settings)
🧭 Content Sidebar - Sticky H1/H2 article navigation with collapsible H3 sublevels, global defaults, per-page overrides, and a responsive mobile outline
📝 Blog Drafts - Keep unfinished posts in Keystatic without listing them or exposing their public page
🔗 Inline Links in Hero - Add clickable links inside Hero title and description using [link:<url>]text[/link] syntax
🎨 Modern Stack - Astro 7 + Vite 8 + Tailwind CSS 4 + DaisyUI 5 + TypeScript 6
🔍 SEO Optimized - Meta tags, Open Graph, and semantic HTML
♿ Accessible - Built with accessibility in mind

🚀 Quick Start

Prerequisites

Node.js 22.12.0 or newer
npm, pnpm, or yarn

Astro 7 requires Node.js 22.12.0 or newer. The included .nvmrc selects that minimum version, and @keystatic/astro 5.2 declares Astro 7 compatibility.

Astro 7 uses Vite 8 and its stricter Rust compiler. Run npm run check and npm run build after changing components or content to catch invalid templates and schema errors.

Installation

# Clone the repository
git clone https://github.com/lauroguedes/bloomfolio.git

# Navigate to the project directory
cd bloomfolio

# Install dependencies
npm install

# Start the development server
npm run dev

Visit http://localhost:4321 to see your portfolio!

📋 Commands

All commands are run from the root of the project:

Command	Action
`npm install`	Install dependencies
`npm run dev`	Start dev server at `localhost:4321`
`npm run build`	Build production site to `./dist/`
`npm run preview`	Preview production build locally
`npm run check`	Run TypeScript, Astro, and content checks
`npm run astro ...`	Run Astro CLI commands

⚙️ Configuration

All site configuration is managed through Keystatic CMS or by editing content files directly in src/content/.

Using Keystatic CMS

Start the development server: npm run dev
Navigate to http://localhost:4321/keystatic
Edit General Settings to configure:
- Theme selector (dropdown vs toggle)
- Section visibility
- Extra links (FAB & Dock)
- Content sidebar visibility and left/right position

Section Visibility

Control which sections appear on your homepage through General Settings in Keystatic:

About section
Projects showcase (shows up to 3 featured projects)
Blog posts (shows 3 most recent)
Work experience timeline
Education history
Hackathon participation
Contact section

The Hero section is always visible.

Project Categories

Organize your projects by custom categories. Categories are managed via Keystatic CMS as a dedicated collection:

Go to /keystatic → Project Categories
Create categories with a name, description, emoji icon, and sort order
When editing a Project, select its category from the dropdown

Three default categories are included: 🤖 AI Made, 🚀 Real Projects, 🧪 Experiments.

On the /projects page, projects are grouped under their category heading. Uncategorized projects appear in an "Other" section.

Projects Page Layout

Choose from 3 layout styles for the projects listing page in General Settings → Projects Page Layout:

Layout	Description
Grid (default)	Stacked category sections with card grids
Horizontal Tabs	DaisyUI `tabs-border` with an All tab followed by category tabs
Sidebar	DaisyUI `menu` with an All item followed by category items

Content Sidebar

Blog posts and project detail pages automatically build an On this page menu from H1, H2, and H3 headings. H3 links are grouped beneath their nearest H2 and start collapsed; use the chevron beside an H2 to reveal them. On desktop the menu stays sticky beside the article and scrolls internally when it reaches its maximum height. On mobile it becomes a compact, collapsible outline above the content.

Configure the defaults in General Settings:

Show Content Sidebar: enabled by default
Content Sidebar Position: right by default; left is also available

Each Blog Post and Project includes Override Global Content Sidebar in Keystatic. Enable it to replace both global values for that page. When editing files manually, use:

contentSidebar:
  discriminant: true
  value:
    show: true
    position: left

Omit contentSidebar to use the global settings.

Inline Links in Hero

You can add clickable links inside the Hero section's Title and Description fields using a simple syntax:

[link:<url>]visible text[/link]

Example:

Astro Portfolio Template built with [link:https://daisyui.com]🌼 DaisyUI[/link]

Renders as: Astro Portfolio Template built with 🌼 DaisyUI

Theme Settings

Choose between a theme selector dropdown or a simple light/dark toggle in General Settings.

Available Themes: light, dark, synthwave, retro, valentine, dim

Extra Links (FAB Flower & Dock)

Configure the floating action button (desktop) and mobile dock navigation:

extraLinks:
  - link: /blog/guide
    icon: BookOpen
    label: Guide
    displayOn: both    # Options: both, dock, fab
  - link: /resume.pdf
    icon: FileText
    label: Resume
    displayOn: fab     # Only show on desktop FAB

The displayOn option controls where each link appears:

both - Shows on both FAB (desktop) and Dock (mobile)
fab - Only shows on the floating action button (desktop)
dock - Only shows on the bottom dock (mobile)

📂 Project Structure

bloomfolio/
├── public/              # Static assets
│   └── favicon.svg
├── src/
│   ├── assets/         # Images and media
│   │   └── bloomfolio.png
│   ├── components/     # Reusable components
│   │   ├── About.astro
│   │   ├── Blog.astro
│   │   ├── BlogCard.astro
│   │   ├── Contact.astro
│   │   ├── Dock.astro        # Mobile bottom navigation
│   │   ├── FabFlower.astro   # Desktop floating action button
│   │   ├── Hackathons.astro
│   │   ├── Hero.astro
│   │   ├── ProjectCard.astro
│   │   ├── Projects.astro
│   │   ├── ProjectsLayoutGrid.astro          # Grid layout (default)
│   │   ├── ProjectsLayoutTabsHorizontal.astro # Horizontal tabs layout
│   │   ├── ProjectsLayoutTabsVertical.astro   # Sidebar menu layout
│   │   ├── SkillBadge.astro
│   │   ├── Spotify.astro
│   │   ├── ThemeSelector.astro
│   │   ├── ThemeToggle.astro
│   │   ├── Timeline.astro
│   │   ├── Twitter.astro
│   │   └── YouTube.astro
│   ├── content/        # Content collections
│   │   ├── about/     # About section (1 file)
│   │   ├── blog/      # Blog posts (.md or .mdoc)
│   │   ├── education/ # Education history
│   │   ├── general/   # General settings
│   │   ├── hackathons/# Hackathon entries
│   │   ├── projectCategories/ # Project category definitions
│   │   ├── projects/  # Portfolio projects
│   │   └── work/      # Work experience
│   ├── layouts/       # Page layouts
│   │   ├── Layout.astro
│   │   ├── BlogLayout.astro
│   │   └── ProjectLayout.astro
│   ├── pages/         # File-based routing
│   │   ├── index.astro
│   │   ├── blog/
│   │   │   ├── index.astro
│   │   │   └── [...slug].astro
│   │   └── projects/
│   │       ├── index.astro
│   │       └── [...slug].astro
│   ├── styles/
│   │   └── global.css # Tailwind + DaisyUI + Typography
│   ├── utils/
│   │   ├── iconMapper.ts
│   │   └── parseInlineLinks.ts  # [link:<url>]text[/link] parser
│   └── content.config.ts # Content schemas
├── astro.config.mjs   # Astro configuration
├── keystatic.config.ts # Keystatic CMS configuration
├── package.json
├── tsconfig.json
└── README.md

📝 Content Management

Bloomfolio offers two powerful ways to manage your content: the Keystatic CMS for a visual editing experience, or direct file editing for developers who prefer working with code.

Option 1: Keystatic CMS (Recommended)

Keystatic is a modern, Git-based headless CMS that provides a user-friendly interface for managing your content without touching code.

Accessing the Editor

Start the development server:
```
npm run dev
```
Navigate to the admin panel:
```
http://localhost:4321/keystatic
```
Start creating and editing content through the visual interface!

What is Keystatic?

Keystatic is a Git-based CMS that:

Stores content as files in your repository (not in a database)
Provides a beautiful visual editor with live preview
Works with local development and GitHub/GitLab workflows
Generates type-safe content with full TypeScript support
Integrates seamlessly with Astro's Content Collections

Learn more: Keystatic Documentation

Content Types in Keystatic

Singletons (one-per-site content):

Hero Section - Your name, title, avatar, social links
About Section - Personal bio with photo (supports Markdown)

Collections (multiple entries):

Blog Posts - Published articles and unlisted drafts with cover images, tags, and rich media embeds
Projects - Portfolio items with screenshots, descriptions, and tech stacks
Work Experience - Timeline of employment history
Education - Academic background
Hackathons - Competitive coding events and achievements

Using the Keystatic Editor

Create New Entries
- Click "Create entry" in any collection
- Fill out the form fields (Keystatic validates required fields)
- For Blog Posts, leave Published unchecked until the article is ready
- Use the rich text editor for Markdown content
- Upload images directly through the interface
Edit Existing Content
- Select any entry from the collection list
- Make changes in the visual editor
- See live preview of your content
Rich Media Embeds (Blog posts only)
- Click the "+" button in the content editor
- Select from available components: Spotify, YouTube, Twitter
- Paste the URL and Keystatic handles the rest
⚠️ Important: Media components (Spotify, YouTube, Twitter) are only available in blog posts. Files must use the .mdoc extension (not .md). To extend components to other collections, see the technical guide in CLAUDE.md.
Save Changes
- All changes are saved as file edits in src/content/
- Changes are automatically detected by Astro's dev server
- Commit and push your changes like any other code

Deployment Modes

Local Mode (Current Setup)

Content stored in src/content/ directory
Changes saved as file system edits
Perfect for personal portfolios and single-user sites

GitHub/Cloud Mode (Future upgrade)

Content synced with GitHub repository
Enable collaboration with non-technical users
Manage content from anywhere via hosted admin panel
See Keystatic Cloud documentation for setup

Option 2: Direct File Editing

If you prefer working directly with files, all content is stored in src/content/ as Markdown, YAML, or Markdoc files.

Blog Posts

Create a new file in src/content/blog/:

---
title: "Your Post Title"
description: "Brief description for SEO"
image: "./featured-image.png"
published: true
publishDate: "2024-01-25"
tags: ["Tag1", "Tag2"]
---

Your content here...

Set published: false to keep the article as a draft. Drafts remain editable in Keystatic but are excluded from the homepage, the Blog page, and direct public access.

File Extensions:

.md - Standard Markdown for regular blog posts
.mdoc - Markdoc with component support (required for media embeds)

Rich Media Embeds (.mdoc files only):

Note: Media components only work in blog collection currently.

# Spotify Embed
{% Spotify url="https://open.spotify.com/track/..." /%}

# YouTube Video
{% YouTube url="https://youtube.com/watch?v=..." /%}

# Twitter/X Post
{% Twitter url="https://x.com/username/status/..." /%}

Projects

Create a new file in src/content/projects/:

---
featured: true  # Show on homepage (max 3 featured projects)
category: real-projects  # Category slug (managed in Project Categories)
title: "Project Name"
description: "Brief description"
image: "./screenshot.png"
startDate: "2023-01-15"
endDate: "2023-06-30"  # Optional (omit for ongoing)
skills: ["React", "Node.js", "MongoDB"]
demoLink: "https://demo.example.com"  # Optional
sourceLink: "https://github.com/..."  # Optional
---

Detailed project description...

Set featured: true to display the project on the homepage. Up to 3 featured projects are shown, sorted by most recent. The category field references a slug from the Project Categories collection.

Work Experience

Create a new file in src/content/work/:

---
title: "Company Name"
subtitle: "Job Title"
location: "City, Country"  # Optional
startDate: "2020-01-15"
endDate: "2023-06-30"  # Optional (omit for current position)
logo: "https://company-logo-url.com"  # Optional
link: "https://company-website.com"   # Optional
skills: ["React", "TypeScript", "Node.js"]  # Optional
---

Job description and achievements...

The timeline displays duration automatically and skills are shown in modal dialogs.

Education

Create a new file in src/content/education/:

---
title: "Institution Name"
subtitle: "Degree/Course"
startDate: "2015-09-01"
endDate: "2019-06-30"  # Optional
logo: "https://institution-logo-url.com"  # Optional
link: "https://institution.edu"  # Optional
---

Educational details and achievements...

Hackathons

Create a new file in src/content/hackathons/:

---
title: "Hackathon Name"
location: "City, State or Virtual"
description: "Brief hackathon summary"
startDate: "2023-11-23"
endDate: "2023-11-25"  # Optional
logo: "https://hackathon-logo-url.com"  # Optional
sourceLink: "https://github.com/..."  # Optional
---

Detailed information about the hackathon and your project...

Singletons (Hero & About)

Hero (src/content/hero/index.yaml):

name: Your Name
title: "Your Title with [link:https://example.com]a link[/link]"
description: Brief description of your portfolio
avatar: "./avatar.png"
location: 🌍 Your Location
socialLinks:
  - url: https://github.com/username
    icon: GitHub
    label: GitHub
  # ... other social links

About (src/content/about/index.md):

---
title: "About Me"
photo: "./photo.png"
link: "https://linkedin.com/in/username"  # Optional - used for "More Work Experience" button
---

Your about content with **Markdown** formatting...

Content Tips

Image Paths:

Use relative paths like "./image.png" for local images
Images are automatically optimized by Astro
Supported formats: PNG, JPG, WEBP, AVIF, SVG

Dates:

Format: YYYY-MM-DD (e.g., "2024-01-15")
Leave endDate empty for ongoing positions/projects

Skills/Tags:

Arrays of strings: ["React", "TypeScript", "Node.js"]
Display as badges in the UI

Resources

Keystatic Documentation - Complete CMS guide
Keystatic Content Components - Creating custom components
Astro Content Collections - Type-safe content schemas
Markdoc Syntax - Enhanced Markdown format

Setting Up GitHub Mode (Optional)

For remote content editing from anywhere, you can enable Keystatic's GitHub mode:

Prerequisites

GitHub account
Repository hosted on GitHub

Steps

Create GitHub OAuth App

Visit GitHub Developer Settings and create a new Github App:
- Application name: Bloomfolio Keystatic
- Homepage URL: http://localhost:4321 (for local development)
- Authorization callback URL: http://localhost:4321/api/keystatic/github/oauth/callback
For production, use your deployed URL instead.

Set Environment Variables

Copy .env.example to .env:

cp .env.example .env

Fill in your values:

KEYSTATIC_GITHUB_CLIENT_ID=your_client_id_here
KEYSTATIC_GITHUB_CLIENT_SECRET=your_client_secret_here
KEYSTATIC_SECRET=$(openssl rand -base64 32)
PUBLIC_KEYSTATIC_REPO_OWNER=your-github-username
PUBLIC_KEYSTATIC_REPO_NAME=bloomfolio
PUBLIC_KEYSTATIC_GITHUB_APP_SLUG=your-github-app-slug

Restart Development Server
```
npm run dev
```
Access Keystatic

Navigate to http://localhost:4321/keystatic and sign in with GitHub.

Production Setup

For production deployment (Vercel, Netlify, etc.):

Add all environment variables to your hosting platform's environment settings
Update OAuth App callback URL to your production domain
Set PUBLIC_KEYSTATIC_GITHUB_APP_SLUG (optional, for GitHub App mode)

Learn more: Keystatic GitHub Mode Documentation

Switching Between Modes

GitHub Mode: Set environment variables (content synced with GitHub)
Local Mode: Remove/unset environment variables (content stored locally)

The configuration automatically detects which mode to use based on environment variables.

🎨 Customization

Changing Themes

Edit theme settings via Keystatic CMS at /keystatic or directly in src/content/general/index.yaml:

enableThemeSelector: true  # Dropdown with 6 themes (false = simple toggle)

To change available themes, edit src/styles/global.css:

@plugin "daisyui" {
  themes: light --default, dark --prefersdark, synthwave, retro, valentine, dim;
}

Adding Custom Styles

Add custom CSS in component <style> tags or extend src/styles/global.css:

@import "tailwindcss";
@plugin "@tailwindcss/typography";
@plugin "daisyui" { ... };

/* Your custom styles here */

Creating New Sections

Create a new component in src/components/
Import and add to src/pages/index.astro
Add a visibility toggle in keystatic.config.ts (general singleton)
Update src/content.config.ts schema to match

🚀 Deployment

Build for Production

npm run build

Output is generated in dist/ directory.

Deploy to Vercel

Connect your GitHub repository
Vercel auto-detects Astro
Deploy!

Other Platforms

Bloomfolio uses output: "server" with @astrojs/vercel because Keystatic needs on-demand routes. To deploy elsewhere, install that platform's Astro 7-compatible adapter, replace the Vercel adapter in astro.config.mjs, and follow the platform's server-rendered deployment instructions.

🛠️ Tech Stack

Astro 7 - Server-rendered web framework with component islands
Tailwind CSS 4 - Utility-first CSS framework
Tailwind Typography - Beautiful prose styling
DaisyUI 5 - Component library for Tailwind
TypeScript - Type safety
Markdoc - Enhanced Markdown with components
Keystatic - Git-based CMS with Astro 7 support
Lucide Icons - Icon library

📚 Documentation

Complete Guide - Comprehensive setup and customization guide
Content Collections Guide - Learn about Astro Content Collections
Markdown Guide - Master Markdown and Markdoc syntax
Astro Docs - Official Astro documentation
Tailwind CSS Docs - Tailwind CSS documentation
DaisyUI Docs - DaisyUI component documentation

🤝 Contributing

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

Fork the repository
Create your feature branch (git checkout -b feature/AmazingFeature)
Commit your changes (git commit -m 'Add some AmazingFeature')
Push to the branch (git push origin feature/AmazingFeature)
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 Tailwind CSS and DaisyUI
Icons from Lucide
Inspired by modern portfolio designs and the developer community

💬 Support

Please if you find this project helpful, consider giving it a ⭐ on GitHub!

Crafted by an Artisan ⛏️ Lauro Guedes

Name		Name	Last commit message	Last commit date
.vscode		.vscode
backup/content-before-keystatic		backup/content-before-keystatic
public		public
src		src
.env.example		.env.example
.gitignore		.gitignore
.nvmrc		.nvmrc
CLAUDE.md		CLAUDE.md
LICENSE		LICENSE
README.md		README.md
SETUP.md		SETUP.md
astro.config.mjs		astro.config.mjs
keystatic.config.ts		keystatic.config.ts
markdoc.config.mjs		markdoc.config.mjs
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json

Latest commit

History

Folders and files

Repository files navigation

🌻 Bloomfolio

✨ Features

🚀 Quick Start

Prerequisites

Installation

📋 Commands

⚙️ Configuration

Using Keystatic CMS

Section Visibility

Project Categories

Projects Page Layout

Content Sidebar

Inline Links in Hero

Theme Settings

Extra Links (FAB Flower & Dock)

📂 Project Structure

📝 Content Management

Option 1: Keystatic CMS (Recommended)

Accessing the Editor

What is Keystatic?

Content Types in Keystatic

Using the Keystatic Editor

Deployment Modes

Option 2: Direct File Editing

Blog Posts

Projects

Work Experience

Education

Hackathons

Singletons (Hero & About)

Content Tips

Resources

Setting Up GitHub Mode (Optional)

Prerequisites

Steps

Production Setup

Switching Between Modes

🎨 Customization

Changing Themes

Adding Custom Styles

Creating New Sections

🚀 Deployment

Build for Production

Deploy to Vercel

Other Platforms

🛠️ Tech Stack

📚 Documentation

🤝 Contributing

📄 License

🙏 Acknowledgments

💬 Support

About

Topics

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages