From ec124768dca8321189af99f1c4d6427dc39f32b8 Mon Sep 17 00:00:00 2001 From: Brandon Lucas Date: Wed, 18 Feb 2026 09:50:15 -0500 Subject: [PATCH] docs: add README and site review with improvement brainstorm Co-Authored-By: Claude Opus 4.6 --- README.md | 107 ++++++++++++++++++++++++++++++ REVIEW.md | 195 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 302 insertions(+) create mode 100644 README.md create mode 100644 REVIEW.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..c091cdb --- /dev/null +++ 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. diff --git a/REVIEW.md b/REVIEW.md new file mode 100644 index 0000000..fe1cb35 --- /dev/null +++ b/REVIEW.md @@ -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 `` 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 (`
`, `

`, `

`, etc.) +- Descriptive `` 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)