phare-blog 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Phare Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,385 @@
+# 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
+
+```bash
+# Install globally
+npm install -g phare
+
+# Or use with pnpm
+pnpm add -g phare
+
+# Or use without installing
+npx phare new my-blog
+```
+
+See [Installation Guide](docs/INSTALL.md) for detailed instructions, troubleshooting, and all installation methods.
+
+### Create Your First Site
+
+```bash
+# 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:
+
+```toml
+[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:
+
+```bash
+phare post "My Post Title"
+```
+
+Or manually create a Markdown file in `content/posts/`:
+
+```markdown
+---
+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/`:
+
+```markdown
+---
+title: "About"
+---
+
+This is the about page.
+```
+
+## Commands
+
+### `phare new <name>`
+
+Create a new Phare site with the given name.
+
+```bash
+phare new my-blog
+```
+
+### `phare post <title>`
+
+Create a new blog post with the given title.
+
+```bash
+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.
+
+```bash
+phare build
+```
+
+Options:
+- `-o, --output <dir>`: Specify output directory (default: `public`)
+
+### `phare serve`
+
+Start a development server with hot-reload.
+
+```bash
+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:**
+
+```handlebars
+{{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:**
+
+```handlebars
+{{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
+
+```bash
+# netlify.toml
+[build]
+  command = "phare build"
+  publish = "public"
+```
+
+### Vercel
+
+```bash
+# vercel.json
+{
+  "buildCommand": "phare build",
+  "outputDirectory": "public"
+}
+```
+
+### GitHub Pages
+
+```bash
+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
+
+```bash
+# 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](CONTRIBUTING.md) for guidelines.
+
+### Reporting Issues
+
+Found a bug? [Open an issue](https://codeberg.org/fberrez/phare/issues) on Codeberg.
+
+### Feature Requests
+
+Have an idea? [Start a discussion](https://codeberg.org/fberrez/phare/issues) 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](https://motherfuckingwebsite.com/)
+- [Neustadt - Rediscovering the Small Web](https://neustadt.fr/essays/the-small-web/)
+- [Neustadt - Against an Increasingly User-Hostile Web](https://neustadt.fr/essays/against-a-user-hostile-web/)
+
+## License
+
+MIT License - see [LICENSE](LICENSE) for details.
+
+## Links
+
+- **Website**: https://phare.example.com (coming soon)
+- **Repository**: https://codeberg.org/fberrez/phare
+- **Issues**: https://codeberg.org/fberrez/phare/issues
+- **Changelog**: [CHANGELOG.md](CHANGELOG.md)
+- **Roadmap**: [ROADMAP.md](ROADMAP.md)
+
+---
+
+**Made with ❤️ for the small web**