Update the docs site with some improvements:

[guoci]

added text search, navigation pane, light/dark theme toggle, bluesky link
preview at: https://guoci.github.io/FragPipe_docs/

[fcyu]

Please make minimal changes related to the function you want to implement. Don't change or delete other unrelated files or folders such as .github/ISSUE_TEMPLATE/submit-an-issue.md, fonts, frag-pipe, etc.

Best,

Fengchao

[guoci]

Please make minimal changes related to the function you want to implement. Don't change or delete other unrelated files or folders such as .github/ISSUE_TEMPLATE/submit-an-issue.md, fonts, frag-pipe, etc.

Best,

Fengchao

But this is only on the gh-pages branch, not the default branch.

[fcyu]

But this is only on the gh-pages branch, not the default branch.

I don’t see why you can disregard the other files just because this is the gh-pages branch. They were kept because they might be useful in the future. Some of the files, such as those in the frag-pipe and logo folders, don't have a copy in other branches.

Best,

Fengchao

[fcyu]

Also, I let Claude Code help me review. There will be a big maintenance burden in the future. I am not sure if it's worth it since the benefit is small. There are also bugs, which I don't post here since they are easy to fix and can wait after deciding to use your new implementation.

The core tradeoff

The old stack (_config.yml, _layouts/default.html, .travis.yml) was essentially zero-config Jekyll. The new one pulls in 1,289 locked npm packages (13,057-line pnpm-lock.yaml), Node 24, pnpm, React 19, Tailwind v4, and a hand-written GitHub Actions pipeline. That's the source of every downside below.

1. Maintenance & supply-chain burden (the big one)
1,289 dependencies means perpetual Dependabot churn, npm security advisories, and breaking changes on every Docusaurus/React/Tailwind upgrade. The commit is already riding bleeding edge — future.v4 flag, React 19, Tailwind v4 — and that combination already produced a known problem (the --no-minify / useCssCascadeLayers minification caveat in the config comments). A Docusaurus v3→v4 migration is on the horizon. Jekyll-on-Pages needed none of this; it just kept working.

2. A content edit can now break the entire site
.md files are parsed as MDX, and onBrokenLinks defaults to throw. So a stray <, an unescaped {, a malformed component, or one broken cross-link fails the build and blocks deployment — the whole docs site, not just one page. Jekyll would have rendered the page slightly wrong and moved on. For mass-spec docs full of <10 ppm, m/z, curly braces, and formulas, this is a recurring trip hazard (I already see bare-< cases in 2 files). The fragility moved from "one page looks off" to "nothing deploys."

3. Higher barrier for the people who actually write these docs
The tutorials are maintained by proteomics researchers, not web devs. Previously: edit a .md, push, GitHub builds it. Now: to preview locally you need Node 24 + pnpm + pnpm install (1,289 packages), and a failed build is an opaque webpack/MDX stack trace. That raises the cost of every routine tutorial update.

4. Cross-branch coupling that isn't build-checked
The homepage and og:image hot-link to raw.githubusercontent.com/Nesvilab/FragPipe/develop/images/.... The docs site now silently depends on the app repo's develop branch keeping those image paths stable — and because they're external URLs, the build won't catch it if they move. You've coupled the docs deploy to an unrelated branch's file layout.

5. Heavier delivery
Output is a React SPA bundle plus a client-side search index the browser downloads, versus Jekyll's plain static HTML. Fine for a docs site, but strictly heavier first-load, and the search index grows with content.

6. Operational cutover risk
Going live requires flipping the Pages source from "branch" to "GitHub Actionsng the custom domain persists there (the root CNAME won't ship in theartifact). Combined with the main-branch trigger bug, the site is currently not auto-deployable — a botched cutover takes the live docs down.

What's genuinely better (so it's a fair call)

Real wins motivate this: built-in full-text search, a proper theme + nav, dark mode, reusable MDX components, and a path to versioned docs. Those are things Jekyll didn't give you.

Bottom line: the downside is operational, not financial — hosting stays free, but you've traded a bulletproof, contributor-friendly static setup for a powerful-but-fragile JS framework that needs ongoing dependency upkeep and where a single bad edit can block themeone owns the toolchain maintenance and you add a CI guardrail (a PR-triggered build check — which is exactly what the broken test-deploy.yml was supposed to be). If no one owns that, the maintenance debt will outweigh the search/theme gains.

Best,

Fengchao

[guoci]

Please make minimal changes related to the function you want to implement. Don't change or delete other unrelated files or folders such as .github/ISSUE_TEMPLATE/submit-an-issue.md, fonts, frag-pipe, etc.
Best,
Fengchao

But this is only on the gh-pages branch, not the default branch.

Restored those.