Skip to content

docs: converge on one product name and link the table of contents#264

Merged
jsugg merged 1 commit into
mainfrom
docs/canonical-name-and-toc
Jul 15, 2026
Merged

docs: converge on one product name and link the table of contents#264
jsugg merged 1 commit into
mainfrom
docs/canonical-name-and-toc

Conversation

@jsugg

@jsugg jsugg commented Jul 15, 2026

Copy link
Copy Markdown
Owner

Four names

Surface Was
README.md:5,14 Alt-Text 4 All
package.json / repo / Postman collection alt-text-generator
docs/openapi.base.json, config/swagger-base.js:24 AI-Powered Alternative Text Provider API
Render OPENROUTER_TITLE (live) Alt Text 4 All (no hyphen)

Plus two competing descriptions. The OpenAPI title is the public-facing one —
config/swagger.js serves that artifact verbatim to swagger-ui and downstream
codegen — so which spelling won was not a cosmetic question.

Now

Alt-Text 4 All, everywhere it is a product name:

README.md:5                 Alt-Text 4 All              (already correct)
package.json description    Alt-Text 4 All — ...
config/swagger-base.js      Alt-Text 4 All
docs/openapi.base.json      Alt-Text 4 All              (regenerated)
Postman collection          Alt-Text 4 All API Contract Harness
Render OPENROUTER_TITLE     Alt-Text 4 All              [live, done]

package.json name stays alt-text-generator — npm names cannot contain
spaces or capitals, and it is the package identifier, not the product name. The
repo, the Render service, and the collection filename keep it for the same
reason. That is a deliberate distinction, not an oversight.

The single description is lifted from the README's own overview line rather than
invented, so the package, the API, and the docs repeat wording a reader has
already seen instead of offering a third variant.

docs/openapi.base.json is generated, not edited

Regenerated via npm run openapi:generate from swagger-base.js:

openapi:validate  OK  (8 paths, 8 operations)
openapi:check     OK  matches the generated contract
openapi:diff      OK  backward compatible with origin/main

openapi:diff matters here: title and description are metadata, so no path,
schema, or response moved. Nothing downstream breaks.

Worth noting this PR is the first to exercise #259 in anger — a change touching
docs/openapi.base.json now runs the openapi job instead of skipping it
as a "docs" path.

Table of contents

All 14 entries already matched their ## headings, so this is navigability
only, not a correctness fix. The anchors were generated with the same
slugifyHeading the docs gate uses to validate links — so the gate now checks
its own output, and a heading renamed without updating the TOC fails the docs
check rather than rotting silently.

Verification

docs:validate 8/0 · docs:lint 0 · openapi:validate / check / diff ·
postman:lint (13 folders, 45 requests) · lint · typecheck · 863/863 unit.
The Postman diff is exactly two lines — name and description — with no
reformatting of the 45 requests.

The project answered to four names: "Alt-Text 4 All" in the README,
"alt-text-generator" in package.json and the Postman collection, "AI-Powered
Alternative Text Provider API" in the OpenAPI spec and swagger, and "Alt Text 4
All" (unhyphenated) in the live OPENROUTER_TITLE. Two competing descriptions
came with them. The OpenAPI title is public-facing — it is what swagger-ui and
downstream codegen show — so the spelling mattered beyond tidiness.

Canonical name is now "Alt-Text 4 All" everywhere it is a product name. The one
short description is taken from the README's own overview line rather than
invented, so the docs and the API agree on the wording a reader already saw.

package.json `name` stays alt-text-generator: npm names cannot carry spaces or
capitals, and it is the package identifier rather than the product name. The
repo, service, and collection filename keep it for the same reason.

docs/openapi.base.json is regenerated from swagger-base.js, not hand-edited;
openapi:check confirms it matches the generated contract and openapi:diff
confirms the change is backward compatible — the title and description are
metadata, no path or schema moved.

The table of contents becomes anchor links. All 14 entries already matched their
headings, so this is navigability only. The anchors were generated with the same
slug function the docs gate validates links with, so the gate checks its own
output.
@jsugg
jsugg merged commit 43c990e into main Jul 15, 2026
22 checks passed
@jsugg
jsugg deleted the docs/canonical-name-and-toc branch July 15, 2026 13:48
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant