From f3a6fa41aab2782bf9fc31309994771c509865f4 Mon Sep 17 00:00:00 2001 From: bits-bytes-nn Date: Tue, 17 Nov 2026 23:08:33 +0900 Subject: [PATCH 1/3] fix: rank search results, and review-round fixes 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. --- .gitignore | 1 - _config.yml | 10 +- _includes/head.html | 44 +++--- _layouts/post.html | 4 +- _plugins/image_dimensions.rb | 13 ++ _plugins/lazy_images.rb | 3 - _plugins/post_toc.rb | 21 ++- _sass/_dark.scss | 1 + _sass/_layout.scss | 7 +- _sass/_post.scss | 20 ++- _sass/_search.scss | 3 + docs/architecture.md | 69 +++++---- index.html | 5 + js/search.js | 257 ++++++++++++++++++++-------------- paper-reviews.md | 11 +- search.json | 5 +- search.md | 8 +- test/test_fetch_citations.rb | 8 +- test/test_image_dimensions.rb | 15 ++ test/test_post_toc.rb | 20 ++- 20 files changed, 329 insertions(+), 196 deletions(-) diff --git a/.gitignore b/.gitignore index 770a198..f7b2021 100644 --- a/.gitignore +++ b/.gitignore @@ -40,7 +40,6 @@ _site .claude/ .idea/ .run/ -_posts_bak/ # Editor and toolchain leftovers node_modules/ diff --git a/_config.yml b/_config.yml index a183c0f..a94e599 100644 --- a/_config.yml +++ b/_config.yml @@ -156,11 +156,7 @@ social: protocols: - # Default social card image, used only when a page sets no `cover`. The old - # value was my_logo.png declared as 612x605 — the file is actually 192x192, - # below the 200x200 floor Facebook/LinkedIn need to render a card at all. - # my_header_image.jpg is the site cover and its declared size is real. + # Default social card image, used only when a page sets no `cover` (the site + # cover; at least 200x200, or Facebook/LinkedIn render no card). head.html + # reads its size from the file. fb_image: /assets/my_header_image.jpg - fb_image_width: 1920 - fb_image_height: 600 - fb_image_type: image/jpeg diff --git a/_includes/head.html b/_includes/head.html index da0854d..17ca7b4 100644 --- a/_includes/head.html +++ b/_includes/head.html @@ -10,15 +10,13 @@ {%- assign page_description = page.description | default: site.description | shorten_meta -%} {%- comment -%} - A page `cover` is a wide banner of unknown size, so its dimensions are not - declared — crawlers measure it themselves. Only the configured default image - ships width/height, because those values are verified against the file. + The page's cover, else the site's default image. Its size is read from the + file (image_size, _plugins/image_dimensions.rb), so a link preview can lay + out before the image arrives. {%- endcomment -%} -{%- if page.cover -%} - {%- assign social_image = page.cover | prepend: site.baseurl | prepend: site.url -%} -{%- else -%} - {%- assign social_image = site.protocols.fb_image | prepend: site.baseurl | prepend: site.url -%} -{%- endif -%} +{%- assign social_src = page.cover | default: site.protocols.fb_image -%} +{%- assign social_image = social_src | prepend: site.baseurl | prepend: site.url -%} +{%- assign social_size = social_src | image_size -%} {%- assign page_lang = page.lang | default: site.lang -%} {%- if page_lang == 'en' -%} @@ -122,10 +120,10 @@ - {% unless page.cover %} - - - {% endunless %} + + {% if social_size %} + + {% endif %} {% if page.layout == 'post' %} {% if page.last_modified_at %} @@ -185,6 +183,10 @@ "image": "{{ social_image }}", "author": { "@type": "Person", "name": {{ site.author | jsonify }}, "url": "{{ '/about/' | prepend: site.baseurl | prepend: site.url }}" }, "publisher": { "@type": "Person", "name": {{ site.author | jsonify }} }, + {%- comment -%} The paper a paper post is about, by its DOI. {%- endcomment -%} + {%- if page.paper_doi %} + "about": { "@type": "ScholarlyArticle", "sameAs": {{ page.paper_doi | prepend: 'https://doi.org/' | jsonify }} }, + {%- endif %} "keywords": {{ page.tags | join: ', ' | replace: '-', ' ' | jsonify | replace: '<', '\u003c' }} } @@ -219,12 +221,12 @@ diff --git a/test/test_fetch_citations.rb b/test/test_fetch_citations.rb index a8145fe..0dd5794 100644 --- a/test/test_fetch_citations.rb +++ b/test/test_fetch_citations.rb @@ -129,9 +129,10 @@ def test_published_counts_are_taken_only_in_the_shape_written LIVE = "https://example.org/citations.json" # run() in a scratch dir; returns [what it returned, the file, the notes]. - def run_with(*answers, key: "") + def run_with(*answers, key: "", existing: nil) Dir.mktmpdir do |dir| out = File.join(dir, "citations.json") + File.write(out, existing) if existing notes = [] answering(*answers) data = CitationFetch.run(%w[arXiv:1 arXiv:2], out: out, published_url: LIVE, key: key, @@ -176,9 +177,10 @@ def test_an_unusable_answer_falls_back_too end def test_with_nothing_to_write_the_file_is_left_alone - data, file, notes = run_with(*Array.new(5) { response(429) }, response(404)) + before = JSON.generate("fetched_at" => "2026-11-01T00:00:00Z", "papers" => {}) + data, file, notes = run_with(*Array.new(5) { response(429) }, response(404), existing: before) assert_nil data - assert_nil file + assert_equal JSON.parse(before), file assert_match(/not updated/, notes.last[1]) end end diff --git a/test/test_image_dimensions.rb b/test/test_image_dimensions.rb index 887b751..fbe4839 100644 --- a/test/test_image_dimensions.rb +++ b/test/test_image_dimensions.rb @@ -6,6 +6,8 @@ # themselves rather than to whichever files happen to be in assets/. require "minitest/autorun" +require "tmpdir" +require "fileutils" require_relative "../_plugins/image_dimensions" class TestImageDimensions < Minitest::Test @@ -85,4 +87,17 @@ def test_leaves_the_tag_alone_when_the_file_is_missing_or_unreadable assert_equal html, ImageDimensions.apply(html) { nil } assert_equal html, ImageDimensions.apply(html) { "not an image" } end + + # The filter head.html declares the social image's size with. + def test_image_size_reads_a_repo_file_and_nil_for_none + Dir.mktmpdir do |dir| + FileUtils.mkdir_p(File.join(dir, "assets")) + File.binwrite(File.join(dir, "assets/c.jpg"), jpeg(1920, 1005)) + filter = Object.new.extend(ImageSizeFilter) + site = Struct.new(:source).new(dir) + filter.instance_variable_set(:@context, Struct.new(:registers).new({ site: site })) + assert_equal [1920, 1005], filter.image_size("/assets/c.jpg") + assert_nil filter.image_size("/assets/missing.jpg") + end + end end diff --git a/test/test_post_toc.rb b/test/test_post_toc.rb index 9925701..0a4022f 100644 --- a/test/test_post_toc.rb +++ b/test/test_post_toc.rb @@ -11,8 +11,23 @@ def toc(html) end def test_one_entry_per_h2_with_an_id - html = %(

