Beyond Static: Building a Publication System Around Jekyll
Jekyll still builds the site, but writing Markdown is only part of publishing it. A new project needs a place in the catalog, a card, a landing page, a blog, and a route into navigation. An article needs a stable URL, a useful place in discovery, and a way to review it before readers see it. Technical posts also bring diagrams, source files, and sometimes audio.
I added tools as those needs surfaced. Some changes are Liquid layouts and includes; others are Ruby plugins, Python generators, shell wrappers, checks, or review habits. This series follows the problems that led to them and explains where each part of the workflow begins and ends.
The main installments tell the engineering story. Optional Hands-On companions will use small, invented examples when a mechanism is worth building separately. They will appear beside the relevant installment and are not required to follow the argument.
Main Series
-
Jekyll, One Problem at a Time
A project catalog, shared Liquid templates, stable links, and publishing checks grew from fixing one Jekyll frustration after another.
-
A Local Jekyll Server I Can Actually Operate
A useful preview has to show work in progress without confusing it with the current publication. Here is what my Jekyll wrapper actually does.
-
Building the Site from Shared Layouts, Includes, and Data
I got tired of fixing the same project presentation in several places. Jekyll’s layout hierarchy and shared includes gave each piece one job.
-
Stable URLs in a Repository That Keeps Moving
I can reorganize the source all I want, but a link I have already given somebody needs a more deliberate kind of change.
-
From a YAML Project Catalog to a Project Publishing System
A project is more than one page here. I wanted one catalog entry to lead to a card, a place in navigation, a landing page, and a blog for its updates.
-
Diagrams and Source Code That Behave Like Editorial Content
A correct diagram can still be unreadable, and a useful code file can take over an article. I gave each artifact a place in the reading flow.
-
Proofreading a Blog by Listening to It
I can read a draft three times and still miss the sentence that sounds wrong. Listening to the rendered post gives me another way to edit it.
-
Checks, Repairs, and the Gates Before Deployment
A successful Jekyll build is useful, but it is not my entire publishing decision. Here is what the local checks, commit hook, and Pages workflow actually do.
-
Monitoring a Static Site After Deployment
The Pages job can finish cleanly while a public route, image, or redirect still needs attention. Here is what my served-site crawler and monitoring tools actually check.
Hands-On Companions
-
Hands-On: Build a Jekyll Preview Switch
Build one small Jekyll fixture in current and review modes, then prove which posts each mode includes without touching your site server.
-
Hands-On: Find the Limits of a Jekyll Metadata Check
Run the site’s taxonomy plugin against invented posts and see both the bad metadata it rejects and the mistake a successful build still lets through.
-
Hands-On: Keep a Short Link Through a Source Move
Run the site’s short-link calculation on invented posts and watch what stays fixed when a source path changes.
-
Hands-On: Follow a Project Through the Catalog
Run an offline copy of the project generator on three invented repositories and inspect the data and scaffolding it produces.
-
Hands-On: Render and Review a Diagram Before Jekyll Builds
Take the actual DOT and Mermaid sources from Part 6, render them locally, change a label, and see where the Jekyll build begins.
-
Hands-On: Build a Small Prepublication Check Runner
Run three small gates against an invented article, break one input at a time, and watch the runner stop without touching a real Jekyll checkout.
-
Hands-On: Check What the Deployed Site Serves
Serve an invented miniature site on loopback and see the difference between a missing asset, a successful HTTP response, and a redirect to the right page.
Across the Series
The opening article follows repeated Jekyll frustrations into a more connected publication workflow. From there I look at local preview, layout inheritance and shared Liquid includes, stable URLs, the YAML project catalog, project blogs and discovery, diagrams and source files, proofreading by listening, validation and deployment gates, monitoring, and the editorial decisions that still belong to a person.
The repository includes older experiments and utilities alongside active paths. I will distinguish implemented code, current operator use, configured automation, and historical work instead of treating every script as part of the daily publishing path.