Building Shipslecky · Shipslecky

Shipslecky is a repository-governed technical publishing project. Its first edition combines a small public library with strict content schemas, generated-output checks, multi-browser testing and a reversible deployment workflow.

This page is the concise build record. The longer Building Shipslecky case study explains how the pieces work together.

Status at a glance

Current state: first production edition deployed and independently verified.
Architecture: static Astro output from repository-owned Markdown and Astro components.
Public sections: articles, projects, resources, topics, search and policy pages.
Runtime in the browser: no executable JavaScript on core pages; one small progressive search module on the search page.
Release model: exact-commit artifact, pre-write backup, preservation checks, live verification and rollback.

The website remains an active project because the content library and manual accessibility evidence can continue to grow. “Active” does not mean the first production release is unfinished.

Decisions

Static output over an application server

The site needed durable content and portable hosting, not accounts, transactions or live data. Astro’s static mode keeps the public artifact to HTML, CSS, XML and text while still providing reusable components and type-checked content collections. The approach follows the capabilities described in the public Astro content collections guide.

Strict content types

Articles, projects and resources share publication rules but keep type-specific fields. Published entries require dates. Projects expose a lifecycle status. Downloads require repository-verified size and checksum metadata. Images and video carry accessibility and safety constraints.

This contract is used by Astro and imported directly by adversarial Node tests, so the test is not a second hand-written approximation of the schema.

Progressive search

Search begins as visible HTML links and adds client-side filtering. It reuses the central published-content policy and stays within a compressed script budget. This preserves useful navigation when JavaScript is unavailable and avoids adding a search service for a small library.

Browser and performance gates

The local suite runs Chromium and Firefox; main-branch CI adds WebKit. Axe-based checks, keyboard flows, responsive overflow checks and Lighthouse budgets exercise representative pages. Playwright’s accessibility guidance is a useful public description of the automated testing boundary.

Reversible production delivery

The deployment workflow runs the full quality suite and canonical build before writing. It validates the remote boundary, checksums the artifact, verifies a complete backup, preserves host-managed files, compares the deployed tree and then tests the public site. GitHub’s public documentation explains the deployment environment and concurrency controls used to serialize the production job.

Milestones

4 August 2026 — foundation

The repository gained its engineering constitution, product vision, decision log and initial Astro architecture. Public content began with this project record while draft fixtures proved that unpublished material stayed private.

Static search was added with keyboard operation, URL state, draft exclusion and a script-size budget. Responsive navigation was corrected after a narrow-screen test exposed overflow.

6–7 August 2026 — deeper quality controls

Firefox and CI WebKit coverage joined Chromium. Lighthouse category and metric budgets became release gates. Content schemas were extracted into a directly tested contract, and published downloads gained byte-size and checksum verification.

21–26 August 2026 — maintenance under the same gates

The accessibility engine and a vulnerable transitive dependency were updated. Clean locked installs, the complete suite and the zero-vulnerability audit were rerun rather than treating maintenance as exempt from release evidence.

31 August 2026 — first production release

The GitHub-to-Hostilica workflow was completed with pinned remote identity, pre-write boundaries, deterministic artifacts, full backups, cPanel-file preservation, receipts, rollback and production checks. Early attempts exposed an unsuitable authentication format, a missing optional host utility and a final-newline edge case in existing server rules. Each failure was stopped or restored safely, then addressed with focused checks and independent review.

The accepted release passed the full repository suite, exact-commit marker check, HTTPS and redirect checks, canonical routes, security headers, crawler files, RSS, sitemap, custom 404 behaviour and production Lighthouse budgets.

Lessons learned

Fail before the network when possible. Local validation makes authentication problems safer and easier to diagnose.
Test the artifact, not only the templates. Broken links, metadata drift and draft leakage are properties of generated output.
Treat the hosting account as an observed boundary. Portable standard tools were a better fit than assuming optional software existed.
Preservation checks should be strict. The server-rules newline failure looked small, but rejecting and restoring was safer than silently changing unmanaged content.
A static site still needs release engineering. Few runtime components reduce failure modes; they do not remove the need for identity checks, backups, receipts and public verification.
Automated accessibility is necessary but incomplete. Browser and Axe coverage finds regressions, while manual assistive-technology work remains explicitly open.

Public references

Operational evidence remains in the private project repository. This public record deliberately omits hosting identities, account details, fingerprints and credential material.