Phare

A privacy-focused static site generator for the small web.

Phare (French for "lighthouse", pronounced like "far") is a minimal, fast, and privacy-first static site generator built with TypeScript. It's designed for bloggers who value simplicity, performance, and user privacy.

Features

• 🔒 Privacy-First: No tracking, no analytics, no external dependencies
• ⚡ Blazing Fast: Builds 50 posts in <20ms
• 🎨 Beautiful Default Theme: Dark mode, <10KB CSS, zero JavaScript
• 📝 Markdown-Based: Write in Markdown with frontmatter
• 🚀 Simple CLI: Four commands to rule them all
• 🌍 RSS/Atom Feeds: Built-in feed generation
• ♿ Accessible: WCAG AA compliant by default
• 📦 Zero Config: Works out of the box with sensible defaults

Quick Start

Installation

# Install globally
npm install -g phare
# Or use with pnpm
pnpm add -g phare
# Or use without installing
npx phare new my-blog

Create Your First Site

# Create a new site
phare new my-blog
# Navigate to your site
cd my-blog
# Create your first post
phare post "Hello World"
# Build the site
phare build
# Start dev server with hot-reload
phare serve

Your site will be available at http://localhost:3000

Project Structure

my-blog/
├── phare.toml # Site configuration
├── content/
│ ├── posts/ # Blog posts (Markdown)
│ │ └── 2024年01月10日-hello-world.md
│ └── pages/ # Static pages (Markdown)
│ └── about.md
├── static/ # Static assets (copied as-is)
│ └── favicon.ico
├── templates/ # Custom templates (optional)
│ └── default/
│ ├── index.html
│ ├── post.html
│ ├── page.html
│ └── style.css
└── public/ # Generated site (don't edit)

Configuration

Edit phare.toml to configure your site:

[site]
title = "My Blog"
url = "https://example.com"
author = "Your Name"
lang = "en"
description = "A blog about things"

That's it! Phare embraces convention over configuration.

Writing Content

Posts

Create a new post with the CLI:

phare post "My Post Title"

Or manually create a Markdown file in content/posts/:

---
title: "My First Post"
date: 2024年01月10日
tags: ["intro", "blog"]
description: "An introduction to my blog"
draft: false
---
# Hello World

This is my first post!

Frontmatter fields:

• title (required): Post title
• date (required): Publication date (YYYY-MM-DD)
• tags (optional): Array of tags
• description (optional): Post description for feeds
• draft (optional): If true, post won't be published

Pages

Create static pages in content/pages/:

---
title: "About"
---
This is the about page.

Commands

phare new <name>

Create a new Phare site with the given name.

phare new my-blog

phare post <title>

Create a new blog post with the given title.

phare post "My Awesome Post"

This creates a file like content/posts/2024-01-10-my-awesome-post.md.

phare build

Build your static site to the public/ directory.

phare build

Options:

• -o, --output <dir>: Specify output directory (default: public)

phare serve

Start a development server with hot-reload.

phare serve

Options:

• -p, --port <port>: Specify port (default: 3000)

The server watches for changes in:

• content/ - Rebuilds on content changes
• static/ - Copies updated assets
• phare.toml - Reloads configuration
• templates/ - Reloads templates

Customization

Templates

Phare uses Handlebars templates. To customize, create files in templates/default/:

• index.html - Homepage template
• post.html - Blog post template
• page.html - Static page template
• style.css - Stylesheet (inlined in HTML)

Available template variables:

{{site.title}} - Site title
{{site.url}} - Site URL
{{site.author}} - Author name
{{site.lang}} - Site language
{{site.description}} - Site description
{{post.title}} - Post title
{{post.date}} - Post date
{{post.content}} - Post HTML content
{{post.description}} - Post description
{{post.tags}} - Post tags array
{{post.slug}} - Post URL slug
{{#each posts}} - Loop through posts
{{#each pages}} - Loop through pages

Template helpers:

{{formatDate date "yyyy-MM-dd"}} - Format date
{{formatDateLong date}} - Format as "January 10, 2024"
{{truncate text 100}} - Truncate text to length
{{join tags ", "}} - Join array with separator

Styling

The default "Clarté" theme provides:

• Automatic dark mode (prefers-color-scheme)
• System font stack (no web fonts)
• Responsive design
• <10KB CSS
• WCAG AA accessible

To customize, edit templates/default/style.css or create your own theme.

Performance

Phare is designed to be fast:

• Build speed: 50 posts in ~15ms
• Page size: <10KB HTML + CSS
• Zero JavaScript: No runtime overhead
• Optimized parsing: Efficient Markdown and template processing

Privacy

Phare is built with privacy as a core principle:

• ✅ No tracking scripts
• ✅ No analytics
• ✅ No external font loading
• ✅ No CDN dependencies
• ✅ Self-contained CSS
• ✅ GDPR compliant by default

Your readers' privacy is protected out of the box.

Deployment

Deploy the public/ directory to any static hosting:

Netlify

# netlify.toml
[build]
 command = "phare build"
 publish = "public"

Vercel

# vercel.json
{
 "buildCommand": "phare build",
 "outputDirectory": "public"
}

GitHub Pages

phare build
cd public
git init
git add .
git commit -m "Deploy"
git push -f git@github.com:username/username.github.io.git main

Cloudflare Pages

Connect your repository and set:

• Build command: phare build
• Output directory: public

Development

Requirements

• Node.js 20+
• pnpm (recommended)

Setup

# Clone repository
git clone https://codeberg.org/fberrez/phare.git
cd phare
# Install dependencies
pnpm install
# Build CLI
pnpm build
# Run tests
pnpm test
# Link for local development
pnpm link --global

Project Structure

phare/
├── src/
│ ├── index.ts # CLI entry point
│ ├── cli/ # Command implementations
│ ├── config/ # Configuration parser
│ ├── content/ # Content parsers (Markdown)
│ ├── build/ # Build system & templates
│ └── server/ # Dev server
├── templates/ # Default theme
├── tests/ # Test suite
└── dist/ # Compiled output

Contributing

Contributions are welcome! Please read CONTRIBUTING.md for guidelines.

Reporting Issues

Found a bug? Open an issue on Codeberg.

Feature Requests

Have an idea? Start a discussion first.

Philosophy

Phare follows these principles:

1. Privacy First: No tracking, no analytics, respect user privacy
2. Radical Simplicity: Minimal configuration, sensible defaults
3. Performance: Fast builds, small pages, optimized output
4. Accessibility: WCAG AA compliant, semantic HTML
5. Open Source: Free software, community-driven
6. Small Web: Built for personal blogs, not corporate sites

Inspirations

Phare is inspired by:

• This is a motherfucking website
• Neustadt - Rediscovering the Small Web
• Neustadt - Against an Increasingly User-Hostile Web

License

MIT License

Links

• Website: https://phare.example.com (coming soon)
• Repository: https://codeberg.org/fberrez/phare
• Issues: https://codeberg.org/fberrez/phare/issues
• Bluesky: https://bsky.app/profile/fberrez.co
• Mastodon: https://mastodon.social/@floberrez

Made with ❤️ for the small web