feat: spis tresci w README, generowany z jego wlasnych naglowkow - #246
Merged
Merged
Conversation
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.
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.
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.mdbył 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ęć:
## ⭐ Support ZeroSMTP#-support-zerosmtp## Security & Deliverability#security--deliverabilityEmoji 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
idz 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.mdlinkuje dwadzieścia dwie, a układ niesie nawigację. Spis na każdej byłby dekoracją, aPRINTERS.md, jedyna dość długa, żeby go potrzebować, już go ma.