Blog Repository

This repository holds all long-form written content for the ecosystem. It serves articles for:

• blog.raycool.dev
• blog.littlelectron.com
• other future subdomains as the platform grows

The repo contains Markdown articles, templates, supporting assets, and rendering logic. It functions as a headless content engine. Rendered articles are deployed to one or more Cloudflare Pages projects.

This design keeps content completely separate from the main raycool.dev platform and avoids long-term technical debt.

Why This Repo Exists

Independently building serious engineering infrastructure requires:

• documentation
• research logs
• architectural notes
• platform announcements
• engineering stories
• long-form explanations
• technical guides
• narrative content

Most platforms get these for free from enterprise systems. Independent developers have to build them.

This repo provides a low-cost, scalable, zero-maintenance foundation for all written content. All articles begin as Markdown and are transformed into styled HTML using templates.

Writing Articles

All articles are written in pure Markdown with light frontmatter.

Example:

---
title: "The Little House on the Corner"
description: "How raycool.dev started as a small house and became a platform."
template: "blog"
date: 2025-02-17
tags:
  - architecture
  - raycool.dev
  - microsites
---

# **Part I: The Little House on the Corner**

**Given** the enterprise world provides everything…

Markdown is the only thing you write. The template system handles styling, typography, spacing, and syntax highlighting.

Frontmatter Specification

Each article must include a YAML frontmatter block:

Templates can use these fields for rendering and metadata.

Templates

Templates live in the templates/ directory.

Each template consists of:

• an HTML file
• a CSS file
• optional template-specific JS

Example structure:

templates/
  blog.html
  blog.css
  technical.html
  technical.css
  story.html
  story.css

Templates define:

• typography
• colors
• spacing
• section breaks
• code highlighting theme
• callouts
• cue word styling (Given, When, Then)
• keyword emphasis

Templates are swappable. The same article can render across multiple domains with the same content but different visual identity.

Syntax Highlighting + Math

The renderer supports:

• Code blocks (Python, JS, Rust, SQL, YAML, etc.)
• Math notation using KaTeX/MathJax
• Callouts
• Headings of all sizes
• Sections breaks (---)
• Inline emphasis semantics

No special authoring syntax required.

Rendering Workflow

The rendering pipeline converts every Markdown article into HTML.

General flow:

1. Parse frontmatter
2. Parse Markdown using standard + extended rules
3. Enhance content with:

• semantic cue word styling
• section break formatting
• callout rendering
• syntax highlighting
• math notation 4. Insert content into chosen template 5. Output static HTML for deployment

The output is fully static and compatible with Cloudflare Pages.

Deployment

This repository can deploy to multiple Cloudflare Pages projects:

• blog.raycool.dev
• blog.littlelectron.com
• future subdomains

Each project may:

• target a different branch
• use a different template set
• override global styles

The underlying content remains the same.

Local Preview

1. Install deps (once): pip install markdown pyyaml
2. Render articles to HTML: python renderer/render_articles.py (writes to public/site/articles/<year>/<slug>.html and logs to renderer/render_summary.json).
3. Serve locally: cd public/site python -m http.server 8000
4. Visit http://localhost:8000 to view the microsite home (index.html) and open generated articles directly, e.g. /articles/2025/why-this-blog-repo-exists.html.

Folder Structure

blog/
  articles/
    2025/
      the-little-house-on-the-corner.md
      second-article.md
    2024/
      older-post.md
  templates/
    blog.html
    blog.css
    technical.html
    technical.css
  assets/
    images/
    illustrations/
  renderer/
    pipeline.js or pipeline.py (TBD)
  README.md

The structure is simple, predictable, and scalable.

Philosophy

This repo aims to do five things well:

1. Make writing frictionless
2. Make rendering beautiful
3. Keep compute costs near zero
4. Keep content portable across domains
5. Support future AI-driven features without rewriting anything

Everything here is structured with long-term growth and independent-developer pragmatism in mind.

License

TBD.