How johnsundell/publish works
Project type and purpose
• This is a Swift-based static site generator library and command-line tool (“Publish”), used to build entire websites as Swift packages.
• It provides a core library (API + internal modules) and a CLI (PublishCLI) with associated core logic (PublishCLICore).
• It supports themes (using Plot), plugins, custom publishing pipelines, deployment methods, and local HTTP serving.
File structure
• Top-level:
• Package.swift, Makefile, README, LICENSE, .gitignore
• Documentation folder (how-to guides and reference docs)
• Resources folder (foundation theme CSS)
• Sources folder, subdivided into:
Publish (split into API and Internal)
PublishCLI (entry point main.swift)
PublishCLICore (core CLI command logic, project/website generation, runner, deployer)
• Tests folder (PublishTests with Infrastructure helpers + unit tests)
• This indicates a layered, modular architecture:
Presentation/entry: CLI modules
Core library: API + internal implementations
External-facing resources and docs
Testing infrastructure
• Configuration files: Swift Package manifest (Package.swift), Makefile for building the CLI.
Key insights from README
• Core abstractions: Website, Section, Item, Page, PublishingStep, PublishingContext, Plugin, Theme/HTMLFactory.
• Pipeline pattern: series of steps (addMarkdownFiles, copyResources, generateHTML, generateRSSFeed, generateSiteMap, deploy).
• Factory pattern: HTMLFactory to produce HTML via Plot.
• Plugin architecture: extensions that modify PublishingContext.
• DeploymentMethod abstraction with built-in Git/GitHub deployments.
• Local HTTP server for “publish run”.
Main components
a. User & Configuration
– Website Swift package (Package.swift + Content folder + custom code)
– Custom themes/plugins/publishing steps
b. CLI Layer
– PublishCLI (main.swift) – entry point, parses command-line arguments
– PublishCLICore – orchestrates commands: new, publish, run, deploy
c. Core Library Layer (Publish)
– API module (public types: Website, Section, Item, Page, PublishingStep, Theme, Plugin, DeploymentMethod)
– Internal module (Markdown parsing, file I/O, pipeline engine, HTMLGenerator, RSS/PodcastFeedGenerator, SiteMapGenerator)
d. External Dependencies
– Plot (HTML DSL)
– Splash (syntax highlighting plugin example)
– Swift Package Manager (packaging/build)
– Git/GitHub (deployment)
e. Output & Side-Effects
– File system (generated HTML/CSS/JS/assets, RSS, sitemap)
– Local HTTP server (for “run” command)
– Remote server / GitHub Pages (on deploy)
Relationships and interactions
• User invokes publish or runs Xcode-built executable → PublishCLI
• PublishCLI delegates to PublishCLICore → selects the appropriate command handler
• PublishCLICore calls into Publish API:
• For “new”: ProjectGenerator creates a website template
• For “publish”: WebsiteGenerator triggers Website.publish(...)
• For “run”: WebsiteRunner spins up HTTP server and monitors changes
• For “deploy”: WebsiteDeployer invokes DeploymentMethod
• Website.publish builds a PublishingPipeline:
• A sequence of PublishingStep instances
• Each step receives a PublishingContext and mutates it
• Internal modules handle Markdown parsing, HTML generation (HTMLGenerator → uses HTMLFactory), feed generation, site map, resource copying
• At the end of the pipeline, files are written to disk
• Deploy step (if enabled) pushes output via Git or GitHub API
• Plugins (extensions of Plugin) and themes (HTMLFactory implementations) hook into pipeline
Architectural patterns & design principles
• Layered architecture: CLI → core-logic → API → internal implementation
• Pipeline pattern for content generation
• Factory pattern for HTML generation (HTMLFactory)
• Plugin/extensible design: both publishing steps and plugins extend PublishingContext
• Strong modular separation: core library is framework-agnostic; CLI builds on it
• Type safety: all website configuration expressed in Swift types