docs: add README and site review with improvement brainstorm

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-02-18 09:50:15 -05:00
parent 6b7ac4f09b
commit ec124768dc
2 changed files with 302 additions and 0 deletions
--- a/README.md
+++ b/README.md
@@ -0,0 +1,107 @@
+# blu-site
+
+A static site generator and personal website for [blu.cx](https://blu.cx), written entirely in [Lux](https://github.com/thebrandonlucas/lux).
+
+## Overview
+
+This is not a generic SSG framework -- it's a single Lux program that reads Markdown content with YAML frontmatter, converts it to HTML, and writes a complete static site. It handles:
+
+- Markdown-to-HTML conversion (headings, bold, italic, links, images, code blocks, blockquotes, lists)
+- YAML frontmatter parsing (title, date, description, tags)
+- Tag page generation
+- Section indexes (articles, blog, journal)
+- Homepage with snippet cards
+- Syntax highlighting via highlight.js
+- SEO meta tags (Open Graph, Twitter Cards)
+
+## Prerequisites
+
+- [Lux](https://github.com/thebrandonlucas/lux) compiler/interpreter
+
+## Usage
+
+### Build the site
+
+```bash
+lux main.lux
+```
+
+This reads content from `content/`, static assets from `static/`, and writes the generated site to `_site/`.
+
+### Serve locally
+
+```bash
+lux serve
+```
+
+Starts a local file server (default port 8090) serving `_site/`.
+
+### Compile to native binary
+
+```bash
+lux compile main.lux
+./main
+```
+
+## Project Structure
+
+```
+blu-site/
+  config.json          # Site metadata (title, URL, author, description)
+  main.lux             # Site generator source
+  content/
+    articles/          # Long-form articles (*.md)
+    blog/              # Blog posts (*.md)
+    journal/           # Monthly journal entries (*.md)
+    snippets/          # Homepage card content (*.md)
+  static/
+    fonts/             # EBGaramond, UnifrakturMaguntia
+    images/            # Site images and social card
+    highlight/         # highlight.js + theme
+    styles.css         # Tailwind CSS v4
+    data/              # Static data files
+  _site/               # Generated output (gitignored)
+```
+
+## Content Format
+
+Posts use Markdown with YAML frontmatter:
+
+```markdown
+---
+title: "My Post Title"
+date: 2025-01-15
+description: "A brief description"
+tags: bitcoin privacy
+---
+
+Post content in Markdown...
+```
+
+## Configuration
+
+`config.json`:
+
+```json
+{
+  "siteTitle": "Brandon Lucas",
+  "siteUrl": "https://blu.cx",
+  "author": "Brandon Lucas",
+  "description": "Personal website of Brandon Lucas...",
+  "contentDir": "content",
+  "outputDir": "_site",
+  "staticDir": "static"
+}
+```
+
+## Design
+
+- Dark theme (#111 background, #fffff8 text)
+- EBGaramond body font, UnifrakturMaguntia for the site title
+- Tailwind CSS v4
+- Tokyo Night Dark code highlighting
+- Responsive grid layout for snippet cards
+
+## License
+
+Copyright (c) 2025 Brandon Lucas. All Rights Reserved.