docs: converge on one product name and link the table of contents#264
Merged
Conversation
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.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Four names
README.md:5,14package.json/ repo / Postman collectiondocs/openapi.base.json,config/swagger-base.js:24OPENROUTER_TITLE(live)Plus two competing descriptions. The OpenAPI title is the public-facing one —
config/swagger.jsserves that artifact verbatim to swagger-ui and downstreamcodegen — so which spelling won was not a cosmetic question.
Now
Alt-Text 4 All, everywhere it is a product name:
package.jsonnamestaysalt-text-generator— npm names cannot containspaces 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.jsonis generated, not editedRegenerated via
npm run openapi:generatefromswagger-base.js:openapi:diffmatters 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.jsonnow runs theopenapijob instead of skipping itas a "docs" path.
Table of contents
All 14 entries already matched their
##headings, so this is navigabilityonly, not a correctness fix. The anchors were generated with the same
slugifyHeadingthe docs gate uses to validate links — so the gate now checksits own output, and a heading renamed without updating the TOC fails the
docscheck rather than rotting silently.
Verification
docs:validate8/0 ·docs:lint0 ·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.