Skip to content

docs: keep the theme out of the site URL - #8245

Merged
Sepush merged 4 commits into
tusen-ai:docsfrom
Sepush:docs-theme-out-of-url
Oct 25, 2026
Merged

Sepush merged 4 commits into
tusen-ai:docsfrom
Sepush:docs-theme-out-of-url

Conversation

@Sepush

@Sepush Sepush commented Oct 25, 2026 •

Copy link
Copy Markdown
Collaborator

The docs site put the theme in the path (/zh-CN/os-theme/components/button). The theme is the reader's preference, not part of the page, and having it in the URL means:

  • a shared link carries the sender's theme, not the reader's;
  • the choice is lost when someone comes back through the root address;
  • every theme switch adds a history entry, so Back flips the theme;
  • each page has three URLs (light, dark, os-theme).

This PR keeps the language in the path and moves the theme out of it.

  • URLs: /:lang/docs/... and /:lang/components/.... Menus, search, header and home links follow.
  • Preference: a small useColorMode composable in demo/utils/color-mode.js, shaped after VueUse's: mode is light, dark or auto (follow the OS, via useOsTheme), state is the theme in effect. Only an explicit pick is saved in localStorage (naive-ui-theme); with nothing saved the site follows the OS and updates when the OS switches.
  • One-step switch: like VueUse's disableTransition, transitions are turned off while the colors change, so the page switches at once instead of every component fading on its own.
  • Picker: the header button is now a popselect: Light, Dark or System. On mobile it is a submenu at the top of the menu. Choosing System clears the saved choice.
  • No flash on reload: a small inline script in index.html sets color-scheme on <html> before the first paint, so the page has a dark canvas until the styles load.
  • Tabs: a change in one tab applies to the other open tabs (storage event).
  • Old links keep working: /:lang/(light|dark|os-theme)/... redirects to /:lang/..., keeping the query and hash. The theme in an old link is ignored, so someone else's link doesn't change the reader's setting.

Old naiveui.com/<lang>/os-theme/... URLs in the library source (for example in useMessage's error message) still work through the redirect, so this PR leaves them alone.

Tested in Chromium (headless) against a production build of the site: root redirect by browser language, legacy links with query and hash, OS dark/light with nothing saved, picking each option and reloading, the page already dark with all JS blocked, tab sync, Back after navigation, and the mobile menu. With the CPU throttled 4×, switching on the Data Table page finishes in about 1.3s, against about 2.0–2.5s on naiveui.com.

The last commit is the same change as #8243 (vue-tsc template scope errors in the image and avatar demos), so the docs lint job passes. It is identical to that PR, so the two merge cleanly.

The theme is the reader's preference, not part of the page, so the site
no longer puts it in the path (/zh-CN/os-theme/...).

- Store the choice in localStorage; by default follow the OS
- Pick light, dark or follow-system from a menu in the header
- Apply the theme before the first paint so a reload doesn't flash
- Sync the theme across open tabs
- Redirect old /:lang/(light|dark|os-theme)/... links to /:lang/...
@codecov-commenter

codecov-commenter commented Oct 25, 2026 •

Copy link
Copy Markdown

⚠️ Please install the 'codecov app svg image' to ensure uploads and comments are reliably processed by Codecov.

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 63.56%. Comparing base (7ef48da) to head (2c29ce8).
❗ Your organization needs to install the Codecov GitHub app to enable full functionality.

Additional details and impacted files
@@            Coverage Diff             @@
##             docs    #8245      +/-   ##
==========================================
- Coverage   63.56%   63.56%   -0.01%     
==========================================
  Files         878      878              
  Lines       27467    27487      +20     
  Branches     8730     8524     -206     
==========================================
+ Hits        17460    17471      +11     
- Misses       9793     9803      +10     
+ Partials      214      213       -1     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
  • 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

Write the inline script in current syntax and drop the hard-coded dark
background: color-scheme alone gives the page a dark canvas until the
styles load.
Shaped after VueUse's useColorMode: mode is light, dark or auto (follow
the OS), state is the theme in effect. It stores only an explicit pick,
syncs across tabs, keeps color-scheme on <html> in step, and turns
transitions off while the colors change so the page switches in one step.
Same change as tusen-ai#8243, so the docs lint job passes.
@Sepush
Sepush merged commit 9422a5f into tusen-ai:docs Oct 25, 2026
3 checks passed
@Sepush
Sepush deleted the docs-theme-out-of-url branch October 25, 2026 06:24
Sepush added a commit to Sepush/naive-ui that referenced this pull request Oct 25, 2026
Since the theme left the path (tusen-ai#8245) the home page is the bare locale,
/zh-CN, which the switch didn't match.
Sepush added a commit that referenced this pull request Oct 25, 2026
* docs: serve llms.txt and a Markdown version of every page

Assemble the LLM files from the docs' Markdown sources, without touching
how the site renders them:

- /llms.txt and /zh-CN/llms.txt: an index in site menu order, each link
  with the page's first paragraph
- /llms-full.txt and /zh-CN/llms-full.txt: every page in one file
- /<lang>/<docs|components>/<page>.md: one page, with every demo's title,
  description and source; site components become plain Markdown

Built on request by the dev server and emitted into site/ by the site
build. Each page title gets a menu to copy or view its Markdown.

* docs: add an LLMs page to the menu and point to it from the home page

* docs: call them agents in the LLMs copy

* docs: keep the LLM files readable when served without a charset

naiveui.com serves static files without a charset, so a browser may
misread the Chinese. Start the emitted files with a byte order mark,
serve them with the charset in vite preview, and keep the English
llms.txt ASCII.

* docs: fix the language switch on the home page

Since the theme left the path (#8245) the home page is the bare locale,
/zh-CN, which the switch didn't match.

* docs: build the LLM files with marked and Vue's parsers

- Split the page Markdown with marked's lexer instead of regexes
- Read demos with @vue/compiler-sfc, and parse embedded site components
  with Vue's template parser, one small function per tag
- Resolve links in one pass over the finished Markdown
- TypeScript only: menu-data.js becomes a typed menu-data.ts
- Split the work into site.ts, page-markdown.ts, template-to-markdown.ts
  and llms-txt.ts

This branch was previously deployed

1 inactive deployment
test — 2c29ce80 Deployed Oct 25, 2026 by Sepush via test-browser (24) #11265
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.

2 participants