EnergySystemsModellingLab · AdrianDAlessandro · Jun 23, 2026 · Jun 23, 2026 · Jun 23, 2026 · Jun 23, 2026
diff --git a/Cargo.toml b/Cargo.toml
@@ -4,7 +4,7 @@ version = "2.1.0"
 authors = ["Hawkes Research Group @ Chemical Engineering, Imperial College London <a.hawkes@imperial.ac.uk>", "Imperial College London RSE Team <ict-rse-team@imperial.ac.uk>"]
 edition = "2024"
 description = "A tool for running simulations of energy systems"
-documentation = "https://energysystemsmodellinglab.github.io/MUSE2"
+homepage = "https://energysystemsmodellinglab.github.io/MUSE2"
 readme = "README.md"
 repository = "https://github.com/EnergySystemsModellingLab/MUSE2"
 license = "GPL-3.0-only"

diff --git a/build-docs.just b/build-docs.just
@@ -42,9 +42,12 @@ header:
     @echo Generating theme/header.hbs
     @uv run docs/generate_header.py
 
-# Build documentation for previous releases
-old: header
-    @# Clean output dir
-    @rm -rf book/release
+# Move the dev docs to the same level as the old docs
+move-dev: header book api
+    @echo Moving dev docs to /dev
+    @uv run docs/move_dev_docs.py
 
+# Build documentation for previous releases
+old: move-dev
+    @echo Building old versions of docs
     @uv run docs/build_old_docs.py
diff --git a/docs/build_old_docs.py b/docs/build_old_docs.py
@@ -85,7 +85,7 @@ def build_docs_for_release(release: str, repo_path: Path, outdir: Path) -> None:
 
 def build_old_docs() -> None:
     """Build documentation for previous releases."""
-    outdir = REPO_ROOT / "book" / "release"
+    outdir = REPO_ROOT / "book"
     outdir.mkdir(parents=True, exist_ok=True)
 
     # Clone this repo to a temporary directory

