chore(website): version-aware docs URLs via remark plugin

Resolve version-sensitive docs URLs/versions at build time from each page's own path.

Tokens:
- {{yew_dependency}} -> `git = "..."` on next, `version = "X"` on snapshots
- {{yew_api}}        -> preview rustdoc host on next, docs.rs/yew/X on snapshots
- {{yew_version}}    -> latest release on next, X on snapshots (prose/display)

Also fixes the 0.21-0.23 hooks links that wrongly pointed at the next preview host.

Author: Madoshakalaka

website/docs/concepts/function-components/hooks/introduction.mdx

@@ -39,7 +39,7 @@ Yew comes with the following predefined Hooks:
 - `use_context`
 - `use_force_update`
 
-The documentation for these hooks can be found in the [Yew API docs](https://yew-rs-api.web.app/next/yew/functional/)
+The documentation for these hooks can be found in the [Yew API docs]({{yew_api}}functional/)
 
 ### Custom Hooks
 

website/docs/getting-started/build-a-sample-app.mdx

@@ -69,7 +69,7 @@ version = "0.1.0"
 edition = "2021"
 
 [dependencies]
-yew = { git = "https://github.com/yewstack/yew/", features = ["csr"] }
+yew = { {{yew_dependency}}, features = ["csr"] }
 ```
 
 :::info

website/docusaurus.config.js

@@ -1,5 +1,6 @@
 const { API_BUTTON } = require('./src/constants')
 const rustDocHiddenLines = require('./src/remark/rustDocHiddenLines')
+const yewVersionUrls = require('./src/remark/yewVersionUrls')
 
 const editUrl = 'https://github.com/yewstack/yew/blob/master/website/'
 
@@ -170,7 +171,7 @@ module.exports = {
                     sidebarPath: require.resolve('./sidebars/docs.js'),
                     editUrl,
                     routeBasePath: '/docs',
-                    remarkPlugins: [rustDocHiddenLines],
+                    remarkPlugins: [rustDocHiddenLines, yewVersionUrls],
                 },
                 blog: {
                     path: 'blog',

website/src/remark/yewVersionUrls.core.js

@@ -0,0 +1,82 @@
+// Pure, dependency-free helpers for the `yewVersionUrls` remark plugin.
+//
+// Kept separate from the remark wrapper so the interesting logic (deriving the
+// documented version from a file path and expanding tokens) can be unit-tested
+// with plain `node`, without pulling in the unified/unist toolchain.
+
+// The `next` docs document the unreleased API, so they get the git dependency
+// and the preview rustdoc host instead of a released version on docs.rs.
+const GIT_DEPENDENCY = 'git = "https://github.com/yewstack/yew/"'
+const PREVIEW_API_BASE = 'https://yew-rs-api.web.app/next/yew/'
+
+/**
+ * Determine what a docs source file documents, based on its path.
+ *
+ * - `website/docs/**`                              -> "next" (unreleased)
+ * - `website/versioned_docs/version-X/**`          -> X
+ * - `website/i18n/<l>/...content-docs/current/**`   -> "next"
+ * - `website/i18n/<l>/...content-docs/version-X/**` -> X
+ *
+ * @param {string} filePath  absolute or relative path to the .md(x) source
+ * @param {string[]} versions  contents of versions.json, newest first
+ * @returns {{ version: string, isNext: boolean, display: string, dependency: string, api: string }}
+ *   - `display`   : version string for prose (e.g. "0.23"; latest release on next)
+ *   - `dependency`: Cargo.toml specifier (`git = "…"` on next, else `version = "X"`)
+ *   - `api`       : rustdoc base URL for the `yew` crate, ending in `/yew/`
+ *                   (preview host on next, `docs.rs/yew/X/yew/` on snapshots)
+ */
+function versionContextFromPath(filePath, versions) {
+    const latest = versions[0]
+    const norm = String(filePath).replace(/\\/g, '/')
+    // Matches both `versioned_docs/version-0.23/…` and the i18n equivalent
+    // `…/docusaurus-plugin-content-docs/version-0.23/…`.
+    const m = norm.match(/(?:^|\/)version-(\d+\.\d+(?:\.\d+)?)(?:\/|$)/)
+    if (m) {
+        const v = m[1]
+        return {
+            version: v,
+            isNext: false,
+            display: v,
+            dependency: `version = "${v}"`,
+            api: `https://docs.rs/yew/${v}/yew/`,
+        }
+    }
+    // `docs/…` (next) or the i18n `…/current/…` mirror.
+    return {
+        version: latest,
+        isNext: true,
+        display: latest,
+        dependency: GIT_DEPENDENCY,
+        api: PREVIEW_API_BASE,
+    }
+}
+
+// Tokens authors write in the docs. Each resolves from the page's version ctx.
+const TOKENS = {
+    // Cargo.toml: `yew = { {{yew_dependency}}, features = ["csr"] }`
+    '{{yew_dependency}}': (ctx) => ctx.dependency,
+    // Links: `[use_future]({{yew_api}}suspense/fn.use_future.html)`
+    '{{yew_api}}': (ctx) => ctx.api,
+    // Prose: `targets Yew {{yew_version}}`
+    '{{yew_version}}': (ctx) => ctx.display,
+}
+
+/** Replace every known yew token in `value` using `ctx`. */
+function applyTokens(value, ctx) {
+    if (typeof value !== 'string' || value.indexOf('{{yew') === -1) return value
+    let out = value
+    for (const token of Object.keys(TOKENS)) {
+        if (out.indexOf(token) !== -1) {
+            out = out.split(token).join(TOKENS[token](ctx))
+        }
+    }
+    return out
+}
+
+module.exports = {
+    versionContextFromPath,
+    applyTokens,
+    TOKENS,
+    GIT_DEPENDENCY,
+    PREVIEW_API_BASE,
+}

website/src/remark/yewVersionUrls.js

@@ -0,0 +1,40 @@
+const { visit } = require('unist-util-visit')
+const { versionContextFromPath, applyTokens } = require('./yewVersionUrls.core')
+
+// versions.json lives at the website root (../../ relative to src/remark).
+const versions = require('../../versions.json')
+
+/**
+ * Remark plugin: expand `{{yew_dependency}}`, `{{yew_api}}` and `{{yew_version}}`
+ * placeholders to what the current docs page documents.
+ *
+ * `next` resolves to the git dependency and the preview rustdoc host (it documents
+ * the unreleased API); a `version-X` snapshot resolves to `version = "X"` and
+ * `docs.rs/yew/X`. Because each token is resolved from the page's own path at
+ * build time, the snapshots created by `docusaurus docs:version` (and their
+ * translations) keep resolving correctly with no manual edits — which is exactly
+ * the maintenance burden this removes.
+ *
+ * Substitution is applied to text, inline code, fenced code blocks and link /
+ * image URLs, so it works inside ```toml blocks (untouched by MDX interpolation)
+ * as well as in prose links.
+ */
+function yewVersionUrls() {
+    return (tree, file) => {
+        const ctx = versionContextFromPath(
+            file.path || (file.history && file.history[0]) || '',
+            versions
+        )
+
+        visit(tree, (node) => {
+            if (typeof node.value === 'string') {
+                node.value = applyTokens(node.value, ctx) // text, code, inlineCode
+            }
+            if (typeof node.url === 'string') {
+                node.url = applyTokens(node.url, ctx) // link, image, definition
+            }
+        })
+    }
+}
+
+module.exports = yewVersionUrls

website/src/remark/yewVersionUrls.test.js

@@ -0,0 +1,105 @@
+// Standalone unit test for the yew-version remark logic.
+// Run with: `node src/remark/yewVersionUrls.test.js` (no build / node_modules needed).
+const assert = require('assert')
+const { versionContextFromPath, applyTokens } = require('./yewVersionUrls.core')
+
+const VERSIONS = ['0.23', '0.22', '0.21', '0.20']
+let passed = 0
+const check = (name, got, want) => {
+    assert.deepStrictEqual(
+        got,
+        want,
+        `${name}\n  got:  ${JSON.stringify(got)}\n  want: ${JSON.stringify(want)}`
+    )
+    passed++
+}
+
+const NEXT = {
+    version: '0.23',
+    isNext: true,
+    display: '0.23',
+    dependency: 'git = "https://github.com/yewstack/yew/"',
+    api: 'https://yew-rs-api.web.app/next/yew/',
+}
+const V22 = {
+    version: '0.22',
+    isNext: false,
+    display: '0.22',
+    dependency: 'version = "0.22"',
+    api: 'https://docs.rs/yew/0.22/yew/',
+}
+
+// --- version derivation from path (next / snapshot / i18n) ---
+check(
+    'next (docs/)',
+    versionContextFromPath(
+        '/repo/website/docs/getting-started/x.mdx',
+        VERSIONS
+    ),
+    NEXT
+)
+check(
+    'versioned 0.22',
+    versionContextFromPath(
+        '/repo/website/versioned_docs/version-0.22/tutorial/index.mdx',
+        VERSIONS
+    ),
+    V22
+)
+check(
+    'i18n next (current/)',
+    versionContextFromPath(
+        '/repo/website/i18n/ja/docusaurus-plugin-content-docs/current/x.mdx',
+        VERSIONS
+    ),
+    NEXT
+)
+check(
+    'i18n versioned 0.22',
+    versionContextFromPath(
+        '/repo/website/i18n/zh-Hans/docusaurus-plugin-content-docs/version-0.22/x.mdx',
+        VERSIONS
+    ),
+    V22
+)
+
+// --- token substitution: next uses git dep + preview host; snapshots use version + docs.rs ---
+const next = versionContextFromPath('/w/website/docs/x.mdx', VERSIONS)
+const v22 = versionContextFromPath(
+    '/w/website/versioned_docs/version-0.22/x.mdx',
+    VERSIONS
+)
+
+check(
+    'dependency (next -> git)',
+    applyTokens('yew = { {{yew_dependency}}, features = ["csr"] }', next),
+    'yew = { git = "https://github.com/yewstack/yew/", features = ["csr"] }'
+)
+check(
+    'dependency (0.22 -> version)',
+    applyTokens('yew = { {{yew_dependency}}, features = ["csr"] }', v22),
+    'yew = { version = "0.22", features = ["csr"] }'
+)
+check(
+    'api link (next -> preview host)',
+    applyTokens('[use_future]({{yew_api}}suspense/fn.use_future.html)', next),
+    '[use_future](https://yew-rs-api.web.app/next/yew/suspense/fn.use_future.html)'
+)
+check(
+    'api link (0.22 -> docs.rs)',
+    applyTokens('[use_future]({{yew_api}}suspense/fn.use_future.html)', v22),
+    '[use_future](https://docs.rs/yew/0.22/yew/suspense/fn.use_future.html)'
+)
+check(
+    'version token (next)',
+    applyTokens('targets Yew {{yew_version}}', next),
+    'targets Yew 0.23'
+)
+check(
+    'version token (0.22)',
+    applyTokens('targets Yew {{yew_version}}', v22),
+    'targets Yew 0.22'
+)
+check('passthrough (no token)', applyTokens('plain text', next), 'plain text')
+
+console.log(`ok — ${passed} assertions passed`)

website/versioned_docs/version-0.20/concepts/function-components/hooks/introduction.mdx

@@ -38,7 +38,7 @@ Yew comes with the following predefined Hooks:
 - `use_context`
 - `use_force_update`
 
-The documentation for these hooks can be found in the [Yew API docs](https://docs.rs/yew/0.20.0/yew/functional/index.html)
+The documentation for these hooks can be found in the [Yew API docs]({{yew_api}}functional/)
 
 ### Custom Hooks
 

website/versioned_docs/version-0.20/getting-started/build-a-sample-app.mdx

@@ -61,7 +61,7 @@ version = "0.1.0"
 edition = "2021"
 
 [dependencies]
-yew = { version = "0.20.0", features = ["csr"] }
+yew = { {{yew_dependency}}, features = ["csr"] }
 ```
 
 or using `cargo add yew -F csr`.

website/versioned_docs/version-0.21/concepts/function-components/hooks/introduction.mdx

@@ -38,7 +38,7 @@ Yew comes with the following predefined Hooks:
 - `use_context`
 - `use_force_update`
 
-The documentation for these hooks can be found in the [Yew API docs](https://yew-rs-api.web.app/next/yew/functional/)
+The documentation for these hooks can be found in the [Yew API docs]({{yew_api}}functional/)
 
 ### Custom Hooks
 

website/versioned_docs/version-0.21/getting-started/build-a-sample-app.mdx

@@ -69,7 +69,7 @@ version = "0.1.0"
 edition = "2021"
 
 [dependencies]
-yew = { version = "0.21", features = ["csr"] }
+yew = { {{yew_dependency}}, features = ["csr"] }
 ```
 
 or using `cargo add yew@0.21 -F csr`.