One

x

Sub

No id

Data

Two

) - assert_equal [{ "id" => "a", "text" => "One", "num" => 1 }, { "id" => "c", "text" => "Two", "num" => 2 }], toc(html) + html = %(

One

x

Sub

No id

Data

Two

Three

) + assert_equal [{ "id" => "a", "text" => "One", "num" => 1, "level" => 2 }, + { "id" => "c", "text" => "Two", "num" => 2, "level" => 2 }, + { "id" => "e", "text" => "Three", "num" => 3, "level" => 2 }], toc(html) + end + + # RAPTOR, LLaMA and GraphRAG: two h2s, each with many h3s. + def test_too_few_h2s_bring_in_the_h3s_unnumbered + html = %(

Part 1

One

Two

Part 2

Three

No

) + entries = toc(html) + assert_equal %w[a a1 a2 b b1], entries.map { |e| e["id"] } + assert_equal [2, 3, 3, 2, 3], entries.map { |e| e["level"] } + assert(entries.all? { |e| e["num"].nil? }) + end + + def test_two_h2s_and_no_h3s_stay_too_short_to_show + assert_equal 2, toc(%(

A

B

)).size end def test_tags_are_stripped_and_entities_kept @@ -21,6 +36,7 @@ def test_tags_are_stripped_and_entities_kept def test_self_numbered_headings_get_no_number assert_nil toc(%(

1. 배경

2. 방법

결론

)).first["num"] + assert_equal 1, toc(%(

배경

방법

결론

)).first["num"] assert_equal 1, toc(%(

1. 배경

방법

결론

)).first["num"] end From 9824b53b74ad825b7ea17395d15e369e1699ee6c Mon Sep 17 00:00:00 2001 From: bits-bytes-nn Date: Tue, 17 Nov 2026 23:17:51 +0900 Subject: [PATCH 2/3] fix: search follows IME composition; nested TOC; review follow-ups - 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. --- _includes/head.html | 2 +- _layouts/post.html | 19 +++++++++++--- _plugins/post_toc.rb | 3 +++ _sass/_layout.scss | 4 +++ _sass/_post.scss | 7 ++--- docs/architecture.md | 8 ++++-- js/search.js | 60 ++++++++++++++++++++++++++++++------------- search.md | 2 +- test/test_post_toc.rb | 5 ++++ 9 files changed, 82 insertions(+), 28 deletions(-) diff --git a/_includes/head.html b/_includes/head.html index 17ca7b4..4174d24 100644 --- a/_includes/head.html +++ b/_includes/head.html @@ -185,7 +185,7 @@ "publisher": { "@type": "Person", "name": {{ site.author | jsonify }} }, {%- comment -%} The paper a paper post is about, by its DOI. {%- endcomment -%} {%- if page.paper_doi %} - "about": { "@type": "ScholarlyArticle", "sameAs": {{ page.paper_doi | prepend: 'https://doi.org/' | jsonify }} }, + "about": { "@type": "ScholarlyArticle", "name": {{ page.title | jsonify | replace: '<', '\u003c' }}, "identifier": {{ page.paper_doi | jsonify }}, "sameAs": {{ page.paper_doi | prepend: 'https://doi.org/' | jsonify }} }, {%- endif %} "keywords": {{ page.tags | join: ', ' | replace: '-', ' ' | jsonify | replace: '<', '\u003c' }} } diff --git a/_layouts/post.html b/_layouts/post.html index ff75453..b0ca6ce 100644 --- a/_layouts/post.html +++ b/_layouts/post.html @@ -86,10 +86,23 @@

