Terminal Portfolio Site

An interactive terminal-themed portfolio built with Zola, WebTUI, and jQuery Terminal. Features dual navigation (tree + shell), virtual filesystem, and progressive enhancement.

Live URL: http://n3st:1111/ (local: 100.99.93.69:1111)

---

Quick Start

# Install dependencies
bun install

# Development server (builds CSS + serves with Zola)
bun run dev

# Full production build
bun run build

---

Tech Stack

• Zola - Static site generator
• Tera - Template engine (Jinja2-like syntax)
• Vite - Asset bundler for CSS/JS
• Bun - Package manager and runtime
• jQuery Terminal - Terminal emulator interface (v2.45.2, self-hosted)
• WebTUI CSS - Modular TUI-styled component library
• Sass/SCSS - Stylesheet preprocessing
• Peggy - Markdown parsing grammar compiler

---

Build Pipeline

The build process runs in three stages:

1. Vite Bundle (bun run build:css)

   • Entry: src/main.js → static/assets/main.js
   • CSS: src/webtui.css → static/assets/webtui.css
   • Tree-shakes WebTUI modules

2. Zola Build (zola build)

   • Compiles Markdown in content/ → HTML
   • Processes Tera templates
   • Compiles Sass → public/global.css
   • Generates search index and RSS feeds

3. Manifest Generation (bun run build:manifest)

   • Node script (build.js) parses markdown with Peggy grammar
   • Extracts frontmatter and processes inline formatting
   • Outputs static/content.json filesystem manifest

---

Repository Structure

birdhouse/
├── config.toml              # Zola configuration
├── package.json             # Dependencies and scripts
├── vite.config.js           # Vite bundler config
├── build.js                 # Manifest generation script
├── content/                 # Markdown content files
│   ├── _index.md
│   ├── blog/
│   └── projects/
├── sass/                    # SCSS stylesheets
│   ├── global.scss
│   └── _terminal-shell.scss
├── src/                     # JavaScript source files
│   ├── main.js              # Entry point
│   ├── webtui.css           # WebTUI imports
│   ├── mobile-navbar.js     # Responsive nav logic
│   ├── terminal-foundation.js   # Terminal implementation (~1400 lines)
│   ├── filesystem-builder.js    # UMD filesystem library
│   └── markdown.pegjs       # Markdown grammar
├── static/                  # Static assets
│   ├── assets/              # Built assets
│   └── vendor/              # Vendored dependencies
├── templates/               # Tera templates
│   ├── base.html
│   ├── index.html
│   └── blog.html
└── public/                  # Zola build output (git-ignored)

---

Development Commands

Command	Description
bun install	Install dependencies
bun run dev	Full dev build + serve
bun run serve	Serve only (skip CSS build)
bun run build:css	Bundle CSS/JS only
bun run build:manifest	Generate content.json
bun run build	Full production build

---

Architecture

Virtual Filesystem

The terminal implements a virtual filesystem loaded from content.json:

• Commands: ls, cd, cat, pwd, help, clear, tree, find
• Features: Tab completion, command history, color-coded output
• Paths: Use /section/page.md format; _index.md for section indexes

Dual Navigation System

1. Tree Navigation (left sidebar) - Generated by Zola templates
2. Terminal Interface (right panel) - Shell commands for navigation

Navigation links include data-terminal-* attributes for synchronization between tree and terminal.

Content Synchronization

• Clicking nav links auto-executes terminal commands
• Terminal state syncs with browser history API
• URL fragments (/#cat /blog/post.md) run commands on load
• Progressive enhancement: content works without JavaScript

---

Key Files

File	Purpose
src/terminal-foundation.js	Terminal shell implementation
build.js	Content manifest generator
templates/base.html	Main layout with navigation
config.toml	Zola and site configuration
src/markdown.pegjs	Markdown parsing grammar

---

Adding Content

New Blog Post

# Create file with TOML frontmatter
echo "+++\ntitle = 'My Post'\ndate = 2025-01-09\n+++\n\nContent here." > content/blog/my-post.md

# Regenerate manifest and rebuild
bun run build:manifest
bun run build

New Section

# Create section index
mkdir content/newsection
echo "+++\ntitle = 'New Section'\n+++" > content/newsection/_index.md

# Add to config.toml nav_items, then rebuild

---

Notes

• Dev server binds to 100.99.93.69:1111 (also reachable at http://n3st:1111/)
• WebTUI box-="double round" renders incorrectly; use one value only
• Always run build:css before zola build to keep assets in sync
• jQuery Terminal is vendored in static/vendor/ (no external CDN dependencies)