diff --git a/docs/move_dev_docs.py b/docs/move_dev_docs.py
@@ -0,0 +1,35 @@
+#!/usr/bin/env python3
+#
+# A script to move the development docs into a /dev directory
+
+import shutil
+from pathlib import Path
+from tempfile import TemporaryDirectory
+
+from release import get_releases
+
+REPO_ROOT = Path(__file__).parent.parent.absolute()
+
+
+def move_to_dev() -> None:
+    """Move the built documentation output (`book/`) into `book/dev/`."""
+    bookdir = REPO_ROOT / "book"
+    outdir = REPO_ROOT / "book" / "dev"
+
+    with TemporaryDirectory() as tmpdir:
+        # Move book to temporary directory
+        shutil.move(bookdir, tmpdir)
+        shutil.move(Path(tmpdir) / "book", outdir)
+
+    # Redirect to stable (most recent) version of docs
+    with (bookdir / "index.html").open("w", encoding="utf-8") as f:
+        f.write(f"""<head>
+    <meta
+        http-equiv="Refresh"
+        content="0; URL=./{get_releases()[0]}/index.html"
+    />
+</head>""")
+
+
+if __name__ == "__main__":
+    move_to_dev()
diff --git a/docs/release_notes/v2.1.0.md b/docs/release_notes/v2.1.0.md
@@ -134,14 +134,14 @@ previous versions of MUSE2.
 [#1205]: https://github.com/EnergySystemsModellingLab/MUSE2/pull/1205
 
 <!-- Use absolute links so they work when we paste into release notes box -->
-[`demand.csv`]: https://energysystemsmodellinglab.github.io/MUSE2/release/v2.1.0/file_formats/input_files.html#demandcsv
-[`processes.csv`]: https://energysystemsmodellinglab.github.io/MUSE2/release/v2.1.0/file_formats/input_files.html#processescsv
-[`process_flows.csv`]: https://energysystemsmodellinglab.github.io/MUSE2/release/v2.1.0/file_formats/input_files.html#process_flowscsv
-[`process_availabilities.csv`]: https://energysystemsmodellinglab.github.io/MUSE2/release/v2.1.0/file_formats/input_files.html#process_availabilitiescsv
-[`process_parameters.csv`]: https://energysystemsmodellinglab.github.io/MUSE2/release/v2.1.0/file_formats/input_files.html#process_parameterscsv
-[`process_investment_constraints.csv`]: https://energysystemsmodellinglab.github.io/MUSE2/release/v2.1.0/file_formats/input_files.html#process_investment_constraintscsv
-[`commodities.csv`]: https://energysystemsmodellinglab.github.io/MUSE2/release/v2.1.0/file_formats/input_files.html#commoditiescsv
-[`commodity_levies.csv`]: https://energysystemsmodellinglab.github.io/MUSE2/release/v2.1.0/file_formats/input_files.html#commodity_leviescsv
-[`model.toml`]: https://energysystemsmodellinglab.github.io/MUSE2/release/v2.1.0/file_formats/input_files.html#model-parameters-modeltoml
-[`assets.csv`]: https://energysystemsmodellinglab.github.io/MUSE2/release/v2.1.0/file_formats/input_files.html#assetscsv
-[`settings.toml`]: https://energysystemsmodellinglab.github.io/MUSE2/release/v2.1.0/file_formats/program_settings.html
+[`demand.csv`]: https://energysystemsmodellinglab.github.io/MUSE2/v2.1.0/file_formats/input_files.html#demandcsv
+[`processes.csv`]: https://energysystemsmodellinglab.github.io/MUSE2/v2.1.0/file_formats/input_files.html#processescsv
+[`process_flows.csv`]: https://energysystemsmodellinglab.github.io/MUSE2/v2.1.0/file_formats/input_files.html#process_flowscsv
+[`process_availabilities.csv`]: https://energysystemsmodellinglab.github.io/MUSE2/v2.1.0/file_formats/input_files.html#process_availabilitiescsv
+[`process_parameters.csv`]: https://energysystemsmodellinglab.github.io/MUSE2/v2.1.0/file_formats/input_files.html#process_parameterscsv
+[`process_investment_constraints.csv`]: https://energysystemsmodellinglab.github.io/MUSE2/v2.1.0/file_formats/input_files.html#process_investment_constraintscsv
+[`commodities.csv`]: https://energysystemsmodellinglab.github.io/MUSE2/v2.1.0/file_formats/input_files.html#commoditiescsv
+[`commodity_levies.csv`]: https://energysystemsmodellinglab.github.io/MUSE2/v2.1.0/file_formats/input_files.html#commodity_leviescsv
+[`model.toml`]: https://energysystemsmodellinglab.github.io/MUSE2/v2.1.0/file_formats/input_files.html#model-parameters-modeltoml
+[`assets.csv`]: https://energysystemsmodellinglab.github.io/MUSE2/v2.1.0/file_formats/input_files.html#assetscsv
+[`settings.toml`]: https://energysystemsmodellinglab.github.io/MUSE2/v2.1.0/file_formats/program_settings.html
diff --git a/docs/templates/header.hbs.jinja b/docs/templates/header.hbs.jinja
@@ -90,30 +90,20 @@
     var labelText = document.getElementById("version-label-text");
     var list = document.getElementById("version-list");
 
-    var versionMatch = /\/release\/(v[\d.]+)\//.exec(path);
+    var versionMatch = /\/(v[\d.]+)\//.exec(path);
     var isDev = !versionMatch;
-    var currentVersion = isDev ? "development" : versionMatch[1];
+    var currentVersion = isDev ? "dev" : versionMatch[1];
     var isStable = false;
 
     // Build version list
     var pathToRoot = "{% raw %}{{path_to_root}}{% endraw %}";
     var versions = [
-      { label: "development", stable: false },
+      { label: "dev", stable: false },
 {%- for release in releases %}
       { label: "{{ release.label }}", stable: {{ release.stable|lower }} },
 {%- endfor %}
     ];
 
-    function hrefFor(label) {
-      if (isDev) {
-        if (label === "development") return pathToRoot;
-        return pathToRoot + "release/" + label + "/index.html";
-      }
-      // Old versioned docs (e.g. /release/v2.0.0/)
-      if (label === "development") return pathToRoot + "../../index.html";
-      return pathToRoot + "../" + label + "/index.html";
-    }
-
     versions.forEach(function (v) {
       var li = document.createElement("li");
 
@@ -130,7 +120,7 @@
         li.appendChild(strong);
       } else {
         var a = document.createElement("a");
-        a.href = hrefFor(v.label);
+        a.href = pathToRoot + "../" + v.label + "/index.html";
         a.textContent = versionLabel;
         li.appendChild(a);
       }

diff --git a/schemas/input/model.yaml b/schemas/input/model.yaml
@@ -63,10 +63,8 @@ properties:
     type: object
     description: |
       Used for setting custom HiGHS options. As this is unsafe, it requires setting
-      `please_give_me_broken_results` to true. For more information, see the relevant [section of
-      the developer documentation][highs-opts-docs].
-
-      [highs-opts-docs]: https://energysystemsmodellinglab.github.io/MUSE2/developer_guide/custom_highs_options.html
+      `please_give_me_broken_results` to true. For more information, see the relevant
+      [section of the developer documentation](../developer_guide/custom_highs_options.html).
     properties:
       global_options:
         type: object

diff --git a/src/cli.rs b/src/cli.rs
@@ -21,9 +21,7 @@ use settings::SettingsSubcommands;
     version,
     about,
     after_help = concat!(
-        "For more detailed documentation on this version of MUSE2, see: https://energysystemsmodellinglab.github.io/MUSE2/release/v",
-        env!("CARGO_PKG_VERSION"),
-        "/"
+        "For more detailed documentation on this version of MUSE2, see: ", crate::docs_url!()
     )
 )]
 struct Cli {

diff --git a/src/lib.rs b/src/lib.rs
@@ -4,6 +4,23 @@
 /// The main GitHub issues page for MUSE2
 pub const ISSUES_URL: &str = concat!(env!("CARGO_PKG_REPOSITORY"), "/issues");
 
+/// A macro to get a url to the most recent version of the documentation
+#[macro_export]
+macro_rules! docs_url {
+    () => {
+        docs_url!("")
+    };
+    ($suffix:literal) => {
+        concat!(
+            env!("CARGO_PKG_HOMEPAGE"),
+            "/v",
+            env!("CARGO_PKG_VERSION"),
+            "/",
+            $suffix
+        )
+    };
+}
+
 use dirs::config_dir;
 use std::path::PathBuf;
 

diff --git a/src/settings.rs b/src/settings.rs
@@ -23,8 +23,9 @@ const DEFAULT_SETTINGS_FILE_HEADER: &str = concat!(
 # \tmuse2 settings show-default
 #
 # For information about the possible settings, visit:
-# \thttps://energysystemsmodellinglab.github.io/MUSE2/file_formats/program_settings.html
-"
+# \t",
+    crate::docs_url!("file_formats/program_settings.html"),
+    "\n"
 );
 
 /// Get the path to where the settings file will be read from

diff --git a/src/simulation/optimisation.rs b/src/simulation/optimisation.rs
@@ -511,7 +511,7 @@ fn get_parent_or_self(assets: &[AssetRef]) -> Vec<AssetRef> {
 ///
 /// For a detailed description, please see the [dispatch optimisation formulation][1].
 ///
-/// [1]: https://energysystemsmodellinglab.github.io/MUSE2/model/dispatch_optimisation.html
+#[doc = concat!("[1]: ", crate::docs_url!("/model/dispatch_optimisation.html"))]
 #[must_use = "Must call run() method on DispatchRun struct"]
 pub struct DispatchRun<'model, 'run> {
     model: &'model Model,

diff --git a/src/simulation/optimisation/constraints.rs b/src/simulation/optimisation/constraints.rs
@@ -113,7 +113,7 @@ where
 /// commodity-balance constraint added to `problem` and `keys` lists the
 /// `(commodity, region, time_selection)` entries in the same order as the rows.
 ///
-/// [1]: https://energysystemsmodellinglab.github.io/MUSE2/model/dispatch_optimisation.html#commodity-balance-for--cin-mathbfcmathrmsed-
+#[doc = concat!("[1]: ", crate::docs_url!("model/dispatch_optimisation.html#commodity-balance-for--cin-mathbfcmathrmsed-"))]
 fn add_commodity_balance_constraints<'a, I>(
     problem: &mut Problem,
     variables: &VariableMap,
@@ -207,7 +207,7 @@ where
 /// (upper and lower bounds) are added per selection; in that case the same key is
 /// stored twice to match the solver ordering.
 ///
-/// [1]: https://energysystemsmodellinglab.github.io/MUSE2/model/dispatch_optimisation.html#a4-constraints-capacity--availability-for-standard-assets--a-in-mathbfastd-
+#[doc = concat!("[1]: ", crate::docs_url!("model/dispatch_optimisation.html#a4-constraints-capacity--availability-for-standard-assets--a-in-mathbfastd-"))]
 fn add_activity_constraints<'a, I>(
     problem: &mut Problem,
     variables: &VariableMap,

diff --git a/src/simulation/prices.rs b/src/simulation/prices.rs
@@ -1,6 +1,6 @@
 //! Code for calculating commodity prices used by the simulation.
 //!
-//! See <https://energysystemsmodellinglab.github.io/MUSE2/model/prices.html>
+#![doc = concat!("See <", crate::docs_url!("/model/prices.html"), ">")]
 use crate::asset::AssetRef;
 use crate::commodity::{CommodityID, CommodityMap, PricingStrategy};
 use crate::model::Model;

diff --git a/tests/cli.rs b/tests/cli.rs
@@ -17,7 +17,7 @@ fn check_help_command() {
     assert!(
         get_muse2_stdout(&["help"]).contains(
             format!(
-                "https://energysystemsmodellinglab.github.io/MUSE2/release/v{}/",
+                "https://energysystemsmodellinglab.github.io/MUSE2/v{}/",
                 env!("CARGO_PKG_VERSION")
             )
             .as_str()