Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion .github/workflows/deploy.yml
Original file line number Diff line number Diff line change
Expand Up @@ -25,7 +25,7 @@ jobs:
cache: 'npm'

- name: Install dependencies
run: npm install
run: npm ci

- name: Build website
run: npm run build
Expand Down
39 changes: 39 additions & 0 deletions .github/workflows/quality.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,39 @@
name: Website quality

on:
pull_request:
push:
branches: [main]

permissions:
contents: read

jobs:
check:
runs-on: ubuntu-latest
env:
DOCUSAURUS_SSG_WORKER_THREADS: 2
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: 24
cache: npm
- run: npm ci
- run: npm run check
- name: Audit the production homepage
run: |
npm run preview -- build 4174 > /tmp/ultrarag-preview.log 2>&1 &
preview_pid=$!
trap 'kill "$preview_pid"' EXIT
for attempt in {1..30}; do
if curl --fail --silent http://127.0.0.1:4174/ > /dev/null; then break; fi
sleep 1
done
npm run audit:lighthouse -- http://127.0.0.1:4174/ artifacts/lighthouse
- uses: actions/upload-artifact@v4
if: always()
with:
name: lighthouse-reports
path: artifacts/lighthouse
if-no-files-found: ignore
2 changes: 2 additions & 0 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -18,3 +18,5 @@
npm-debug.log*
yarn-debug.log*
yarn-error.log*

/artifacts/
35 changes: 28 additions & 7 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,11 +1,32 @@
```bash
npm config set registry https://registry.npmmirror.com
# UltraRAG website

The bilingual UltraRAG promotional website, built with Docusaurus and deployed to GitHub Pages.

Use Node.js 22.19+ (CI uses Node.js 24). Lighthouse 13 requires this minimum version.

```sh
npm ci
npm run check
npm run preview
```

`check` runs the regression tests, creates the production build, and checks local links and media across the generated pages. `preview` serves `build/` at <http://127.0.0.1:4174> with HTTP compression. The normal Docusaurus `npm start` and `npm run serve` commands are also available; their development/preview results are not comparable to a compressed production Lighthouse run.

Run Chrome-based mobile and desktop audits against the preview or any public route:

```sh
npm run audit:lighthouse -- http://127.0.0.1:4174/ artifacts/home
npm run audit:lighthouse -- http://127.0.0.1:4174/demo artifacts/demo
```

```bash
npm install
Install Chrome or set `CHROME_PATH`. Reports include HTML, full JSON, and a compact summary. Missing metrics remain `null` and audit errors fail the command. Scores are lab measurements and vary with the host and third-party network availability. The PR workflow uploads homepage reports for review; it does not enforce a flaky performance-score threshold.

To regenerate responsive WebP assets while retaining the original artwork:

```sh
npm run images:optimize
```

```bash
npm run start
```
See [the website audit](docs/audit/2026-11-10.md) for findings, validation, and measurement conditions. Pushes to `main` deploy the website; PR branches run quality checks without deployment.

The lockfile also carries targeted overrides for Docusaurus's worker pool, JavaScript serialization, and SockJS UUID generation. These select patched dependencies while keeping the framework version fixed. CI exercises static generation with two workers, and the SockJS UUID API was smoke-tested. Keep the compatibility checks when changing these constraints; dependency audit details are recorded in the audit notes.
20 changes: 10 additions & 10 deletions blog/2026-01-27-ultrarag-3.0-release.md
Original file line number Diff line number Diff line change
Expand Up @@ -53,12 +53,12 @@ Today, Tsinghua University's THUNLP Lab, Northeastern University's NEUIR Lab, Op
<!-- truncate -->

<En>
<video controls playsinline preload="metadata" className="blogVideo">
<video controls playsinline preload="none" className="blogVideo">
<source src={EnVideo01} type="video/mp4" />
</video>
</En>
<Zh>
<video controls playsinline preload="metadata" className="blogVideo">
<video controls playsinline preload="none" className="blogVideo">
<source src={ZhVideo01} type="video/mp4" />
</video>
</Zh>
Expand Down Expand Up @@ -92,12 +92,12 @@ Let the endpoint of algorithms no longer be cold console logs. UltraRAG 3.0 auto
</Zh>

