From e2f7067808a8c9989447cc145a6231ba7cd18df9 Mon Sep 17 00:00:00 2001 From: Peter Johanson Date: Tue, 25 Nov 2025 02:04:12 -0700 Subject: [PATCH] docs: Add release version to the docs, with links and warning banner Add versions to the sidebar of the documentation, and when viewing the deployment on zmk.dev, which tracks `main`, add a banner warning about possibly prefering the docs for a particular stable release. --- docs/docusaurus.config.js | 60 ++++++++++++++++++++--- docs/src/css/custom.css | 15 ++++++ docs/src/theme/DocVersionBanner/index.tsx | 60 +++++++++++++++++++++++ docs/versions.js | 3 ++ 4 files changed, 131 insertions(+), 7 deletions(-) create mode 100644 docs/src/theme/DocVersionBanner/index.tsx create mode 100644 docs/versions.js diff --git a/docs/docusaurus.config.js b/docs/docusaurus.config.js index 801eac927..aab22f12e 100644 --- a/docs/docusaurus.config.js +++ b/docs/docusaurus.config.js @@ -1,6 +1,34 @@ +const { execSync } = require("child_process"); const path = require("path"); const theme = require("./src/theme/prism/themes/github"); const darkTheme = require("./src/theme/prism/themes/github-dark-dimmed"); +const { releaseVersions } = require("./versions.js"); + +const gitBranch = + process.env.BRANCH || + execSync("git branch --show-current", { encoding: "utf-8" }).trim(); +const isDevelopmentVersion = + gitBranch === "main" || !/^v\d+\.\d+-branch$/.test(gitBranch); +const versionNavbarItems = [ + { + label: "Pre-Release", + description: "Current active development branch (main)", + href: "https://zmk.dev/docs/", + }, + ...releaseVersions.map((r) => ({ + label: "v" + r, + description: "Stable release v" + r, + href: `https://v${r.replaceAll(".", "-")}-branch.zmk.dev/docs/`, + })), +]; + +const versionDropDownLabel = isDevelopmentVersion + ? versionNavbarItems[0].label + : versionNavbarItems.find((item) => { + return item.label === gitBranch.replace("-branch", ""); + }); + +console.error(versionDropDownLabel); module.exports = { title: "ZMK Firmware", @@ -11,6 +39,10 @@ module.exports = { trailingSlash: "false", organizationName: "zmkfirmware", // Usually your GitHub org/user name. projectName: "zmk", // Usually your repo name. + customFields: { + isDevelopmentVersion, + releaseVersions, + }, plugins: [ "@docusaurus/theme-mermaid", path.resolve(__dirname, "src/docusaurus-tree-sitter-plugin"), @@ -51,16 +83,29 @@ module.exports = { label: "Docs", position: "left", }, - { to: "blog", label: "Blog", position: "left" }, + isDevelopmentVersion + ? { to: "blog", label: "Blog", position: "left" } + : { href: "https://zmk.dev/blog", label: "Blog", position: "left" }, { - to: "power-profiler", - label: "Power Profiler", + type: "dropdown", + label: "Tools", position: "left", + items: [ + { + to: "power-profiler", + label: "Power Profiler", + }, + { + to: "keymap-upgrader", + label: "Keymap Upgrader", + }, + ], }, { - to: "keymap-upgrader", - label: "Keymap Upgrader", - position: "left", + type: "dropdown", + label: versionDropDownLabel, + position: "right", + items: versionNavbarItems, }, { href: "https://zmk.studio/", @@ -69,7 +114,8 @@ module.exports = { }, { href: "https://github.com/zmkfirmware/zmk", - label: "GitHub", + "aria-label": "ZMK GitHub Repository", + className: "header-github-link", position: "right", }, ], diff --git a/docs/src/css/custom.css b/docs/src/css/custom.css index e41a8bcec..a016416ce 100644 --- a/docs/src/css/custom.css +++ b/docs/src/css/custom.css @@ -23,6 +23,21 @@ --docusaurus-highlighted-code-line-bg: rgb(255 255 255 / 8%); } +.header-github-link::before { + content: ""; + width: 24px; + height: 24px; + display: flex; + background-color: var(--ifm-navbar-link-color); + mask-image: url("data:image/svg+xml,%3Csvg viewBox='0 0 24 24' xmlns='http://www.w3.org/2000/svg'%3E%3Cpath d='M12 .297c-6.63 0-12 5.373-12 12 0 5.303 3.438 9.8 8.205 11.385.6.113.82-.258.82-.577 0-.285-.01-1.04-.015-2.04-3.338.724-4.042-1.61-4.042-1.61C4.422 18.07 3.633 17.7 3.633 17.7c-1.087-.744.084-.729.084-.729 1.205.084 1.838 1.236 1.838 1.236 1.07 1.835 2.809 1.305 3.495.998.108-.776.417-1.305.76-1.605-2.665-.3-5.466-1.332-5.466-5.93 0-1.31.465-2.38 1.235-3.22-.135-.303-.54-1.523.105-3.176 0 0 1.005-.322 3.3 1.23.96-.267 1.98-.399 3-.405 1.02.006 2.04.138 3 .405 2.28-1.552 3.285-1.23 3.285-1.23.645 1.653.24 2.873.12 3.176.765.84 1.23 1.91 1.23 3.22 0 4.61-2.805 5.625-5.475 5.92.42.36.81 1.096.81 2.22 0 1.606-.015 2.896-.015 3.286 0 .315.21.69.825.57C20.565 22.092 24 17.592 24 12.297c0-6.627-5.373-12-12-12'/%3E%3C/svg%3E"); + transition: background-color var(--ifm-transition-fast) + var(--ifm-transition-timing-default); +} + +.header-github-link:hover::before { + background-color: var(--ifm-navbar-link-hover-color); +} + .docusaurus-highlight-code-line { display: block; margin: 0 calc(-1 * var(--ifm-pre-padding)); diff --git a/docs/src/theme/DocVersionBanner/index.tsx b/docs/src/theme/DocVersionBanner/index.tsx new file mode 100644 index 000000000..2e7fe1332 --- /dev/null +++ b/docs/src/theme/DocVersionBanner/index.tsx @@ -0,0 +1,60 @@ +import { type ReactNode } from "react"; +import clsx from "clsx"; +import useDocusaurusContext from "@docusaurus/useDocusaurusContext"; +import Link from "@docusaurus/Link"; +import { ThemeClassNames } from "@docusaurus/theme-common"; +import type { Props } from "@theme/DocVersionBanner"; + +function ZMKReleaseLink({ version }: { version: string }): ReactNode { + return ( + + v{version} + + ); +} + +function DevWarningBanner({ + className, + latestVersion, +}: Props & { latestVersion: string }): ReactNode { + return ( +
+ You're viewing the documentation for the development version of ZMK. You + may want the latest release . +
+ ); +} + +export default function DocVersionBanner({ className }: Props): ReactNode { + const { + siteConfig: { customFields }, + } = useDocusaurusContext(); + + if ( + !customFields?.releaseVersions || + !Array.isArray(customFields.releaseVersions) + ) { + return null; + } + + const releaseVersions: [string] = customFields.releaseVersions as [string]; + + if (customFields.isDevelopmentVersion) { + return ( + + ); + } + return null; +} diff --git a/docs/versions.js b/docs/versions.js new file mode 100644 index 000000000..9a5d4f530 --- /dev/null +++ b/docs/versions.js @@ -0,0 +1,3 @@ +module.exports = { + releaseVersions: ["0.3"], +};