{{ page.title | escape }}

{{ toc.size }} + {%- comment -%} + h3s (level 3, _plugins/post_toc.rb) nest under the h2 before them, so + a screen reader hears the sections and their parts. + {%- endcomment %} {% endif %} {% endif %} diff --git a/_plugins/post_toc.rb b/_plugins/post_toc.rb index e93bd8d..4657bc5 100644 --- a/_plugins/post_toc.rb +++ b/_plugins/post_toc.rb @@ -22,6 +22,9 @@ def post_toc(html) heads = html.to_s.scan(HEADING).map { |level, id, inner| [level.to_i, id, inner.gsub(/<[^>]+>/, "").strip] } top = heads.select { |level, _, _| level == 2 } heads = top if top.size >= MIN + # An h3 before the first h2 has no section to sit under: list it as one. + first_h2 = heads.index { |level, _, _| level == 2 } || heads.size + heads = heads.each_with_index.map { |(level, id, text), i| [i < first_h2 ? 2 : level, id, text] } # Numbers count h2s only: with h3s among them, "1 … 14" would number sections # and their parts alike, so the list goes unnumbered and the h3s indented. unnumbered = heads.count { |_, _, text| text.match?(SELF_NUMBERED) } > heads.size / 2.0 || diff --git a/_sass/_layout.scss b/_sass/_layout.scss index 531c35a..9b77828 100644 --- a/_sass/_layout.scss +++ b/_sass/_layout.scss @@ -483,6 +483,10 @@ blockquote { min-width: 24px; min-height: 24px; @media (max-width: $tablet - 1px) { + // The menu's items are right-aligned: the icon keeps that edge. + display: inline-flex; + align-items: center; + justify-content: flex-end; min-width: 44px; min-height: 44px; } diff --git a/_sass/_post.scss b/_sass/_post.scss index 9fcef28..d005b44 100644 --- a/_sass/_post.scss +++ b/_sass/_post.scss @@ -95,9 +95,10 @@ font-size: 0.92em; } - // An h3, listed when the post has too few h2s (_plugins/post_toc.rb). - .toc-sub { - margin-left: 1.2em; + // h3s, listed under their h2 when the post has too few h2s + // (_plugins/post_toc.rb). + ul ul { + padding: 0 0 0 1.2em; a { font-weight: 400; } } diff --git a/docs/architecture.md b/docs/architecture.md index 8bd2445..b37ce9f 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -209,10 +209,14 @@ site. with the page, and runs any query typed while it downloads. It shows "Loading the search index…", and "Search could not load" on failure. It keeps the query in the address bar (`?q=`), so a search can be linked, and runs it on load. -- A post matches when every query word is in its title, tags, category or body. +- A post matches when every query word is in its title, tags, category or body + (not its date). Matches rank by where the words are (`WEIGHTS`: title, then tags, category, body, with a little for how often the body has them), then newest first. A - translation pair counts once (`translation`). The status gives the real total; + translation pair counts once (`translation`): the post in the site's language + when both match, at the better score. The results follow every keystroke, + a Korean syllable still being composed included; the spoken status waits for + it. The status gives the real total; 10 results show, and "Show 10 more" adds the next ones and moves focus to the first of them. - Each result's title and excerpt carry its post's `lang`; the excerpt is cut diff --git a/js/search.js b/js/search.js index b422b2c..abcccc4 100644 --- a/js/search.js +++ b/js/search.js @@ -203,20 +203,29 @@ }); } - // Matching posts, best first; of a translation pair, the better-scoring one - // (the original on a tie, since it is the newer by a second). + // The site's language (site.lang): of a translation pair that both match, the + // post in it is shown, at the better score of the two; the twin only when it + // alone matches (an English query the Korean original lacks). + var SITE_LANG = searchInput.getAttribute('data-site-lang'); + + // Matching posts, best first, newest first on a tie; a pair counts once. function rank(words) { - var seen = {}; - return docs + var matched = docs .map(function (doc) { return { doc: doc, score: score(doc, words) }; }) - .filter(function (r) { return r.score > 0; }) - .sort(function (a, b) { return b.score - a.score || a.doc.order - b.doc.order; }) - .filter(function (r) { - var pair = r.doc.post.translation; - if (!pair) return true; - if (seen[pair]) return false; - return (seen[pair] = true); - }); + .filter(function (r) { return r.score > 0; }); + var pairs = {}; + matched.forEach(function (r) { + var pair = r.doc.post.translation; + if (!pair) return; + var kept = pairs[pair]; + if (!kept) { pairs[pair] = r; return; } + var mine = r.doc.post.lang === SITE_LANG; + var best = Math.max(kept.score, r.score); + if (mine) { r.score = best; pairs[pair] = r; } else { kept.score = best; } + }); + return matched + .filter(function (r) { var pair = r.doc.post.translation; return !pair || pairs[pair] === r; }) + .sort(function (a, b) { return b.score - a.score || a.doc.order - b.doc.order; }); } function text(v) { return String(v == null ? '' : v); } @@ -242,9 +251,18 @@ html += ''; } resultsContainer.innerHTML = html; + // The status is announced (aria-live): mid-composition it would read out a + // half-typed syllable, so it waits for the syllable to be done. + if (!composing) announce(words); + } + function announce(words) { var query = searchInput.value.trim(); var n = results.length; + if (!words.length) { + statusEl.textContent = ''; + return; + } if (n === 0) { statusEl.textContent = words.length > 1 ? 'No post contains every word of "' + query + '". Try fewer words.' @@ -261,7 +279,7 @@ if (!words.length) { results = []; resultsContainer.innerHTML = ''; - statusEl.textContent = ''; + if (!composing) statusEl.textContent = ''; return; } results = rank(words); @@ -307,19 +325,25 @@ searchInput.addEventListener(type, start, { once: true }); }); - // Mid-composition (a Korean syllable still being typed) the results and the - // status would follow a half-typed word; they update when it is done. + // The results follow every keystroke, a syllable still being composed + // included: a Korean IME (or a phone keyboard composing a whole word) keeps + // the last one open until Space, Enter or blur. Only the spoken status waits. + var composing = false; var runTimer; function scheduleRun() { if (!ready) return; clearTimeout(runTimer); runTimer = setTimeout(run, 80); } - searchInput.addEventListener('input', function (e) { - if (!e.isComposing) scheduleRun(); + searchInput.addEventListener('compositionstart', function () { composing = true; }); + searchInput.addEventListener('compositionend', function () { + composing = false; + scheduleRun(); + }); + searchInput.addEventListener('input', function () { + scheduleRun(); syncUrl(); }); - searchInput.addEventListener('compositionend', scheduleRun); var linked = new URLSearchParams(window.location.search).get('q'); if (linked && !searchInput.value) searchInput.value = linked; diff --git a/search.md b/search.md index 754a092..c15f9bf 100644 --- a/search.md +++ b/search.md @@ -14,7 +14,7 @@ sitemap: false ---
-