<En>
<video controls playsinline preload="metadata" className="blogVideo">
<video controls playsinline preload="none" className="blogVideo">
<source src={EnVideo02} type="video/mp4" />
</video>
</En>
<Zh>
<video controls playsinline preload="metadata" className="blogVideo">
<video controls playsinline preload="none" className="blogVideo">
<source src={ZhVideo02} type="video/mp4" />
</video>
</Zh>
Expand Down Expand Up @@ -131,20 +131,20 @@ UltraRAG 3.0 重新定义了 **Chat 界面**——它不仅是用户交互的入
</Zh>

<En>
<video controls playsinline preload="metadata" className="blogVideo">
<video controls playsinline preload="none" className="blogVideo">
<source src={EnVideo03} type="video/mp4" />
</video>

<video controls playsinline preload="metadata" className="blogVideo">
<video controls playsinline preload="none" className="blogVideo">
<source src={EnVideo04} type="video/mp4" />
</video>
</En>
<Zh>
<video controls playsinline preload="metadata" className="blogVideo">
<video controls playsinline preload="none" className="blogVideo">
<source src={ZhVideo03} type="video/mp4" />
</video>

<video controls playsinline preload="metadata" className="blogVideo">
<video controls playsinline preload="none" className="blogVideo">
<source src={ZhVideo04} type="video/mp4" />
</video>
</Zh>
Expand Down Expand Up @@ -219,12 +219,12 @@ We demonstrate four real interaction scenarios here, showing how it transforms n
</Zh>

<En>
<video controls playsinline preload="metadata" className="blogVideo">
<video controls playsinline preload="none" className="blogVideo">
<source src={EnVideo05} type="video/mp4" />
</video>
</En>
<Zh>
<video controls playsinline preload="metadata" className="blogVideo">
<video controls playsinline preload="none" className="blogVideo">
<source src={ZhVideo05} type="video/mp4" />
</video>
</Zh>
2 changes: 1 addition & 1 deletion blog/authors.yml
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@ ms:
name: Sen Mei
title: TsinghuaNLP
url: https://mssssss123.github.io/
image_url: /img/team/ms.png
image_url: /img/team/ms.jpg

xhd:
name: Haidong Xin
Expand Down
63 changes: 63 additions & 0 deletions docs/audit/2026-11-10.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,63 @@
# Website quality audit — November 10, 2026

The audit covers the homepage, desktop/mobile navigation, research, team, contact, release articles, the interactive demo, and the daily paper feed. It preserves the existing white/blue branding and artwork.

## Findings and changes

