From 19b10d281d100b7003b43c798636f3ceb67211d9 Mon Sep 17 00:00:00 2001 From: Pieter Viljoen Date: Mon, 10 Aug 2026 15:48:10 -0700 Subject: [PATCH] Align the README With the Declared Structure Ten findings, all in the README, and none of them visible to a reader who is not comparing it against the fleet model. The Overview section carried its retired name, Use Cases. Renaming it orphaned the Table of Contents anchor, which markdownlint caught as MD051 rather than shipping a link into nothing, and that is the whole reason a rename is not a one-line change. The link definitions used a Workflow group the model does not declare, and the Repo group held six references to this repository's own GitHub pages, which the model classifies as distribution rather than local. The block is rebuilt into the four declared groups it needs, Shields, Distribution, Repo and External, each sorted by reference name. Every one of the 29 definitions is preserved, and the classification comes from the audit's own link_kind rule against the model's declared URL prefixes rather than from reading the URLs by eye. The 3rd Party Tools table dropped its License column, since a license belongs to the dependency and is authoritative at its source, so restating it is a maintenance obligation carrying no information. Its three rows now use the fleet's own descriptions, because a shared tool carries one description across the fleet rather than a per-repo paraphrase, and the rows are alphabetized, since the list is scanned rather than read. Co-Authored-By: Claude Opus 5 (1M context) --- README.md | 38 +++++++++++++++++++------------------- 1 file changed, 19 insertions(+), 19 deletions(-) diff --git a/README.md b/README.md index b9f406a..3d89568 100644 --- a/README.md +++ b/README.md @@ -33,14 +33,14 @@ See [Release History][history] for complete release notes and older versions. ## Table of Contents -- [Use Cases](#use-cases) +- [Overview](#overview) - [Migration from WordPress](#migration-from-wordpress) - [How a Change Reaches the Site](#how-a-change-reaches-the-site) - [Configuration](#configuration) - [Questions or Issues](#questions-or-issues) - [Development Environment Setup](#development-environment-setup) -## Use Cases +## Overview A personal technical blog, published as a static site and served from a host the author owns. It holds the writing itself and everything needed to put it online, so the site is reproducible from this repository alone. @@ -186,11 +186,11 @@ The deploy root and the base URL come from an untracked file per environment und ## 3rd Party Tools -| Tool | Role | License | -| --- | --- | --- | -| [Hugo][hugo-link] | static site generator | Apache-2.0 | -| [PaperMod][papermod-link] | theme, vendored under `themes/` | MIT | -| [Caddy][caddy-link] | web server, serving the built site and the redirects | Apache-2.0 | +| Tool | Role | +| --- | --- | +| [Caddy][caddy-link] | Web server. | +| [Hugo][hugo-link] | Static site generator. | +| [PaperMod][papermod-link] | Hugo theme. | ## License @@ -199,36 +199,36 @@ Licensed under the [MIT License][license]\ -[pre-release-version-shield]: https://img.shields.io/github/v/release/ptr727/Blog?include_prereleases&label=GitHub%20Pre-Release&logo=github -[release-version-shield]: https://img.shields.io/github/v/release/ptr727/Blog?logo=github&label=GitHub%20Release [last-commit-shield]: https://img.shields.io/github/last-commit/ptr727/Blog?logo=github&label=Last%20Commit [license-shield]: https://img.shields.io/github/license/ptr727/Blog?label=License +[pre-release-version-shield]: https://img.shields.io/github/v/release/ptr727/Blog?include_prereleases&label=GitHub%20Pre-Release&logo=github [release-status-shield]: https://img.shields.io/github/actions/workflow/status/ptr727/Blog/publish-release.yml?event=workflow_dispatch&logo=github&label=Release%20Status +[release-version-shield]: https://img.shields.io/github/v/release/ptr727/Blog?logo=github&label=GitHub%20Release - + [actions-link]: https://github.com/ptr727/Blog/actions +[commits-link]: https://github.com/ptr727/Blog/commits +[discussions-link]: https://github.com/ptr727/Blog/discussions +[github-link]: https://github.com/ptr727/Blog +[issues-link]: https://github.com/ptr727/Blog/issues +[releases-link]: https://github.com/ptr727/Blog/releases -[github-link]: https://github.com/ptr727/Blog -[checks]: ./checks/ -[commits-link]: https://github.com/ptr727/Blog/commits -[deploy]: ./deploy/ [capture]: ./capture/ [capture-readme]: ./capture/README.md -[ops]: ./ops/ -[environment]: ./ENVIRONMENT.md +[checks]: ./checks/ +[deploy]: ./deploy/ [deploy-readme]: ./deploy/README.md -[discussions-link]: https://github.com/ptr727/Blog/discussions -[issues-link]: https://github.com/ptr727/Blog/issues [env-example]: ./example.env +[environment]: ./ENVIRONMENT.md [history]: ./HISTORY.md [hugo-config]: ./hugo.yaml [license]: ./LICENSE [migration-post]: ./content/posts/2026/08/01/moving-this-blog-from-wordpress-to-hugo.md [operations]: ./OPERATIONS.md -[releases-link]: https://github.com/ptr727/Blog/releases +[ops]: ./ops/ [workflow]: ./WORKFLOW.md