Rewrite yew.rs with Yew

[Madoshakalaka]

fixes #2779
Replace the Docusaurus-based website with a pure Rust/Yew implementation.

The SSG pipeline compiles each page to WASM, runs wasm-bindgen and wasm-opt, then captures SSR output for SEO-friendly HTML. All docs (5 versions x 4 languages), blog posts, community pages, search, and 404 have standalone index.html with customized <head/> content.

4 major bundles are produced, one for each locale. Once a bundle is loaded, all navigation are done through yew-router and doesn't require re-fetching unless the user navigates to a different locale. See this comment below for more details.

This is a quite faithful rewrite of our old docusaurus based website.

Key features:

• Content model with HTML and Markdown rendering which enables a sane Table of Contents implementation and a copy-as-markdown button on each page (new feature)
• Overhauled the getting-started/examples page to show a gallery of examples, parsed from disk at compile time. (new feature)
• Syntax highlighting via syntect (rust solution) with light/dark themes (old site used prism.js)
• Collapsible sidebar, table of contents, breadcrumbs, and pagination (matching old site)
• 3-state theme toggle (light/dark/system) (matching old site)
• Blog with date-prefixed URLs, index, sidebar, RSS and Atom feeds (matching old site)
• Full-page Algolia search with version faceting (matching old site)
• OpenSearch descriptor, sitemap, robots.txt, 404 page (matching old site)
• SEO: hreflang, OG tags, JSON-LD breadcrumbs, canonical URLs (matching old site)
• wasm bundle and javascript hashing for cache control
• CI workflow builds with Rust toolchain instead of Node.js

Some design choices and notes:

• fantoccini is used for e2e testing the website. Site navigation needs to be tested because version + i18n selectors + side menu interaction can get very tricky. Alternatives to Fantoccini like thirtyfour, chromiumoxide were considered and Fantoccini has the most downloads, most stars, most recent release cadence.
• Code snippet testing and tutorial testing preserved.
• Data-as-code allows us to deduplicate greatly. Next, 0.23, and 0.22 docs are not diverged, which allows 0.23 docs and 0.22 docs to reuse the same data. The number of lines of code is roughly the same: 100k mdx replaced with 100k rust, as we judiciously used multi-line formatting:
  MDX:

  The `use_effect` hook can do many evil things.

  Rust:

  p![
    "The",
    code("use_effect"),
    " hook can do many evil things."
  ]

• We have compile-time validated doc links that go through the spa router:
  External Links:

  link!["https://docs.rs/web-sys/latest/web_sys/struct.Event.html", "Event"]

  Internal Links:

  doc_link!(crate::pages::advanced_topics::struct_components::hoc, "Higher Order Component")

  Internal Links with fragments (correctly working with the scrolling-to behavior):

  doc_link![
      crate::pages::advanced_topics::server_side_rendering,
      #"rendering-head-tags",
      "head rendering section",
  ],