| Area | Observed problem | Change |
| --- | --- | --- |
| Media | Oversized logo, hero and screenshots; missing intrinsic dimensions and hero priority | Generate responsive WebP variants, reserve aspect ratios, prioritize the hero, and lazy-load secondary images |
| Responsive layout | Large mobile artwork pushed every CTA below the fold; carousel arrows overflowed tablet/narrow desktop layouts; negative hero margin could cover buttons | Put mobile text/actions first, constrain the artwork, wrap CTAs, and keep arrows within the viewport |
| Navigation | The mobile sidebar header (including its close button) was hidden; desktop dropdowns depended on hover | Restore and layer the drawer header; add disclosure buttons, Arrow Down, Escape, focus/outside dismissal, and expanded states |
| Carousel | Automatic rotation continued offscreen and during keyboard interaction; dots were mouse-only | Default to manual navigation, provide an explicit slideshow control and labeled buttons, and pause rotation for focus, hover, hidden pages, offscreen content and reduced motion |
| Accessibility | Low-contrast secondary text, skipped heading levels, unnamed demo controls and incorrect document language | Improve contrast/semantics, add names/focus indicators, synchronize the HTML language with the selected language, and support reduced motion |
| Quick start | Missing clone/build steps, obsolete `examples/sayhello.yaml` and unsupported `--admin` | Show the current `uv run` local-mode build/run/UI commands in both languages; restore code copying |
| Demo lifecycle | An uncancelled thinking timeout could start a response after a session switch; copying dereferenced a React event asynchronously | Own and cancel both streaming phases, clean up on unmount, and give the copy control its own feedback/timer lifecycle |
| Demo UX | Mobile drawer started open, desktop sidebar expanded after hydration, and initial automatic scrolling hid the introduction | Reserve the desktop sidebar during SSR, initially hide the mobile drawer, trap/restore mobile focus, show the start of the sample conversation, and respect readers who scroll up |
| Demo clarity | The preview could be mistaken for live model inference | Keep a visible bilingual notice that replies are pre-recorded; label inputs/send actions and guard IME composition; make sample Markdown web links usable |
| Daily papers | The current feed produced about 16,878 DOM nodes; failures/empty feeds could strand the page | Initially render seven populated dates (about 1,477 nodes in the observed feed), load earlier dates on demand, keep full timeline navigation, cancel/timeout requests, and offer retry/source fallback; validate external link schemes |
| Metadata/content | Missing social-card image and an author avatar referenced a nonexistent PNG; public template page remained | Use existing artwork for sharing metadata, correct the avatar extension and remove the template page |
| Validation | No PR checks or repeatable audits | Add regression tests, strict build/link/anchor validation, a compressed production preview and pinned Lighthouse scripts; upload reports in PR CI |

## Lighthouse measurements

Lighthouse **13.6.0**, Chrome **157**, macOS, fresh headless Chrome profiles. Mobile uses Lighthouse's default simulated mobile network and 4× CPU slowdown; desktop uses its desktop preset. Google Analytics and the GitHub counter remain enabled. Runs were sequential.

The comparison below serves the untouched `main` revision `4a11df3` and the optimized production build through the same local gzip preview with a 600-second cache lifetime. These are lab measurements, not field Core Web Vitals or a claim about an already deployed release.

| Homepage | Performance | Accessibility | Best practices | SEO |
| --- | ---: | ---: | ---: | ---: |
| Baseline, mobile | 92 | 96 | 96 | 92 |
| Optimized, mobile | 97 | 100 | 96 | 100 |
| Baseline, desktop | 100 | 96 | 96 | 92 |
| Optimized, desktop | 100 | 100 | 96 | 100 |

Mobile LCP changed from **3.37 s** to **2.42 s** in these runs. Measured homepage requests fell from approximately **1,053 KiB to 489 KiB** during the audit, including carousel activity. The optimized homepage and demo recorded **CLS 0**. The optimized demo scored **100 / 100 / 96 / 100** on mobile and **100 / 100 / 96 / 100** on desktop.

The initial live-site snapshot (Lighthouse 13.0.3) scored **52 / 96 / 96 / 92** on mobile and **88 / 96 / 96 / 92** on desktop. Its different origin/network conditions make it unsuitable as the numerical baseline for localhost improvements.

The remaining best-practices deduction is a failed Google Analytics collection request in this network environment. Analytics was retained and was not blocked to improve the score. GitHub Pages' cache lifetime is controlled by the host; this PR does not claim to change its response headers. Some framework-wide CSS/JavaScript remains unused on individual routes. Paper freshness depends on the upstream feed, which currently includes many recent empty dates; the website skips empty groups. Re-run the public URL after deployment to assess CDN latency and external services.

## Dependency audit

The untouched main lockfile reported **58 affected dependency entries** (18 critical, 21 high, 15 moderate and 4 low). Updating the audit/image/preview tools, refreshing compatible transitive packages, and applying targeted overrides reduced this to **5 low entries, with no moderate/high/critical entries**. These are npm's propagated package counts, not distinct CVEs. No newly affected package names remain relative to the baseline; the [recorded comparison](dependencies.json) includes the counts and constraints.

The overrides select Tinypool 2.2.0 for Docusaurus's build workers, serialize-javascript 7.1.4, and UUID 11.1.1 for SockJS. Validation explicitly runs static generation with two workers, and SockJS's CommonJS UUID v4 interface was smoke-tested. CI preserves the two-worker check to exercise the upgraded worker pool.

