GeezerVison

The search box in the top bar currently sends the query to Qwant with site:feyncalc.github.io. This PR replaces that with a search that runs entirely in the browser over the site's own index.

What changes for a reader

• The top-bar box (same place, same look) goes to a new page, /search?q=…. It searches the FeynCalc manual (stable and development), the FeynHelpers manual and the example gallery.
  • Pages whose name matches come first, e.g. Contract, DiracTrace or TID lead straight to their manual pages. After them come the paragraphs that mention the term, each linking to its section anchor.
• Formulas are searchable however they are written. γ^μγ^ν finds \bar{\gamma}^{\mu } \bar{\gamma}^{\nu }, m_μ^2 finds m_{\mu }^2 in the examples' results, and Mathematica's \[Mu] is μ.
  • Results draw formulas with KaTeX.
  • Typing \gam in the box, or clicking Σ, enters a symbol.
• ⌘K / Ctrl-K (or /) on any page opens a jump-to-page palette over the names of all manual pages and examples. Type DiracTr and press Enter.
  • A query that matches no name falls through to the full text in the same list.
  • A ⌘K button sits in the top bar next to the search box.
• No third-party search service. Nothing is sent anywhere; the search works on a local jekyll serve, and offline.
  • The one external file is KaTeX (pinned, with SRI, from jsDelivr), loaded only on /search to draw formulas. Without it they are shown as TeX.

How it works

The engine is sitesearch, a small dependency-free static-site search. It is attached as a git submodule over https, which GitHub Pages fetches itself; in a fresh clone run git submodule update --init.

• _pages/search.html: the search page.
• _includes/head.html: palette.js (⌘K) on every page.
• _includes/topbar.html: the Qwant form and its script are replaced by a form to /search, plus a slot for the ⌘K button.
• css/hyde.css: the palette and the results in the site's colours.
• tools/search-index.js: builds the index of the manuals.
  • Why a script: the manuals are pandoc HTML that Jekyll copies without reading, so their index cannot be built by Liquid. The script uses Node ≥ 16, no npm packages.
  • Output: it writes <book>/search-index.json, <book>/search-index-text/ and nav-index.json.
  • Please rerun node tools/search-index.js (about 1 s) after regenerating the manuals or the examples, and commit the result.
• _data/sitesearch.yml: the site's own Markdown pages are indexed by Jekyll itself (/search-index.json, built by the submodule's Liquid template), which names the manuals' indexes as shards.
• _config.yml:
  • the submodule's docs and checks, and tools/, are excluded from the site. Jekyll's default exclude list is repeated, because listing exclude replaces it.
  • OldForum is excluded from the index with search: false.

What is indexed, and the size

• Two-tier indexes: the manuals are too large for a single index file, so each is split into a word map plus small chunks of text.
  • The maps load on the first query (about 350 KB gzipped in all). After that a query fetches only the few chunks it needs, typically tens of KB.
  • nav-index.json is fetched in idle time on every page so that ⌘K is instant.
  • Altogether the generated files are 6.8 MB over 2624 files.
• What goes into the text: paragraphs, list items, code cells and formulas.
  • The generic "FeynCalc manual (development version)" header of every page is left out.
  • So are the 232 largest output formulas (over 1000 characters of TeX). They would be shown only as cut TeX and no query needs them.
  • Example pages are named by their own description string, e.g. "El Ael -> Mu Amu, QED, total cross section, tree".
• Not indexed: the old forum archive (1600 posts from 2000–2015, 7 MB, about long-gone versions). It would triple the index. It is easy to add as another shard if wanted.

Testing

• Built with the github-pages gem (bundle exec jekyll build, Ruby 3.3): no errors, 2.5 min.
• Tested the built pages in headless Chrome:
  • Contract, DiracTrace and TID list the named pages first (stable, then development manual), then the text hits.
  • Passarino-Veltman, DiracTrace[, $FCDefault and dimensional regularization return the expected pages.
  • The formula queries γ^μγ^ν, m_μ^2 and \gamma^5 return results with the formulas drawn by KaTeX.
• ⌘K tests:
  • the palette opens and its button sits in the top bar;
  • DiracTr → DiracTrace, DiracTraceEvaluate, DiracTrick;
  • contract → Contract first;
  • QED renormalization → the renormalization examples;
  • Grozin falls through to the text of the examples.
• Checked by screenshot that the top bar keeps its look.

Known limits

• Inside the framed manual on /reference*, ⌘K does not fire while focus is in the frame, because the manual pages are generated and carry no script. The top-bar button still works there.
• The indexes go stale if the manuals are regenerated without rerunning tools/search-index.js. Moving the site to a GitHub Pages Actions workflow could make that automatic, but it needs a change in the repository settings, so it is not part of this PR.

Related

#28 fixes 76 manual/example pages where a code cell is shown as raw "```mathematica" text. If #28 is merged first, the indexes here should be rebuilt (node tools/search-index.js) so that the search text matches the fixed pages. I can push that to this branch.

🤖 Generated with Claude Code