blu/blu-lux
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: add README and site review with improvement brainstorm

Browse Source 
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
Brandon Lucas
2026-02-18 09:50:15 -05:00
parent 6b7ac4f09b
commit ec124768dc
2 changed files with 302 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

107
README.md Normal file
View File

@@ -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.

195
REVIEW.md Normal file
View File

@@ -0,0 +1,195 @@
# blu-site: Honest Review & Brainstorm
## Site Review
### Performance: A+
The site is genuinely fast. It's pure static HTML with no JavaScript framework, no client-side rendering, no bundle. The only JS is highlight.js (deferred) for code blocks. Fonts are preloaded. Images use `<picture>` with AVIF + WebP fallbacks and lazy loading. Tailwind is pre-compiled to a single CSS file. This is about as fast as a website can be.
### SEO: B-
**What's good:**
- Open Graph and Twitter Card meta tags on every page
- Semantic HTML (`<main>`, `<h1>`, `<h2>`, etc.)
- Descriptive `<title>` tags per page
- `<meta name="description">` present
- Font preloading
- `<link rel="canonical">`
**What's broken or missing:**
- **`<link rel="canonical">` is `https://blu.cx` on every page** -- it should be the actual page URL. Google uses this to determine the authoritative URL. Having every page point to the homepage is actively harmful to SEO.
- **`og:url` is `https://blu.cx` on every page** -- same issue, should be per-page.
- **No `<link rel="icon">`** -- browsers will 404 looking for `/favicon.ico`. The Narsil logo is displayed as an `<img>` but not set as the browser tab icon.
- **No `robots.txt`** -- search engines will still crawl, but it's a best practice signal.
- **No `sitemap.xml`** -- important for discoverability, especially for a site with 14+ pages across multiple sections.
- **No RSS/Atom feed** -- critical for a blog. Many readers and aggregators use RSS. This is a significant miss for someone who writes regularly.
- **No structured data (JSON-LD)** -- Article schema would help with rich snippets in search results.
- **No `<meta name="theme-color">`** -- minor, but improves mobile browser chrome.
- **Copyright says 2025** -- should be 2026 (or dynamic).
### Design: B
**What's good:**
- The dark theme is pleasant and readable.
- EBGaramond is an excellent serif choice -- gives the site a literary, classical feel that matches the content.
- UnifrakturMaguntia for the site name is a bold, distinctive choice. It's memorable.
- The homepage card grid is a good way to surface diverse content at a glance.
- The post pages are clean and readable.
**What needs work:**
- **No navigation.** There is no way to get from a post page to the articles index, blog index, journal index, or between sections. The only clickable navigation element is the Narsil logo which goes home. For a site with 14 posts, 3 sections, and tag pages, this is a major usability gap.
- **The homepage is a wall of scrollable boxes.** The snippet cards with `max-h-150 overflow-y-auto` create scrollable regions within the page. This is disorienting -- you have the page scroll AND multiple internal scrolls. The Creations and Contributions cards are especially long. Users may not realize they can scroll inside a card, or may accidentally scroll the page when trying to scroll a card.
- **Markdown rendering bug in the Writing snippet.** Lines like `- ### [Fear to Attempt]...` render the `### ` as literal text because the markdown processor doesn't handle headings inside list items. They show up as `### Fear to Attempt` with the hashes visible.
- **The grid is lopsided.** The first snippet (Technology) takes the full width, then the rest are in a 2-column grid. But the cards have wildly different content lengths. The Creations card is massive; the Work card is short. This makes the grid feel unbalanced.
- **Footer social links are tiny (16x16 SVGs).** Hard to click on mobile.
- **No 404 page.**
- **Mobile experience is untested** but the 80% width container with no mobile-specific adjustments may feel cramped or overly wide on different screen sizes.
### Content: A-
This is the strongest part of the site. The writing is genuine, opinionated, and deeply personal. The quotes collection is exceptional -- it reveals a serious reader with taste. The Creations section tells real stories about real projects with honest reflection on what worked and didn't. The articles (Payjoin, Micropayments) are substantive technical writing.
**Issues:**
- **The Technology snippet says "This website is built in Elm"** -- this is now false. The site is built in Lux. This is the most prominent factual error on the site.
- **The bio says "Learning Nix, Elm, Rust, Ancient Greek and Latin"** -- should mention Lux, and possibly remove Elm if it's no longer a focus (or rephrase as "Learned from Elm, now building Lux").
- **Missing recent projects from Creations.** The Lux programming language, Grapho (notetaking/sync), and Lyceum (Ancient Greek reader) are absent from the Creations section. These are arguably more significant and current than many of the archived projects listed.
- **The Lyceum article (2026-02-07) exists in content/articles/ but isn't shown in the Writing snippet.** The Writing snippet appears to be manually curated rather than auto-generated, so it's out of date.
- **Snippets are manually ordered by filename prefix (2000-01-01, 2000-01-02...).** This works but is fragile.
### Uniqueness: B+
The UnifrakturMaguntia title, the Greek name, the Narsil favicon, the curated quotes -- these all contribute to a distinctive identity. It doesn't look like a template. The problem is that the visual design (near-black background, off-white text, bordered cards) is relatively generic. It could be any dark-mode personal site. The font and title treatment are the only truly distinctive elements.
### Ease of Deploy: A
It's a static site. `lux main.lux` generates `_site/`. Copy that anywhere. No build tooling, no npm, no bundler. The only dependency is the Lux binary. This is as freedom-friendly as it gets.
### Custom Aesthetic: C
This is where the biggest gap is. Based on the NixOS configuration, there's a carefully curated classical/antiquity color palette:
- Deep brown `#1a1611` (background)
- Cream `#d4c4a8` (text)
- Gold `#d4a857` (accents)
- Olive `#8a9a5b` (secondary)
- Terracotta `#b85c38` (highlights)
- Wine `#722f37` (emphasis)
The current site uses none of these. It's `#111` (near-black) and `#fffff8` (near-white), which is fine but doesn't express the classical, warm, parchment-like aesthetic that's clearly been thought through for the desktop environment. The disconnect between the carefully themed NixOS rice and this generic dark theme is notable.
---
## Brainstorm: Making the Site Reflect Who You Are
The core theme across all your work is **the recovery of classical wisdom through modern tools** -- using sovereign technology (Bitcoin, Nix, self-hosted systems) in the service of perennial human values (liberty, truth, beauty, craftsmanship). The site should feel like walking into a scholar's study, not a developer portfolio.
### 1. Apply the Classical Color Palette
Replace the generic dark theme with the NixOS palette:
- Background: `#1a1611` (deep brown, like aged wood or leather)
- Text: `#d4c4a8` (cream, like parchment)
- Links/accents: `#d4a857` (gold, like gilt lettering)
- Hover/secondary: `#8a9a5b` (olive, like old book bindings)
- Highlights/tags: `#b85c38` (terracotta)
- Borders: muted gold or olive instead of gray
This would immediately make the site feel warm, distinctive, and coherent with the desktop aesthetic. The EBGaramond + UnifrakturMaguntia fonts already support this direction -- they'd look even better against a brown/cream palette than against stark black/white.
### 2. Add Navigation
A minimal, classical navigation bar:
```
[Articles] [Blog] [Journal] [Creations] [Quotes] [Books]
```
Placed below the title/bio section. No hamburger menu, no complex dropdowns. Just labeled links. This is the single most important usability improvement.
### 3. Restructure the Homepage
Instead of scrollable cards, consider a layout inspired by a classical manuscript or broadsheet:
- **Hero section:** Name, Greek name, one-line description (drop the multi-line bio, it reads like a resume)
- **Featured/latest post** prominently displayed
- **Section previews:** Each section gets 2-3 recent entries with links to the full index
- **Quotes sidebar or rotating quote** as a subtle personality element
The current approach of dumping all content into scrollable boxes on the homepage buries the actual writing. The writing is the best part -- surface it.
### 4. Showcase Your Projects (Lux, Grapho, Lyceum)
These are your most distinctive creations and they're completely absent from the site:
- **Lux:** You literally built this site with it. "This site is built with Lux, a programming language I'm designing" is a compelling hook.
- **Grapho:** A notetaking/sync system -- this reflects your interest in self-hosted, sovereign tools.
- **Lyceum:** An Ancient Greek reader -- this directly connects to the classical theme.
These deserve prominent placement, perhaps a dedicated "Projects" section that replaces or augments the current Creations card.
### 5. Fix the Content Errors
Immediate fixes needed:
- Update "This website is built in Elm" to "This website is built in Lux"
- Update bio: "Learning Nix, Elm, Rust..." -> mention Lux
- Add Lux/Grapho/Lyceum to Creations
- Fix the `### ` rendering in the Writing snippet
- Update copyright to 2026
### 6. Add RSS Feed
Critical for a blog. The site generator should output an `atom.xml` or `rss.xml`. Many of the people in your intellectual circle (Bitcoin devs, Nix enthusiasts, classical scholars) are exactly the kind of people who use RSS readers.
### 7. Add a Proper Favicon
Set the Narsil image as a browser favicon:
```html
<link rel="icon" href="/images/favicon.webp" type="image/webp">
```
### 8. Fix Canonical URLs
Each page should have its own canonical URL:
```html
<link rel="canonical" href="https://blu.cx/posts/articles/2023-10-31-payjoin-better-future">
```
Same for `og:url`. This is important for SEO and for people sharing your posts on social media.
### 9. Consider a Colophon or "About This Site" Page
Given that the site is built with a language you created, running on NixOS, using self-hosted infrastructure -- telling that story is itself compelling content. A colophon page describing the stack (Lux SSG -> static HTML -> VPS/NixOS) would interest exactly the kind of people you want reading your site.
### 10. Add Sitemap + Robots.txt
Easy wins for SEO. The site generator can output these alongside the HTML.
### 11. Subtle Classical Touches
- A thin ornamental rule (`<hr>` styled as a classical divider -- maybe a simple `* * *` or a small SVG flourish) between sections
- Pull quotes styled with a larger font size and subtle left border in gold
- Drop caps on article first paragraphs (CSS `::first-letter`)
- A subtle paper texture or grain on the background (very light, just enough to feel tactile)
These would reinforce the "scholar's study" aesthetic without being heavy-handed.
### 12. Tag Cloud or Category Index
The tag pages exist but are undiscoverable. A tag listing page or tag cloud on the homepage would help readers find related content. Tags like `bitcoin`, `privacy`, `history`, `philosophy` would help people understand what you write about at a glance.
---
## Priority Order
1. **Fix factual errors** (Elm -> Lux, bio text, copyright)
2. **Fix canonical URLs and og:url** (SEO harm)
3. **Add navigation** (usability)
4. **Apply classical color palette** (identity)
5. **Add favicon** (professionalism)
6. **Add RSS feed** (reach)
7. **Restructure homepage** (first impression)
8. **Add Lux/Grapho/Lyceum to Creations** (showcase real work)
9. **Add sitemap.xml + robots.txt** (SEO)
10. **Fix markdown rendering bugs** (quality)
11. **Add colophon page** (storytelling)
12. **Classical design touches** (polish)