The remaining entries propagate from the [low-severity deepmerge advisory](https://github.com/advisories/GHSA-gcqx-w48m-w2h4), for which no patched release is published as of this audit. They remain visible as follow-up work.

## Validation and reproduction

- Five regression tests cover cancellation during thinking/streaming, final response metadata, and safe external URLs.
- Production compilation checks broken links/anchors; the additional checker verifies links, media and metadata across all 16 generated HTML pages.
- Browser QA covers 320, 390, 768, 1024 and 1440 CSS pixel widths, English/Chinese switching, navigation disclosures/close, keyboard focus, carousel controls, code copying, new chats, session switching, and paper pagination/timeline navigation.
- Article videos use `preload="none"`; the first release video was played and paused successfully, and the original media files remain available.
- `npm run check` runs tests, build and local asset checks. `npm run audit:lighthouse -- <url> <output-directory>` saves both profiles' HTML/JSON reports. Missing metrics and audit errors are not reported as zero scores.

See the repository README for setup and commands. The PR workflow uploads the raw homepage Lighthouse reports; local audit reports are kept outside the tracked source tree. Creating this PR does not deploy the branch or merge it into `main`.

## Preview

![Desktop homepage](desktop-home.png)

![Mobile homepage](mobile-home.png)
39 changes: 39 additions & 0 deletions docs/audit/dependencies.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,39 @@
{
"date": "2026-11-10",
"baselineRef": "4a11df3e4a416fba6bf710601265a91d5ff3a3c7",
"countMeaning": "npm audit affected dependency entries, including graph propagation; not distinct CVEs",
"baseline": {
"info": 0,
"low": 4,
"moderate": 15,
"high": 21,
"critical": 18,
"total": 58
},
"optimized": {
"info": 0,
"low": 5,
"moderate": 0,
"high": 0,
"critical": 0,
"total": 5
},
"newAffectedPackages": [],
"remainingPackages": [
"@docusaurus/plugin-svgr",
"@docusaurus/preset-classic",
"@svgr/plugin-svgo",
"@svgr/webpack",
"deepmerge"
],
"remainingAdvisory": "https://github.com/advisories/GHSA-gcqx-w48m-w2h4",
"overrides": {
"@docusaurus/core": {
"tinypool": "2.2.0"
},
"serialize-javascript": "7.1.4",
"sockjs": {
"uuid": "11.1.1"
}
}
}
Binary file added docs/audit/desktop-home.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/audit/mobile-home.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
11 changes: 7 additions & 4 deletions docusaurus.config.js
Original file line number Diff line number Diff line change
Expand Up @@ -11,11 +11,12 @@ const config = {
url: 'https://ultrarag.github.io',
baseUrl: '/', // 如果你是用 GitHub Pages 且不是自定义域名,这里通常填 '/仓库名/'

organizationName: 'xhd0728', // 你的 GitHub 用户名
organizationName: 'UltraRAG', // 你的 GitHub 用户名
projectName: 'ultrarag.github.io', // 你的仓库名

onBrokenLinks: 'throw',
onBrokenMarkdownLinks: 'warn',
onBrokenAnchors: 'throw',
markdown: { hooks: { onBrokenMarkdownLinks: 'throw' } },

i18n: {
defaultLocale: 'en',
Expand Down Expand Up @@ -50,12 +51,14 @@ const config = {
disableSwitch: true, // 关掉切换开关(像vLLM一样保持风格统一)
respectPrefersColorScheme: false,
},
image: 'img/docusaurus-social-card.jpg',
image: 'img/home/home.jpg',
navbar: {
// title: 'UltraRAG',
logo: {
alt: 'UltraRAG Logo',
src: 'img/_UltraRAG_logo.png',
src: 'img/optimized/_UltraRAG_logo-400.webp',
width: 400,
height: 60,
},
items: [
// ========== 中间区域菜单 (position: left,但会通过 CSS 居中) ==========
Expand Down
Loading
Loading