Lighthouse mark for Peisong's Lighthouse Peisong's Lighthouse Somewhere to find inspiration.

LIGHTHOUSE

Lighthouse Site Design

This document describes the implementation-facing design of the Lighthouse site repository.

Table of Contents

Goals

Lighthouse is a static-first personal site. It is designed to:

  • render entirely as a static Jekyll site
  • keep the public site free of runtime mutation surfaces
  • support hand-authored pages and photo entries directly in-repo
  • accept automation-generated .md and .tex posts from the deployment pipeline

Content Model

The current repository has six content classes:

  1. root pages such as index.html and privacy-policy.md
  2. the About section under aboutme/
  3. the site-owned resume source at resume.tex
  4. photo entries under _photos/
  5. automation-generated posts under _automated_posts/
  6. automation-generated navigator directory pages under generated-directories/

Shared presentation is owned by:

Automation Boundary

The deployment pipeline writes only to machine-owned paths:

  • _automated_posts/
  • _data/generated/
  • generated-directories/
  • assets/generated/

Everything else is treated as hand-maintained site source.

The pipeline is implemented in the separate ../../lighthouse-cli/ repository. It is responsible for:

  • syncing source repositories
  • rewriting local document references
  • generating explicit Jekyll front matter
  • generating source and directory navigator pages
  • copying referenced local assets
  • generating assets/generated/resume/resume.fragment.html and assets/generated/resume/resume.pdf from resume.tex
  • building and deploying the final site

Public Build Surface

Jekyll should only publish the site itself. Repository-only materials such as docs, local tooling notes, vendored gems, and Git metadata are excluded in _config.yml.

The public site output is generated into _site/ and is not tracked as source.

Design Notes

  • No WordPress taxonomy model is carried forward.
  • The site uses a small number of explicit collections instead of a CMS object model.
  • Search and weighted-random discovery are implemented as static JSON endpoints plus client-side behavior.
  • RSS feeds are rendered as static XML endpoints using generated policy data from lighthouse-cli.
  • Generated raw assets are excluded from Jekyll rendering and copied into _site/ after the build, so raw HTML/XML/JSON files from linked repositories cannot override authored site routes.
  • /navigator/ is the primary post browsing surface. It lists source repository roots in navigator mode and includes built-in photo posts alongside generated repository posts. Source roots such as /blogs/ are generated navigator pages scoped to their repository content.
  • Navigator listings default to most-recent ordering with surfaced posts promoted after directories. Users can switch to least-recent, alphabetical, highest-rating, or lowest-rating order.
  • Linked repository directories are exposed through generated navigator pages rather than being treated as authored posts.