[jsdoc] Add per-release GitHub release-notes link to sidebar (#1551)

minggangw · web-flow · commit 58801391c194 · 2026-06-24T14:00:45.000+08:00
Add a "Release notes" link to the sidebar of each generated jsdoc release so developers browsing a version's API reference can jump straight to that release's notes for a quick overview of what changed. - tmpl/layout.tmpl: derive the release-notes URL from the package.json `repository.url` (strip the `git+` prefix and `.git` suffix) and render a `brand-release-notes` link under the version badge, pointing at `<repo>/releases/tag/<version>`. Gated on the URL being resolvable, so the link is omitted when no repository is configured. Because the version is the release being documented, the link is always correct without extra logic, and reading the slug from package.json keeps forks/renames working. - static/styles/jsdoc-default.css: add a `.brand-release-notes` style matching the sidebar accent color with an underline on hover. Fix: #1550
diff --git a/tools/jsdoc/static/styles/jsdoc-default.css b/tools/jsdoc/static/styles/jsdoc-default.css
@@ -211,6 +211,17 @@ samp,
     color: var(--text-soft);
 }
 
+.brand-release-notes {
+    width: fit-content;
+    color: var(--accent-strong);
+    font-size: 0.82rem;
+    font-weight: 700;
+}
+
+.brand-release-notes:hover {
+    text-decoration: underline;
+}
+
 .nav-toggle {
     display: none;
     border: 0;
diff --git a/tools/jsdoc/tmpl/layout.tmpl b/tools/jsdoc/tmpl/layout.tmpl
@@ -19,6 +19,23 @@
     var packageName = packageInfo.name || 'rclnodejs';
     var packageVersion = packageInfo.version || '';
     var packageDescription = packageInfo.description || 'ROS 2 client library for Node.js and TypeScript';
+    var repository = packageInfo.repository;
+    var repositoryUrl = '';
+    if (repository) {
+        var repositoryString = (typeof repository === 'string' ? repository : (repository.url || '')).trim();
+        repositoryString = repositoryString
+            .replace(/^git\+/, '')
+            .replace(/#.*$/, '')
+            .replace(/^ssh:\/\//, '')
+            .replace(/^git:\/\//, 'https://')
+            .replace(/^git@([^:/]+)[:/]/, 'https://$1/')
+            .replace(/\.git$/, '')
+            .replace(/\/$/, '');
+        if (/^https?:\/\//.test(repositoryString)) {
+            repositoryUrl = repositoryString;
+        }
+    }
+    var releaseNotesUrl = (repositoryUrl && packageVersion) ? repositoryUrl + '/releases/tag/' + encodeURIComponent(packageVersion) : '';
 ?>
 <body>
 <div class="site-backdrop"></div>
@@ -34,6 +51,9 @@
                 <?js } ?>
             </a>
             <p class="brand-description"><?js= packageDescription ?></p>
+            <?js if (releaseNotesUrl) { ?>
+            <a class="brand-release-notes" href="<?js= releaseNotesUrl ?>" target="_blank" rel="noopener noreferrer">Release notes &#8599;</a>
+            <?js } ?>
         </div>
 
         <button class="nav-toggle" type="button" aria-expanded="false" aria-controls="site-nav">
