Sitelet https://github.com/msgwing/ZeroSMTP/pull/246
Skip to content

feat: spis tresci w README, generowany z jego wlasnych naglowkow - #246

Merged
msgwing merged 1 commit into
mainfrom
readme-contents
Aug 23, 2026
Merged

msgwing merged 1 commit into
mainfrom
readme-contents

Conversation

@msgwing

@msgwing msgwing commented Aug 23, 2026

Copy link
Copy Markdown
Owner

Właściciel wskazał awesome-free-apps, które go ma, i zapytał, czemu tego nie widzimy. Słusznie. README ma 311 linii w dziewięciu sekcjach, a 52 z 55 unikalnych odwiedzających ostatnich dwóch tygodni ląduje właśnie tam — bez możliwości przeskoczenia gdziekolwiek.

Generowany, nie pisany — z powodu, który kosztował dziś rano jedenaście stron. Indeks błędów w ERROR-MESSAGES.md był utrzymywany ręcznie, podczas gdy strony obok były generowane, i jedenaście z nich wylądowało w sitemapie bez ani jednego linku. Spis treści ma ten sam tryb porażki: starzeje się w ciszy, bo brakujący wiersz wygląda jak nic.

Sprawdzone, nie założone — i to jest część warta zapamiętania

Oczywista implementacja kotwic (małe litery, usuń interpunkcję, zwiń spacje w myślniki) produkuje w tym pliku dwa martwe linki na dziewięć:

Nagłówek GitHub renderuje
## ⭐ Support ZeroSMTP #-support-zerosmtp
## Security & Deliverability #security--deliverability

Emoji zostaje usunięte i zostawia spację przed słowem, która staje się wiodącym myślnikiem. Ampersand zostaje usunięty i zostawia spacje po obu stronach, które stają się dwoma.

Reguła brzmi: nie przycinaj końców i nie zwijaj ciągów spacji. Znalezione przez odczytanie id z wyrenderowanej strony na github.com, a nie przez rozumowanie — i każda z dziewięciu pasuje teraz do identyfikatora, który tam naprawdę istnieje.

Czego nie dodałem

Osiemnastu stron w docs/ nie ruszam. Nie są sierotami — index.md linkuje dwadzieścia dwie, a układ niesie nawigację. Spis na każdej byłby dekoracją, a PRINTERS.md, jedyna dość długa, żeby go potrzebować, już go ma.

The owner pointed at awesome-free-apps, which has one, and asked why we did not
notice. Fair. README.md is 311 lines across nine sections and 52 of 55 unique
visitors in the last fortnight landed on it with no way to jump. GitHub has an
outline button; it is an icon most readers never press.

Generated rather than written, for a reason that cost something earlier today.
The error-page index in ERROR-MESSAGES.md was maintained by hand while the pages
beside it were generated, and eleven pages ended up in the sitemap with nothing
linking to them. A contents list has the same failure mode: it goes stale in
silence, because a missing row looks like nothing at all.

Checked rather than assumed, and this is the part worth keeping. The obvious
anchor implementation - lowercase, strip punctuation, collapse whitespace to
hyphens - produces two dead links out of nine in this file:

  "## ⭐ Support ZeroSMTP"       GitHub renders #-support-zerosmtp
  "## Security & Deliverability" GitHub renders #security--deliverability

The emoji is removed and leaves the space in front of the word, which becomes a
leading hyphen. The ampersand is removed and leaves the spaces on both sides,
which become two. So the rule is: do not strip the ends and do not collapse
runs. That was found by reading the ids off the rendered page on github.com
rather than by reasoning about it, and every one of the nine now matches an id
that actually exists there.

Not added to the eighteen pages under docs/. They are not orphans - index.md
links twenty-two of them and the layout carries navigation - so a contents list
on each would be decoration, and PRINTERS.md, the one long enough to need one,
already has it.
@msgwing
msgwing enabled auto-merge August 23, 2026 10:28
@msgwing
msgwing merged commit ebc0d74 into main Aug 23, 2026
36 checks passed
@msgwing
msgwing deleted the readme-contents branch August 23, 2026 10:29
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant