Skip to content

Rank search results; review-round fixes - #138

Merged
bits-bytes-nn merged 3 commits into
mainfrom
fix/review-round-1
Nov 17, 2026
Merged

bits-bytes-nn merged 3 commits into
mainfrom
fix/review-round-1

Conversation

@bits-bytes-nn

Copy link
Copy Markdown
Owner

These changes come out of three rounds of adversarial review covering features, UI/UX, SEO and code hygiene, run over the whole blog.

Major: search hid the posts it should show first

simple-jekyll-search stopped at the first 10 matches in posting order and never ranked them. A search for llama listed ten posts that merely mention Llama, and none of the three Llama papers.

js/search.js now does the matching and ranking itself:

  • A post matches only if it contains every query word.
  • Hits are weighted by field: title, then tags, then category, then body. Ties go to the newer post.
  • A ko/en translation pair counts once, preferring the post in site.lang. search.json has a new translation field for this.
  • The status shows the real total, and Show 10 more moves focus to the first new result.
  • Results follow every keystroke, including while a Korean syllable is still being composed. The status updates on screen too, but is announced (aria-live) only once the syllable is done.
  • The unpkg dependency is removed.

Minor fixes

  • TOC: a post with fewer than 3 h2s now lists its h3s too, nested under their h2. RAPTOR, LLaMA, DeepSeek LLM and GraphRAG had no TOC before.
  • Accessibility:
    • The TOC toggle has a dark-mode focus ring.
    • The share links and the phone-menu theme toggle are 44px tap targets.
    • Overflowing equations are role=group instead of landmarks (one post had 19).
    • Lightbox figures stop short of the close button.
  • MathJax: it now reads only \(\) and \[\]. The $$ delimiter was dead config; no built page has a literal $$.
  • SEO:
    • og:image width/height are read from the image file by a new image_size filter. Covers now declare theirs, and the hardcoded fb_image_* sizes are removed.
    • The JSON-LD about names the reviewed paper by name and DOI.
    • The home page has a Korean description.
  • Listings: /paper-reviews/ lists topics in the spec's order.
  • Docs: the :post_read hook order, the search behaviour and the math delimiters now match the code.
  • Tests: the citation "nothing to write" test now checks that an existing file is left untouched.

No change to _data/post_conventions.yml and no new lint rule.

Verification

  • Gates: unit tests (219), lint, actionlint, strict build, htmlproofer and validate-site.sh all pass.
  • Headless Chrome:
    • Search ranking, escaping of HTML-like queries, Show-more focus, composition and ?q= behave as described.
    • All 43 TOCs are balanced.
    • Math-heavy posts render every equation.

Deliberately not done

These need a decision:

  • 147 hotlinked external images, which have no size
  • seo_title on about 15 long-titled generated posts
  • a Korean title suffix for surveys and guides (a spec change shared with scholar-lens)
  • dateModified from hand fixes
  • removing the unused default.jpg covers
  • a JS test runner

Search (the one major finding): simple-jekyll-search stopped at the first
10 matches in posting order, so "llama" listed ten posts that mention
Llama and none of the three Llama papers. js/search.js now matches and
ranks itself: every query word must be in the post; title, tags,
category and body hits are weighted, newest first on a tie; a
translation pair counts once (search.json `translation`); the status
gives the real total and "Show 10 more" adds the rest. The unpkg
dependency goes. A one-word miss no longer says "try fewer words".

Also:
- TOC: a post with fewer than 3 h2s lists its h3s too, indented and
  unnumbered (RAPTOR, LLaMA, DeepSeek LLM, GraphRAG had none).
- Accessibility: dark focus ring on the TOC toggle; 44px share links and
  phone-menu theme toggle; overflowing equations are groups, not
  landmarks; lightbox figures stop short of the close button.
- MathJax reads only \( \) and \[ \]; the `$$` delimiter was dead.
- Social image: width/height read from the file (image_size filter), so
  covers declare theirs; the hardcoded fb_image sizes go.
- JSON-LD names the reviewed paper by DOI (`about`).
- Home page: a Korean description.
- /paper-reviews/ lists topics in the spec's order, as /categories/ does.
- Docs: the :post_read hook order, citations.json in the layout.
- Test: "nothing to write" now checks an existing file is left alone.
- search.js ran only when a composition ended, so the last Korean
  syllable (or a phone keyboard's whole word) was never searched live.
  Results now follow every keystroke; only the spoken status waits.
- Of a translation pair that both match, the post in site.lang is shown.
- The h3s a short-h2 post's TOC lists nest under their h2; an h3 before
  any h2 is listed as a section.
- JSON-LD `about` carries the paper's name and DOI identifier.
- The phone-menu theme toggle keeps the menu's right edge.
- Docs: the date is not searched; composition and pair behaviour.
- The status text updates with the results during IME composition and is
  spoken (aria-live) once the syllable is done, instead of going stale.
- A query typed just before clicking a result is written to ?q= on
  pagehide, so Back returns to it.
- Nested TOC items no longer shrink twice.
@bits-bytes-nn
bits-bytes-nn merged commit 05e1429 into main Nov 17, 2026
3 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