diff --git a/test/test_post_toc.rb b/test/test_post_toc.rb index 0a4022f..fb84733 100644 --- a/test/test_post_toc.rb +++ b/test/test_post_toc.rb @@ -26,6 +26,11 @@ def test_too_few_h2s_bring_in_the_h3s_unnumbered assert(entries.all? { |e| e["num"].nil? }) end + def test_an_h3_before_any_h2_is_listed_as_a_section + entries = toc(%(

Preface

A

A1

)) + assert_equal [2, 2, 3], entries.map { |e| e["level"] } + end + def test_two_h2s_and_no_h3s_stay_too_short_to_show assert_equal 2, toc(%(

A

B

)).size end From 9e32675268ec94b38b47174e65172c190935c5a8 Mon Sep 17 00:00:00 2001 From: bits-bytes-nn Date: Tue, 17 Nov 2026 23:22:38 +0900 Subject: [PATCH 3/3] fix: keep the search status current while composing; save ?q= on leave - 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. --- _sass/_post.scss | 1 + docs/architecture.md | 5 +++-- js/search.js | 38 +++++++++++++++++++++++--------------- 3 files changed, 27 insertions(+), 17 deletions(-) diff --git a/_sass/_post.scss b/_sass/_post.scss index d005b44..1f593b6 100644 --- a/_sass/_post.scss +++ b/_sass/_post.scss @@ -99,6 +99,7 @@ // (_plugins/post_toc.rb). ul ul { padding: 0 0 0 1.2em; + li { font-size: inherit; } // not 0.92em of 0.92em a { font-weight: 400; } } diff --git a/docs/architecture.md b/docs/architecture.md index b37ce9f..533948f 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -215,8 +215,9 @@ site. body, with a little for how often the body has them), then newest first. A translation pair counts once (`translation`): the post in the site's language when both match, at the better score. The results follow every keystroke, - a Korean syllable still being composed included; the spoken status waits for - it. The status gives the real total; + a Korean syllable still being composed included; the status is spoken + (`aria-live`) only once the syllable is done. A query is kept in `?q=` even + when a result is clicked straight after typing. The status gives the real total; 10 results show, and "Show 10 more" adds the next ones and moves focus to the first of them. - Each result's title and excerpt carry its post's `lang`; the excerpt is cut diff --git a/js/search.js b/js/search.js index abcccc4..32d5f36 100644 --- a/js/search.js +++ b/js/search.js @@ -154,16 +154,22 @@ // The query in the address bar (?q=), so a search can be shared and survives // going back to it. // Debounced: Safari throws after 100 replaceState calls in 30 seconds. - var syncTimer; + var syncTimer = null; + function writeUrl() { + clearTimeout(syncTimer); + syncTimer = null; + var url = new URL(window.location.href); + var query = searchInput.value.trim(); + if (query) url.searchParams.set('q', query); else url.searchParams.delete('q'); + try { history.replaceState(null, '', url); } catch (e) {} + } function syncUrl() { clearTimeout(syncTimer); - syncTimer = setTimeout(function () { - var url = new URL(window.location.href); - var query = searchInput.value.trim(); - if (query) url.searchParams.set('q', query); else url.searchParams.delete('q'); - try { history.replaceState(null, '', url); } catch (e) {} - }, 400); + syncTimer = setTimeout(writeUrl, 400); } + // Leaving before the wait is over (a result clicked straight after typing) + // still records the query, so Back returns to it. + window.addEventListener('pagehide', function () { if (syncTimer !== null) writeUrl(); }); // Up to BODY_CAP occurrences of `word` in `text` (both lowercase). function occurrences(text, word) { @@ -251,9 +257,7 @@ html += ''; } resultsContainer.innerHTML = html; - // The status is announced (aria-live): mid-composition it would read out a - // half-typed syllable, so it waits for the syllable to be done. - if (!composing) announce(words); + announce(words); } function announce(words) { @@ -279,7 +283,7 @@ if (!words.length) { results = []; resultsContainer.innerHTML = ''; - if (!composing) statusEl.textContent = ''; + statusEl.textContent = ''; return; } results = rank(words); @@ -327,17 +331,21 @@ // The results follow every keystroke, a syllable still being composed // included: a Korean IME (or a phone keyboard composing a whole word) keeps - // the last one open until Space, Enter or blur. Only the spoken status waits. - var composing = false; + // the last one open until Space, Enter or blur. var runTimer; function scheduleRun() { if (!ready) return; clearTimeout(runTimer); runTimer = setTimeout(run, 80); } - searchInput.addEventListener('compositionstart', function () { composing = true; }); + // The status is shown throughout but spoken (aria-live) only once the + // syllable is done: mid-composition it would read out a half-typed one. + searchInput.addEventListener('compositionstart', function () { + statusEl.setAttribute('aria-live', 'off'); + }); searchInput.addEventListener('compositionend', function () { - composing = false; + statusEl.setAttribute('aria-live', 'polite'); + statusEl.textContent = ''; // so the same words are announced again scheduleRun(); }); searchInput.addEventListener('input', function () {