• stylist-rs is used for concise styling (most styles are inlined to the component). Its SSR support renders the same styling during SSG and runtime, causing no content flickering at all.
• the new website uses stable yew (pinned to 0.23 at the moment) for cache friendliness and ecosystem support (stylist-rs and yew-hooks won't work with Yew Next)
• We have version and locale aware home pages now. The Get Started button and the Learn More buttons on each feature card now consume the version and locale too. (new feature)
• Migration guides are no longer versioned. I believe the versioned migration guides were purely a docusaurus artifact. People simply didn't figure out a good place to place the migration guides. Each set of versioned migration guides were exact copies of each other.
• Side bar on the tutorial page eliminated. Was a side bar with a single "Tutorial" item, a docusaurs artifact.
• Categories and subcategories all had {category}/introduction.mdx files. Most pages (7 out of 9) had a slug front matter in the old mdx files so that the slug {category} by itself shows the introduction page, (and {category}/introduction gives a 404). The only two exceptions were: https://yew.rs/docs/next/getting-started/introduction and https://yew.rs/docs/advanced-topics/struct-components/introduction. The new code unifies the aliasing behaviour. It means old urls to docs/next/getting-started/introduction and docs/advanced-topics/struct-components/introduction will hit 404.
• the url of the tutorial page was prefixed with the /docs/ slug. It doesn't make sense as the nav bar suggests "tutorial" and "docs" are on the same level, handled just like the Community pages and Blog pages with no "docs" prefix. I have removed the docs prefix from the tutorial's url. This will also cause some 404s to old references.

Future Considerations

• we might want to embed the playground directly into yew.rs now. We can make code blocks actually runnable.
• use const fn or macros to groups localized strings together, further reduction of code size.
  This is not easy because the subject-verb-object order in different languages are different.

[github-actions]

Size Comparison

Details

examples	master (KB)	pull request (KB)	diff (KB)	diff (%)
async_clock	100.818	100.818	0	0.000%
boids	168.448	168.469	+0.021	+0.012%
communication_child_to_parent	94.076	94.076	0	0.000%
communication_grandchild_with_grandparent	105.914	105.912	-0.002	-0.002%
communication_grandparent_to_grandchild	102.257	102.256	-0.001	-0.001%
communication_parent_to_child	91.486	91.486	0	0.000%
contexts	105.977	105.975	-0.002	-0.002%
counter	86.798	86.798	0	0.000%
counter_functional	88.834	88.833	-0.001	-0.001%
dyn_create_destroy_apps	90.713	90.715	+0.002	+0.002%
file_upload	99.812	99.811	-0.001	-0.001%
function_delayed_input	94.807	94.813	+0.007	+0.007%
function_memory_game	173.664	173.668	+0.004	+0.002%
function_router	395.375	395.708	+0.333	+0.084%
function_todomvc	164.955	164.969	+0.014	+0.008%
futures	235.551	235.548	-0.003	-0.001%
game_of_life	105.099	105.099	0	0.000%
immutable	259.314	259.627	+0.312	+0.121%
inner_html	81.341	81.341	0	0.000%
js_callback	109.957	109.963	+0.006	+0.005%
keyed_list	180.407	180.403	-0.004	-0.002%
mount_point	84.714	84.714	0	0.000%
nested_list	113.660	113.662	+0.002	+0.002%
node_refs	92.087	92.088	+0.001	+0.001%
password_strength	1719.252	1719.288	+0.036	+0.002%
portals	93.560	93.560	0	0.000%
router	366.017	366.360	+0.344	+0.094%
suspense	113.962	113.961	-0.001	-0.001%
timer	88.943	88.943	0	0.000%
timer_functional	99.368	99.367	-0.001	-0.001%
todomvc	142.661	142.661	0	0.000%
two_apps	86.711	86.711	0	0.000%
web_worker_fib	136.457	136.455	-0.002	-0.001%
web_worker_prime	187.640	187.637	-0.003	-0.002%
webgl	83.486	83.485	-0.001	-0.001%

✅ None of the examples has changed their size significantly.

[github-actions]

Visit the preview URL for this PR (updated for commit 8d46462):

https://yew-rs--pr4069-yew-docs-185gwe7t.web.app

_{(expires Mon, 06 Apr 2026 21:19:29 GMT)}

_{🔥 via Firebase Hosting GitHub Action 🌎}

[Madoshakalaka]

@WorldSEnder still a draft PR but any opinions are welcome. you can already try the wasm website in the preview URL

[Madoshakalaka]

Size Note:
every doc page is ~1.7 MB of WASM (700 kB after compression). Home pages (which skip syntect) are only ~378 KB (120 kB after compression).

[Madoshakalaka]

SPA: we still generate all static pages. But we make it have dynamic navigation between them.

This is now implemented. Each locale (en, ja, zh-Hans, zh-Hant) has one SPA binary powered by yew-router that covers all 5 doc versions + migration guides. Version switching is client-side (no WASM re-download), locale switching triggers a full reload. This is identical to docusaurus behavior. The rationale I think is version switching is much frequent than locale switching.

Architecture:

• 4 new SPA crates (spa-en/, spa-ja/, spa-zh-hans/, spa-zh-hant/) with Route enums using wildcard paths
• SSG compiles 4 SPA binaries instead of ~1,100 per-page binaries, then hardlinks WASM/JS to each page directory
• SSR unchanged: each page still gets unique meta tags, hreflang, JSON-LD, descriptions
• Blog, community, and home pages are unchanged (still per-page binaries)

Per-page WASM download went from ~1.7 MB (per navigation) to ~2.8 MB (once per session, then all version/page switches are instant. 930 kB after compression, seems acceptible). Full build time in CI reduces tenfold (90 minutes -> 11 minutes).

[Madoshakalaka]

As previously commented, a huge bloat is syntect. We don't have codeblocks on a lot of pages like the home page and the getting-started/examples page.

But the SPA approach now inevitably bundles it.

after #3932 lands though, we can delay loading the CodeBlock component.

This will even beat docusaurus. Note docusaurs based getting-started/examples and getting-started/editor-setup currently load JavaScript of identical size.

[WorldSEnder]

I didn't realize that the plan was to fully replace the mdx documents with their rust source code and I don't agree with this design decision. The components look good, and the macros are also helpful. But I would not want to write a blog post in this format, I would want to write the markdown where this came from.

Compare the above to the markdown:

• Have to learn magic macros (crate::blog_page!, h! etc) which are btw not use imported into the file due to more macro magic in blog_page!
• there is BLOG_POSTS slugs in a separate part, with a magic number index
• my editor understands markdown more or less, it does not understand this. Even with a rust language server running on the side, which takes minutes to start and load the macro and dependencies.

What's the advantage here when using rust code? All files seem to follow a strict form or were there parts that needed manual editing after the conversion?

[Madoshakalaka]

But I would not want to write a blog post in this format, I would want to write the markdown where this came from.

I can get behind this sentiment. Valid concerns.

I'll do some research on mdx parsers and see if we can achieve the same thing with minimal edits to the mdx files.