Pass additional configuration options to the jupyter lite build command

docs/conf.py

@@ -6,6 +6,10 @@
     "myst_parser",
 ]
 
+myst_enable_extensions = [
+    "colon_fence"
+]
+
 html_theme = "pydata_sphinx_theme"
 html_logo = "_static/icon.svg"
 

docs/configuration.md

@@ -75,3 +75,29 @@ jupyterlite_silence = False
 ```
 
 in your Sphinx `conf.py`.
+
+## Additional CLI arguments for `jupyter lite build`
+
+You can pass additional arguments to the `jupyter lite build` command by passing a dictionary of arguments to the `jupyterlite_build_command_options` configuration option, without the hyphens prepended to the keys. Here's an example:
+
+```python
+jupyterlite_build_command_options = {
+    "port": 8888,
+    "XeusAddon.environment_file": "jupyterlite_environment.yml",
+    "source-date-epoch": "315532800",
+    }
+```
+
+This will launch the JupyterLite site on port 8888, configure the `jupyterlite-xeus` kernel with a custom
+`jupyterlite_environment.yml` file, and configure the source date epoch to ensure reproducible builds.
+
+:::{attention}
+The `--contents`, `--output-dir`, and `--lite-dir` options are not supported in this scenario, as they are set by
+the [`jupyterlite_contents`](#jupyterlite-content) and the[`jupyterlite_dir`](#jupyterlite-dir) configuration
+options, respectively, as described above.
+:::
+
+:::{seealso}
+The full list of available options can be found by running the `jupyter lite build --help-all` command. For more
+information, please visit the [JupyterLite documentation](https://jupyterlite.readthedocs.io/en/stable/reference/cli.html#usage).
+:::

jupyterlite_sphinx/jupyterlite_sphinx.py

@@ -572,6 +572,10 @@ def jupyterlite_build(app: Sphinx, error):
 
         jupyterlite_dir = str(app.env.config.jupyterlite_dir)
 
+        jupyterlite_build_command_options: Dict[str, Any] = (
+            app.env.config.jupyterlite_build_command_options
+        )
+
         config = []
         if jupyterlite_config:
             config = ["--config", jupyterlite_config]
@@ -614,6 +618,22 @@ def jupyterlite_build(app: Sphinx, error):
             jupyterlite_dir,
         ]
 
+        if jupyterlite_build_command_options is not None:
+            for key, value in jupyterlite_build_command_options.items():
+                # Check for conflicting options from the default command we use
+                # while building. We don't want to allow these to be overridden
+                # unless they are explicitly set through Sphinx config.
+                if key in ["contents", "output_dir", "lite_dir"]:
+                    jupyterlite_command_error_message = """
+                Cannot use [contents, output_dir, lite_dir] in jupyterlite_build_command_options.
+                Please use the corresponding option directly in conf.py.
+                For a list of available options, run the 'jupyter lite build --help-all'
+                command and refer to the documentation for jupyterlite-sphinx:
+                https://jupyterlite-sphinx.readthedocs.io/en/stable/configuration.html
+                """
+                    raise ValueError(jupyterlite_command_error_message)
+                command.extend([f"--{key}", value])
+
         assert all(
             [isinstance(s, str) for s in command]
         ), f"Expected all commands arguments to be a str, got {command}"
@@ -669,6 +689,9 @@ def setup(app):
     app.add_config_value("jupyterlite_bind_ipynb_suffix", True, rebuild="html")
     app.add_config_value("jupyterlite_silence", True, rebuild=True)
 
+    # Pass a dictionary of additional options to the JupyterLite build command
+    app.add_config_value("jupyterlite_build_command_options", None, rebuild="html")
+
     app.add_config_value("global_enable_try_examples", default=False, rebuild=True)
     app.add_config_value("try_examples_global_theme", default=None, rebuild=True)
     app.add_config_value("try_examples_global_warning_text", default=None, rebuild=True)