beeware · freakboy3742 · Oct 21, 2025 · Oct 15, 2025 · Oct 15, 2025 · Oct 15, 2025
diff --git a/changes/2511.misc.rst b/changes/2511.misc.rst
@@ -0,0 +1 @@
+The Briefcase documentation now includes the missing documentation for the recently introduced asset-gathering strategy for web projects.
diff --git a/docs/reference/platforms/web/static.rst b/docs/reference/platforms/web/static.rst
@@ -97,3 +97,124 @@ and change the default PyScript app name, you could use::
     [[runtimes]]
     src = "https://example.com/custom/pyodide.js"
     """
+
+Deployment Configuration
+========================
+
+Wheels can include information related to deployment that Briefcase will use to
+control how to serve web applications. This includes configuration of the Python
+runtime environment (such as the PyScript version), as well as snippets of HTML,
+CSS or JavaScript that are required for a wheel to behave as expected at runtime.
+
+The deployment configuration is provided by including a ``deploy`` folder in the
+contents of the wheel as a child of the top level package folder. For example, if you
+have a package named ``mypackage``, any content in the wheel in the ``mypackage/deploy``
+folder will be used by Briefcase to aid deployment as a web site.
+
+The following files and file types can be included in the deploy directory:
+
+``config.toml``
+---------------
+
+Deployment settings are defined using a ``config.toml`` file located in the ``deploy``
+folder. The deployment configuration file accepts the following information:
+
+* ``implementation``: The web implementation to use (currently only ``"pyscript"``
+  is supported). If not specified, defaults to ``"pyscript"``.
+
+* ``pyscript.version``: The PyScript version to use (e.g., ``"2024.11.1"``). If not
+  specified, Briefcase will use its default PyScript version.
+
+Example ``config.toml``:
+
+.. code-block:: toml
+
+    implementation = "pyscript"
+
+    [pyscript]
+    version = "2024.11.1"
+
+A Briefcase project must have only one package that defines deployment configuration
+through a ``config.toml`` file. Briefcase will raise an error if multiple packages in
+the dependencies attempt to define deployment settings.
+
+``pyscript.toml``
+-----------------
+
+A package can include a base ``pyscript.toml`` file located at
+``<package>/deploy/pyscript.toml``. The base configuration in this file serves as the
+foundation for Briefcase to generate the final ``pyscript.toml`` file. Briefcase
+will build the final ``pyproject.toml`` file using the following procedure:
+
+1. Briefcase reads the base ``pyscript.toml`` file from the wheel's ``deploy``
+   directory.
+2. Briefcase will add a ``packages`` definition to that base ``pyscript.toml`` that
+   matches the requirements defined in your project's ``pyproject.toml``.
+3. Any :attr:`extra_pyscript_toml_content` from ``pyproject.toml`` will be merged over
+   the top of any existing configuration.
+
+Inserts
+-------
+
+A package can provide snippets of HTML, CSS, and JavaScript content that are to be
+inserted into specific locations (called "slots") in the generated web application. This
+is the recommended way to add custom web resources to your Briefcase web application.
+
+When building an app for deployment, Briefcase will:
+
+1. Scans through all wheel files to detect insert content.
+2. Organize collected inserts according to their target files and slot names.
+3. Writes the accumulated content into designated slots in the target files.
+
+Insert Slots
+~~~~~~~~~~~~
+
+Any file generated by the Briefcase app template can to include slots that indicate
+where inserts should be placed. These slots are code comments that have a specific
+format that Briefcase can use to identify the location for inserted content:
+
+* HTML:
+
+    .. code-block:: html
+
+        <!--@@ slot-name:start @@-->
+        <!--@@ slot-name:end @@-->
+
+* CSS/JavaScript:
+
+    .. code-block:: css
+
+        /*@@ slot-name:start @@*/
+        /*@@ slot-name:end @@*/
+
+Common insert slots in Briefcase web templates include:
+
+* ``head``: Content to insert in the HTML ``<head>`` section of ``index.html``
+* ``head-python``: Content for the ``<head>`` used to configure the Python interpreter
+* ``body-start``: Content at the start of the ``<body>``
+* ``body-python``: Content in the ``<body>`` used to configure the Python interpreter
+* ``body-end``: Content at the end of the ``<body>``
+* ``css``: CSS content to be included in the site stylesheet.
+
+Defining Insert Files
+~~~~~~~~~~~~~~~~~~~~~
+
+Python packages can include inserts by placing files inside the ``deploy/inserts/``
+directory which must use this naming convention:
+
+.. code-block:: text
+
+    <package>/deploy/inserts/<path-to-target-file>~<slot-name>
+
+Where:
+
+* The target file path is specified in relation to the project root directory appears as
+  ``<target-file>`` (e.g., ``index.html`` or ``static/css/briefcase.css``).
+* The tilde (``~``) character separates the target path from the slot name.
+
+For example, a package named ``mypackage`` could include the following files as inserts:
+
+* ``mypackage/deploy/inserts/index.html~head`` - Inserts into the ``head`` slot of
+  ``index.html`` in the root of the deployment directory
+* ``mypackage/deploy/inserts/static/css/briefcase.css~css`` - Inserts into the ``css``
+  slot of ``static/css/briefcase.css``
diff --git a/docs/spelling_wordlist b/docs/spelling_wordlist
@@ -86,6 +86,7 @@ sandboxed
 sandboxing
 scrollable
 Setuptools
+stylesheet
 subdirectories
 subdirectory
 subfolders
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1 @@
		The Briefcase documentation now includes the missing documentation for the recently introduced asset-gathering strategy for web projects.