Skip to content

SEO: titles and descriptions that fit, and a standard library reference - #5

Merged
sdogruyol merged 2 commits into
mainfrom
seo
Oct 21, 2026
Merged

sdogruyol merged 2 commits into
mainfrom
seo

Conversation

@sdogruyol

Copy link
Copy Markdown
Collaborator

What

Search engines had little to go on: the home page never said programming language, most descriptions were cut mid-sentence, playground pages were titled by file name, and there was no reference for the standard library at all.

Titles, descriptions, names

  • Home: iyi: the programming language for people and their agents; the heading and lead say programming language.
  • iyilang is the second name: in the colophon and as alternateName (with iyi lang, iyi programming language) in the JSON-LD. "iyi" alone is a common Turkish word and a party's name.
  • Every description is ≤155 characters and every title ≤60; Page.astro fails the build on either. A title that already names iyi no longer gets | iyi appended.
  • Lessons carry searchTitle and description in their frontmatter (Error handling in iyi: errors you cannot ignore).
  • Playground pages lead with their topic from src/playground/topics.json (Arrays in iyi: a runnable example). A tour step's description is its own first comment line; repository samples get an authored about. A page with no entry, or an entry with no page, fails the build.
  • /project/notice/ and /project/conduct/ are noindex and out of the sitemap (third-party / boilerplate text); their titles are no longer Crystal Programming Language.

/reference/

  • 110 std/ modules and 31 prelude types, 621 declarations, each with a heading and an anchor.
  • Signatures and doc comments are iyi doc output, verbatim (not mod dump --json, which drops reopened types and constants). A module's header comment, which no compiler output carries, is read from the source at the tag.
  • npm run record:stdlib writes records/stdlib.json; scripts/stdlib.mjs (in generate) refuses it when the release ships a module it does not cover or a source it was not printed from.
  • In the masthead, llms.txt, and budget.json (three new rows).

Gates touched

  • release-ref.mjs: requireReleaseCompiler also accepts the 7-digit bracketed hash the release's own binary prints ([2a96530]), so the record can be taken with an unpacked release.
  • prose.mjs: doc-comment blocks are exempt. They reach the page as one string from the repository, so the template line-break weld cannot occur, and they contain RFC 6265bis, 0xc0, 1xx.

Verification

  • npm run build against a v0.18.0 worktree: generate, prose, links (225 pages), budget all pass; astro check 0 errors.
  • Built output: no title over 60, no description over 155, no duplicate titles; sitemap 221 URLs without notice/conduct.
  • The description gate failed the build on the old install summary (166 chars) before it was shortened.
  • stdlib.mjs rejects a record with a corrupted digest and a missing module.
  • /reference/, /reference/std/csv/, /reference/prelude/string/ checked in a browser.

…om iyi doc at the release

Every module directly under src/std and every type iyi doc prelude lists gets
a page: the module's header comment out of the source at the tag, then each
declaration under its own heading with its doc comment and its listing as
iyi doc printed it. npm run record:stdlib writes records/stdlib.json;
scripts/stdlib.mjs refuses it when the release ships a module it does not
cover or a file it was not printed from.

requireReleaseCompiler accepts the seven-digit hash the release's own binary
prints, so the record can be taken with an unpacked release. prose.mjs exempts
doc-comment blocks, which reach the page as one string and carry RFC 6265bis,
0xc0 and 1xx.
The home page's title and heading say programming language; iyilang is the
second name, in the colophon and in the structured data. Every description
fits the 155 characters a results page shows and every title its 60, and the
layout fails the build on either. Lessons carry a searchTitle and a
description; playground pages lead with their topic, out of
src/playground/topics.json. The notice and the code of conduct are noindex and
out of the sitemap, and their titles are no longer Crystal's heading.
Reference joins the masthead.
@sdogruyol
sdogruyol merged commit 73024de into main Oct 21, 2026
2 checks passed
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