Consolidate Flutter/Dart version numbers into shared constants

astro.config.mjs

@@ -11,12 +11,16 @@ import opengraphImages from 'astro-opengraph-images';
 import { renderer } from './src/og/renderer.tsx';
 import { readFileSync } from 'node:fs';
 import starlightLlmsTxt from 'starlight-llms-txt';
+import { remarkReplaceVersions } from './src/plugins/replace-versions.ts';
 
 const site = 'https://docs.shorebird.dev/';
 
 // https://astro.build/config
 export default defineConfig({
   site,
+  markdown: {
+    remarkPlugins: [remarkReplaceVersions],
+  },
   vite: {
     plugins: [tailwindcss()],
   },

src/consts.ts

@@ -0,0 +1,5 @@
+export const versions = {
+  flutter: '3.41.4',
+  dart: '3.11.1',
+  flutter_release_date: 'March 2026',
+};

src/content/docs/code-push/ci/codemagic.mdx

@@ -78,12 +78,12 @@ As a preview, our finished `codemagic.yaml` file will look like this:
 definitions:
   environment:
     shared_env: &shared_env
-      flutter: 3.41.4
+      flutter: %flutter_version%
       groups:
         - shorebird
         - play_store
       vars:
-        FLUTTER_VERSION: 3.41.4
+        FLUTTER_VERSION: %flutter_version%
   scripts:
     - &shorebird_install
       name: Install Shorebird
@@ -189,7 +189,7 @@ definitions:
     # Use &shared_env to allow us to reference this environment in other
     #   parts of the file
     shared_env: &shared_env
-      flutter: 3.41.4
+      flutter: %flutter_version%
       groups:
         # Add the shorebird group to make $SHOREBIRD_TOKEN available to
         #   the Shorebird CLI.
@@ -198,7 +198,7 @@ definitions:
         #   available to the Google Play Publishing step.
         - play_store
       vars:
-        FLUTTER_VERSION: 3.41.4
+        FLUTTER_VERSION: %flutter_version%
   scripts:
     # A step to install Shorebird and add it to the host machine's PATH
     - &shorebird_install
@@ -358,7 +358,7 @@ locally.
 definitions:
   environment:
     shared_env: &shared_env
-      flutter: 3.41.4
+      flutter: %flutter_version%
       groups:
         # Export the shorebird group to make $SHOREBIRD_TOKEN available to
         #   the Shorebird CLI.
@@ -370,7 +370,7 @@ definitions:
         # The bundle ID of this example app.
         # Replace this with your app's bundle id.
         BUNDLE_ID: dev.shorebird.codemagic-demo
-        FLUTTER_VERSION: 3.41.4
+        FLUTTER_VERSION: %flutter_version%
   scripts:
     # Download the Shorebird CLI and add it to the PATH.
     - &shorebird_install

src/content/docs/code-push/ci/generic.mdx

@@ -97,7 +97,7 @@ change. If you'd like to pin your CI to a specific Flutter version you can do
 this by adding `--flutter-version` to your command, e.g.
 
 ```
-shorebird release ios --flutter-version=3.41.4 --dart-define=HERO=Mario -- --enable-impeller
+shorebird release ios --flutter-version=%flutter_version% --dart-define=HERO=Mario -- --enable-impeller
 ```
 
 ### Patching

src/content/docs/code-push/release.mdx

@@ -94,7 +94,7 @@ To release with a different Flutter version, you can specify the version using
 the `--flutter-version` flag.
 
 ```
-shorebird release android --flutter-version 3.41.4
+shorebird release android --flutter-version %flutter_version%
 ```
 
 </TabItem>
@@ -166,7 +166,7 @@ To release with a different Flutter version, you can specify the version using
 the `--flutter-version` flag.
 
 ```sh
-shorebird release ios --flutter-version 3.41.4
+shorebird release ios --flutter-version %flutter_version%
 ```
 
 ### Signing issues
@@ -323,7 +323,7 @@ To release with a different Flutter version, you can specify the version using
 the `--flutter-version` flag.
 
 ```
-shorebird release macos --flutter-version 3.41.4
+shorebird release macos --flutter-version %flutter_version%
 ```
 
 </TabItem>
@@ -396,7 +396,7 @@ To release with a different Flutter version, you can specify the version using
 the `--flutter-version` flag.
 
 ```
-shorebird release windows --flutter-version 3.41.4
+shorebird release windows --flutter-version %flutter_version%
 ```
 
 </TabItem>

src/content/docs/flutter-concepts/flutter-sdk-deep-dive.mdx

@@ -323,10 +323,11 @@ modify Dart code (not native code, Flutter engine, or assets).
 
 ## Current best practices for Flutter development in 2026
 
-**Flutter 3.41.4** (March 2026) is the current stable release, bundled with
-**Dart 3.11.1**. Key requirements now include Java 17 minimum for Android, iOS
-13+ minimum, and Android 16KB page size support for Google Play compliance.
-Impeller is fully default across iOS and Android API 29+.
+**Flutter %flutter_version%** (%flutter_release_date%) is the current stable
+release, bundled with **Dart %dart_version%**. Key requirements now include Java
+17 minimum for Android, iOS 13+ minimum, and Android 16KB page size support for
+Google Play compliance. Impeller is fully default across iOS and Android API
+29+.
 
 For static analysis, configure `analysis_options.yaml` to include
 `package:flutter_lints/flutter.yaml` and enable strict mode:

src/content/docs/flutter-concepts/how-to-install-flutter.mdx

@@ -5,11 +5,12 @@ sidebar:
   order: 4
 ---
 
-Flutter 3.41 is the latest stable release as of February 2026, bundled with Dart
-3.11, and installing it correctly from day one, alongside
-[Shorebird](https://shorebird.dev/) for over-the-air updates, eliminates the
-most common developer pain points, such as broken PATH variables, missing
-Android SDK command-line tools, and CocoaPods failures on Apple Silicon.
+Flutter %flutter_version% is the latest stable release as of
+%flutter_release_date%, bundled with Dart %dart_version%, and installing it
+correctly from day one, alongside [Shorebird](https://shorebird.dev/) for
+over-the-air updates, eliminates the most common developer pain points, such as
+broken PATH variables, missing Android SDK command-line tools, and CocoaPods
+failures on Apple Silicon.
 
 This guide covers exact commands and configuration for macOS, Windows, and
 Linux, prioritizing the professional workflow used in production teams. macOS
@@ -82,7 +83,7 @@ Once downloaded, extract the zip to a development directory:
 
 ```bash
 mkdir -p ~/develop
-unzip ~/Downloads/flutter_macos_arm64_3.41.4-stable.zip -d ~/develop/
+unzip ~/Downloads/flutter_macos_arm64_%flutter_version%-stable.zip -d ~/develop/
 ```
 
 For manual installs, add Flutter to your PATH. Since macOS defaults to **zsh**
@@ -171,7 +172,7 @@ and extract it to a path without spaces or special characters (as a reminder,
 never use `C:\Program Files\`). A good choice is `%USERPROFILE%\develop\`:
 
 ```powershell
-Expand-Archive -Path \$env:USERPROFILE\Downloads\flutter_windows_3.41.4-stable.zip -Destination \$env:USERPROFILE\develop\
+Expand-Archive -Path \$env:USERPROFILE\Downloads\flutter_windows_%flutter_version%-stable.zip -Destination \$env:USERPROFILE\develop\
 ```
 
 Next, to add Flutter to your path, configure PATH through **System Properties →
@@ -220,7 +221,7 @@ If you want to install Flutter, manually, download the `.tar.xz` from the
 
 ```bash
 mkdir -p ~/develop
-tar -xf ~/Downloads/flutter_linux_3.41.4-stable.tar.xz -C ~/develop/
+tar -xf ~/Downloads/flutter_linux_%flutter_version%-stable.tar.xz -C ~/develop/
 ```
 
 ```bash

src/content/docs/getting-started/flutter-version.mdx

@@ -48,7 +48,7 @@ to create a release with a different version of Flutter, you can use the
 `--flutter-version` option with the `shorebird release` command:
 
 ```sh
-shorebird release android --flutter-version=3.41.4
+shorebird release android --flutter-version=%flutter_version%
 ```
 
 Any patches created with this release will be built with the version of Flutter

src/plugins/replace-versions.ts

@@ -0,0 +1,34 @@
+import { versions } from '../consts';
+import type { Root, RootContent } from 'mdast';
+
+const replacements: Record<string, string> = {
+  '%flutter_version%': versions.flutter,
+  '%dart_version%': versions.dart,
+  '%flutter_release_date%': versions.flutter_release_date,
+};
+
+const pattern = /%(?:flutter_version|dart_version|flutter_release_date)%/g;
+
+function replaceInString(value: string): string {
+  return value.replace(pattern, (match) => replacements[match] ?? match);
+}
+
+function walk(node: Root | RootContent) {
+  if ('value' in node && typeof node.value === 'string') {
+    node.value = replaceInString(node.value);
+  }
+  if ('url' in node && typeof node.url === 'string') {
+    node.url = replaceInString(node.url);
+  }
+  if ('children' in node && Array.isArray(node.children)) {
+    for (const child of node.children) {
+      walk(child as RootContent);
+    }
+  }
+}
+
+export function remarkReplaceVersions() {
+  return (tree: Root) => {
+    walk(tree);
+  };
+}