From 9d0b830921292d5c28c94b8c8ebdda12e1f06a48 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?David=20R=C3=B6nnqvist?= <ronnqvist@apple.com>
Date: Thu, 18 Dec 2025 14:05:08 +0100
Subject: [PATCH 1/2] Make a tiny simplification to the parameters HTML output
 (#1387)

---
 .../MarkdownRenderer+Parameters.swift         |  8 +---
 .../FileWritingHTMLContentConsumerTests.swift |  8 +---
 .../MarkdownRenderer+PageElementsTests.swift  | 44 +++++--------------
 3 files changed, 15 insertions(+), 45 deletions(-)

diff --git a/Sources/DocCHTML/MarkdownRenderer+Parameters.swift b/Sources/DocCHTML/MarkdownRenderer+Parameters.swift
index a316f6e49..45a43589f 100644
--- a/Sources/DocCHTML/MarkdownRenderer+Parameters.swift
+++ b/Sources/DocCHTML/MarkdownRenderer+Parameters.swift
@@ -78,9 +78,7 @@ package extension MarkdownRenderer {
         for parameter in parameterInfo {
             // name
             items.append(
-                .element(named: "dt", children: [
-                    .element(named: "code", children: [.text(parameter.name)])
-                ])
+                .element(named: "dt", children: [.text(parameter.name)])
             )
             // description
             items.append(
@@ -131,9 +129,7 @@ package extension MarkdownRenderer {
             let index = (offset + primaryOnlyIndices.count(where: { $0 < offset })) * 2
             items.insert(contentsOf: [
                 // Name
-                .element(named: "dt", children: [
-                    .element(named: "code", children: [.text(parameter.name)])
-                ], attributes: ["class": "\(secondary.language.id)-only"]),
+                .element(named: "dt", children: [.text(parameter.name)], attributes: ["class": "\(secondary.language.id)-only"]),
                 // Description
                 .element(named: "dd", children: parameter.content.map { visit($0) }, attributes: ["class": "\(secondary.language.id)-only"])
             ], at: index)
diff --git a/Tests/DocCCommandLineTests/FileWritingHTMLContentConsumerTests.swift b/Tests/DocCCommandLineTests/FileWritingHTMLContentConsumerTests.swift
index 9e20d7feb..6d4297a5f 100644
--- a/Tests/DocCCommandLineTests/FileWritingHTMLContentConsumerTests.swift
+++ b/Tests/DocCCommandLineTests/FileWritingHTMLContentConsumerTests.swift
@@ -347,15 +347,11 @@ final class FileWritingHTMLContentConsumerTests: XCTestCase {
               </section>
               <h2>Parameters</h2>
               <dl>
-                <dt>
-                  <code>first</code>
-                </dt>
+                <dt>first</dt>
                 <dd>
                   <p>Description of the <code>first</code> parameter.</p>
                 </dd>
-                <dt>
-                  <code>second</code>
-                </dt>
+                <dt>second</dt>
                 <dd>
                   <p>Description of the <code>second</code> parameter.</p>
                 </dd>
diff --git a/Tests/DocCHTMLTests/MarkdownRenderer+PageElementsTests.swift b/Tests/DocCHTMLTests/MarkdownRenderer+PageElementsTests.swift
index 0fcbbe58c..1503d7511 100644
--- a/Tests/DocCHTMLTests/MarkdownRenderer+PageElementsTests.swift
+++ b/Tests/DocCHTMLTests/MarkdownRenderer+PageElementsTests.swift
@@ -131,17 +131,13 @@ struct MarkdownRenderer_PageElementsTests {
                 <a href="#Parameters">Parameters</a>
               </h2>
               <dl>
-                <dt>
-                  <code>First</code>
-                </dt>
+                <dt>First</dt>
                 <dd>
                   <p>
                     Some <i>formatted</i> description with <code>code</code>
                   </p>
                 </dd>
-                <dt>
-                  <code>Second</code>
-                </dt>
+                <dt>Second</dt>
                 <dd>
                   <p>
                     Some <b>other</b> <i>formatted</i> description</p>
@@ -154,16 +150,12 @@ struct MarkdownRenderer_PageElementsTests {
             parameters.assertMatches(prettyFormatted: true, expectedXMLString: """
             <h2>Parameters</h2>
             <dl>
-              <dt>
-                <code>First</code>
-              </dt>
+              <dt>First</dt>
               <dd>
                 <p>Some <i>formatted</i>description with <code>code</code>
                 </p>
               </dd>
-              <dt>
-                <code>Second</code>
-              </dt>
+              <dt>Second</dt>
               <dd>
                 <p>
                   Some <b>other</b> <i>formatted</i> description</p>
@@ -194,27 +186,19 @@ struct MarkdownRenderer_PageElementsTests {
             <a href="#Parameters">Parameters</a>
           </h2>
           <dl>
-            <dt>
-              <code>FirstCommon</code>
-            </dt>
+            <dt>FirstCommon</dt>
             <dd>
               <p>Available in both languages</p>
             </dd>
-            <dt class="swift-only">
-              <code>SwiftOnly</code>
-            </dt>
+            <dt class="swift-only">SwiftOnly</dt>
             <dd class="swift-only">
               <p>Only available in Swift</p>
             </dd>
-            <dt>
-              <code>SecondCommon</code>
-            </dt>
+            <dt>SecondCommon</dt>
             <dd>
               <p>Also available in both languages</p>
             </dd>
-            <dt class="occ-only">
-              <code>ObjectiveCOnly</code>
-            </dt>
+            <dt class="occ-only">ObjectiveCOnly</dt>
             <dd class="occ-only">
               <p>Only available in Objective-C</p>
             </dd>
@@ -242,25 +226,19 @@ struct MarkdownRenderer_PageElementsTests {
             <a href="#Parameters">Parameters</a>
           </h2>
           <dl class="swift-only">
-            <dt>
-              <code>First</code>
-            </dt>
+            <dt>First</dt>
             <dd>
               <p>Some description</p>
             </dd>
           </dl>
           <dl class="data-only">
-            <dt>
-              <code>Third</code>
-            </dt>
+            <dt>Third</dt>
             <dd>
               <p>Some description</p>
             </dd>
           </dl>
           <dl class="occ-only">
-            <dt>
-              <code>Second</code>
-            </dt>
+            <dt>Second</dt>
             <dd>
               <p>Some description</p>
             </dd>

From 5a13f10e8849c856396d3ef630951ee0db7a5fdb Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?David=20R=C3=B6nnqvist?= <ronnqvist@apple.com>
Date: Thu, 18 Dec 2025 14:51:40 +0100
Subject: [PATCH 2/2] Add CLI flag to enable DocC adding minimal per-page HTML
 content to each index.html file (#1396)

* Add CLI flag to insert minimal HTML content in each "index.html" file

rdar://163326857

* Support index.html files that are missing the expected HTML elements

* Test that index.html files with content includes the hosting base path

* Support custom header/footer templates alongside the per-page content

* Remove properties that are never read

* Avoid HTML encoding difference between platforms in new test

* Add code comments about confusing test behaviors

* Apply suggestions from code review

Co-authored-by: Andrea Fernandez Buitrago <15234535+anferbui@users.noreply.github.com>

* Fix typo in test data

---------

Co-authored-by: Andrea Fernandez Buitrago <15234535+anferbui@users.noreply.github.com>
---
 .../Actions/Convert/ConvertAction.swift       |  31 +++-
 .../Convert/ConvertFileWritingConsumer.swift  |   2 +-
 .../FileWritingHTMLContentConsumer.swift      |  77 ++++++---
 .../ConvertAction+CommandInitialization.swift |   1 +
 .../ArgumentParsing/Subcommands/Convert.swift |  20 +++
 .../ConvertSubcommandTests.swift              |  31 ++++
 .../FileWritingHTMLContentConsumerTests.swift | 118 +++++++++++++-
 .../StaticHostingWithContentTests.swift       | 150 ++++++++++++++++++
 features.json                                 |   3 +
 9 files changed, 404 insertions(+), 29 deletions(-)
 create mode 100644 Tests/DocCCommandLineTests/StaticHostingWithContentTests.swift

diff --git a/Sources/DocCCommandLine/Action/Actions/Convert/ConvertAction.swift b/Sources/DocCCommandLine/Action/Actions/Convert/ConvertAction.swift
index 62d2baf74..b9fb3a088 100644
--- a/Sources/DocCCommandLine/Action/Actions/Convert/ConvertAction.swift
+++ b/Sources/DocCCommandLine/Action/Actions/Convert/ConvertAction.swift
@@ -30,6 +30,7 @@ public struct ConvertAction: AsyncAction {
     let diagnosticEngine: DiagnosticEngine
 
     private let transformForStaticHosting: Bool
+    private let includeContentInEachHTMLFile: Bool
     private let hostingBasePath: String?
     
     let sourceRepository: SourceRepository?
@@ -64,6 +65,7 @@ public struct ConvertAction: AsyncAction {
     ///   - experimentalEnableCustomTemplates: `true` if the convert action should enable support for custom "header.html" and "footer.html" template files, otherwise `false`.
     ///   - experimentalModifyCatalogWithGeneratedCuration: `true` if the convert action should write documentation extension files containing markdown representations of DocC's automatic curation into the `documentationBundleURL`, otherwise `false`.
     ///   - transformForStaticHosting: `true` if the convert action should process the build documentation archive so that it supports a static hosting environment, otherwise `false`.
+    ///   - includeContentInEachHTMLFile: `true` if the convert action should process each static hosting HTML file so that it includes documentation content for environments without JavaScript enabled, otherwise `false`.
     ///   - allowArbitraryCatalogDirectories: `true` if the convert action should consider the root location as a documentation bundle if it doesn't discover another bundle, otherwise `false`.
     ///   - hostingBasePath: The base path where the built documentation archive will be hosted at.
     ///   - sourceRepository: The source repository where the documentation's sources are hosted.
@@ -91,6 +93,7 @@ public struct ConvertAction: AsyncAction {
         experimentalEnableCustomTemplates: Bool = false,
         experimentalModifyCatalogWithGeneratedCuration: Bool = false,
         transformForStaticHosting: Bool = false,
+        includeContentInEachHTMLFile: Bool = false,
         allowArbitraryCatalogDirectories: Bool = false,
         hostingBasePath: String? = nil,
         sourceRepository: SourceRepository? = nil,
@@ -105,6 +108,7 @@ public struct ConvertAction: AsyncAction {
         self.temporaryDirectory = temporaryDirectory
         self.documentationCoverageOptions = documentationCoverageOptions
         self.transformForStaticHosting = transformForStaticHosting
+        self.includeContentInEachHTMLFile = includeContentInEachHTMLFile
         self.hostingBasePath = hostingBasePath
         self.sourceRepository = sourceRepository
         
@@ -189,6 +193,11 @@ public struct ConvertAction: AsyncAction {
     /// A block of extra work that tests perform to affect the time it takes to convert documentation
     var _extraTestWork: (() async -> Void)?
 
+    /// The `Indexer` type doesn't work with virtual file systems.
+    ///
+    /// Tests that don't verify the contents of the navigator index can set this to `true` so that they can use a virtual, in-memory, file system.
+    var _completelySkipBuildingIndex: Bool = false
+    
     /// Converts each eligible file from the source documentation bundle,
     /// saves the results in the given output alongside the template files.
     public func perform(logHandle: inout LogHandle) async throws -> ActionResult {
@@ -286,7 +295,7 @@ public struct ConvertAction: AsyncAction {
             workingDirectory: temporaryFolder,
             fileManager: fileManager)
 
-        let indexer = try Indexer(outputURL: temporaryFolder, bundleID: inputs.id)
+        let indexer = _completelySkipBuildingIndex ? nil : try Indexer(outputURL: temporaryFolder, bundleID: inputs.id)
 
         let registerInterval = signposter.beginInterval("Register", id: signposter.makeSignpostID())
         let context = try await DocumentationContext(bundle: inputs, dataProvider: dataProvider, diagnosticEngine: diagnosticEngine, configuration: configuration)
@@ -299,9 +308,23 @@ public struct ConvertAction: AsyncAction {
             context: context,
             indexer: indexer,
             enableCustomTemplates: experimentalEnableCustomTemplates,
-            transformForStaticHostingIndexHTML: transformForStaticHosting ? indexHTML : nil,
+            // Don't transform for static hosting if the `FileWritingHTMLContentConsumer` will create per-page index.html files
+            transformForStaticHostingIndexHTML: transformForStaticHosting && !includeContentInEachHTMLFile ? indexHTML : nil,
             bundleID: inputs.id
         )
+        
+        let htmlConsumer: FileWritingHTMLContentConsumer?
+        if includeContentInEachHTMLFile, let indexHTML {
+            htmlConsumer = try FileWritingHTMLContentConsumer(
+                targetFolder: temporaryFolder,
+                fileManager: fileManager,
+                htmlTemplate: indexHTML,
+                customHeader: experimentalEnableCustomTemplates ? inputs.customHeader : nil,
+                customFooter: experimentalEnableCustomTemplates ? inputs.customFooter : nil
+            )
+        } else {
+            htmlConsumer = nil
+        }
 
         if experimentalModifyCatalogWithGeneratedCuration, let catalogURL = rootURL {
             let writer = GeneratedCurationWriter(context: context, catalogURL: catalogURL, outputURL: catalogURL)
@@ -320,7 +343,7 @@ public struct ConvertAction: AsyncAction {
                 try ConvertActionConverter.convert(
                     context: context,
                     outputConsumer: outputConsumer,
-                    htmlContentConsumer: nil,
+                    htmlContentConsumer: htmlConsumer,
                     sourceRepository: sourceRepository,
                     emitDigest: emitDigest,
                     documentationCoverageOptions: documentationCoverageOptions
@@ -375,7 +398,7 @@ public struct ConvertAction: AsyncAction {
         }
         
         // If we're building a navigation index, finalize the process and collect encountered problems.
-        do {
+        if let indexer {
             let finalizeNavigationIndexMetric = benchmark(begin: Benchmark.Duration(id: "finalize-navigation-index"))
             
             // Always emit a JSON representation of the index but only emit the LMDB
diff --git a/Sources/DocCCommandLine/Action/Actions/Convert/ConvertFileWritingConsumer.swift b/Sources/DocCCommandLine/Action/Actions/Convert/ConvertFileWritingConsumer.swift
index 56e492585..9b570988d 100644
--- a/Sources/DocCCommandLine/Action/Actions/Convert/ConvertFileWritingConsumer.swift
+++ b/Sources/DocCCommandLine/Action/Actions/Convert/ConvertFileWritingConsumer.swift
@@ -227,7 +227,7 @@ struct ConvertFileWritingConsumer: ConvertOutputConsumer, ExternalNodeConsumer {
         let template = "<template id=\"\(id.rawValue)\">\(templateContents)</template>"
         var newIndexContents = indexContents
         newIndexContents.replaceSubrange(bodyTagRange, with: indexContents[bodyTagRange] + template)
-        try newIndexContents.write(to: index, atomically: true, encoding: .utf8)
+        try fileManager.createFile(at: index, contents: Data(newIndexContents.utf8))
     }
     
     /// File name for the documentation coverage file emitted during conversion.
diff --git a/Sources/DocCCommandLine/Action/Actions/Convert/FileWritingHTMLContentConsumer.swift b/Sources/DocCCommandLine/Action/Actions/Convert/FileWritingHTMLContentConsumer.swift
index 2fcaf2eae..83db0611a 100644
--- a/Sources/DocCCommandLine/Action/Actions/Convert/FileWritingHTMLContentConsumer.swift
+++ b/Sources/DocCCommandLine/Action/Actions/Convert/FileWritingHTMLContentConsumer.swift
@@ -20,8 +20,6 @@ import SwiftDocC
 import DocCHTML
 
 struct FileWritingHTMLContentConsumer: HTMLContentConsumer {
-    var targetFolder: URL
-    var fileManager: any FileManagerProtocol
     var prettyPrintOutput: Bool
     
     private struct HTMLTemplate {
@@ -30,24 +28,51 @@ struct FileWritingHTMLContentConsumer: HTMLContentConsumer {
         var titleReplacementRange:       Range<String.Index>
         var descriptionReplacementRange: Range<String.Index>
         
-        init(data: Data) throws {
-            let content = String(decoding: data, as: UTF8.self)
+        struct CustomTemplate {
+            var id, content: String
+        }
+        
+        init(data: Data, customTemplates: [CustomTemplate]) throws {
+            var content = String(decoding: data, as: UTF8.self)
             
-            // ???: Should we parse the content with XMLParser instead? If so, what do we do if it's not valid XHTML?
-            let noScriptStart = content.utf8.firstRange(of:  "<noscript>".utf8)!.upperBound
-            let noScriptEnd   = content.utf8.firstRange(of: "</noscript>".utf8)!.lowerBound
+            // Ensure that the index.html file has at least a `<head>` and a `<body>`.
+            guard var beforeEndOfHead  = content.utf8.firstRange(of: "</head>".utf8)?.lowerBound,
+                  var afterStartOfBody = content.range(of: "<body[^>]*>", options: .regularExpression)?.upperBound
+            else {
+                struct MissingRequiredTagsError: DescribedError {
+                    let errorDescription = "Missing required `<head>` and `<body>` elements in \"index.html\" file."
+                }
+                throw MissingRequiredTagsError()
+            }
             
-            let titleStart = content.utf8.firstRange(of:  "<title>".utf8)!.upperBound
-            let titleEnd   = content.utf8.firstRange(of: "</title>".utf8)!.lowerBound
+            for template in customTemplates { // Use the order as `ConvertFileWritingConsumer`
+                content.insert(contentsOf: "<template id=\"\(template.id)\">\(template.content)</template>", at: afterStartOfBody)
+            }
             
-            let beforeHeadEnd = content.utf8.firstRange(of: "</head>".utf8)!.lowerBound
+            if let titleStart = content.utf8.firstRange(of:  "<title>".utf8)?.upperBound,
+               let titleEnd   = content.utf8.firstRange(of: "</title>".utf8)?.lowerBound
+            {
+                titleReplacementRange = titleStart ..< titleEnd
+            } else {
+                content.insert(contentsOf: "<title></title>", at: beforeEndOfHead)
+                content.utf8.formIndex(&beforeEndOfHead,  offsetBy: "<title></title>".utf8.count)
+                content.utf8.formIndex(&afterStartOfBody, offsetBy: "<title></title>".utf8.count)
+                let titleInside = content.utf8.index(beforeEndOfHead, offsetBy: -"</title>".utf8.count)
+                titleReplacementRange = titleInside ..< titleInside
+            }
             
+            if let noScriptStart = content.utf8.firstRange(of:  "<noscript>".utf8)?.upperBound,
+               let noScriptEnd   = content.utf8.firstRange(of: "</noscript>".utf8)?.lowerBound
+            {
+                contentReplacementRange = noScriptStart ..< noScriptEnd
+            } else {
+                content.insert(contentsOf: "<noscript></noscript>", at: afterStartOfBody)
+                let noScriptInside = content.utf8.index(afterStartOfBody, offsetBy: "<noscript>".utf8.count)
+                contentReplacementRange = noScriptInside ..< noScriptInside
+            }
+                        
             original = content
-            // TODO: If the template doesn't already contain a <noscript> element, add one to the start of the <body> element
-            // TODO: If the template doesn't already contain a <title> element, add one to the end of the <head> element
-            contentReplacementRange     = noScriptStart ..< noScriptEnd
-            titleReplacementRange       = titleStart    ..< titleEnd
-            descriptionReplacementRange = beforeHeadEnd ..< beforeHeadEnd
+            descriptionReplacementRange = beforeEndOfHead ..< beforeEndOfHead
             
             assert(titleReplacementRange.upperBound       < descriptionReplacementRange.lowerBound, "The title replacement range should be before the description replacement range")
             assert(descriptionReplacementRange.upperBound < contentReplacementRange.lowerBound,     "The description replacement range should be before the content replacement range")
@@ -78,11 +103,27 @@ struct FileWritingHTMLContentConsumer: HTMLContentConsumer {
         targetFolder: URL,
         fileManager: some FileManagerProtocol,
         htmlTemplate: URL,
+        customHeader: URL?,
+        customFooter: URL?,
         prettyPrintOutput: Bool = shouldPrettyPrintOutputJSON
     ) throws {
-        self.targetFolder = targetFolder
-        self.fileManager = fileManager
-        self.htmlTemplate = try HTMLTemplate(data: fileManager.contents(of: htmlTemplate))
+        var customTemplates: [HTMLTemplate.CustomTemplate] = []
+        if let customHeader {
+            customTemplates.append(.init(
+                id: "custom-header",
+                content: String(decoding: try fileManager.contents(of: customHeader), as: UTF8.self)
+            ))
+        }
+        if let customFooter {
+            customTemplates.append(.init(
+                id: "custom-footer",
+                content: String(decoding: try fileManager.contents(of: customFooter), as: UTF8.self)
+            ))
+        }
+        self.htmlTemplate = try HTMLTemplate(
+            data: fileManager.contents(of: htmlTemplate),
+            customTemplates: customTemplates
+        )
         self.prettyPrintOutput = prettyPrintOutput
         self.fileWriter = JSONEncodingRenderNodeWriter(
             targetFolder: targetFolder,
diff --git a/Sources/DocCCommandLine/ArgumentParsing/ActionExtensions/ConvertAction+CommandInitialization.swift b/Sources/DocCCommandLine/ArgumentParsing/ActionExtensions/ConvertAction+CommandInitialization.swift
index 4d7272d3a..8ea1c161f 100644
--- a/Sources/DocCCommandLine/ArgumentParsing/ActionExtensions/ConvertAction+CommandInitialization.swift
+++ b/Sources/DocCCommandLine/ArgumentParsing/ActionExtensions/ConvertAction+CommandInitialization.swift
@@ -78,6 +78,7 @@ extension ConvertAction {
             experimentalEnableCustomTemplates: convert.experimentalEnableCustomTemplates,
             experimentalModifyCatalogWithGeneratedCuration: convert.experimentalModifyCatalogWithGeneratedCuration,
             transformForStaticHosting: convert.transformForStaticHosting,
+            includeContentInEachHTMLFile: convert.experimentalTransformForStaticHostingWithContent,
             allowArbitraryCatalogDirectories: convert.allowArbitraryCatalogDirectories,
             hostingBasePath: convert.hostingBasePath,
             sourceRepository: SourceRepository(from: convert.sourceRepositoryArguments),
diff --git a/Sources/DocCCommandLine/ArgumentParsing/Subcommands/Convert.swift b/Sources/DocCCommandLine/ArgumentParsing/Subcommands/Convert.swift
index a33715a62..6398b9922 100644
--- a/Sources/DocCCommandLine/ArgumentParsing/Subcommands/Convert.swift
+++ b/Sources/DocCCommandLine/ArgumentParsing/Subcommands/Convert.swift
@@ -184,6 +184,20 @@ extension Docc {
                 help: "Produce a DocC archive that supports static hosting environments."
             )
             var transformForStaticHosting = true
+            
+            @Flag(help: "Include documentation content in each HTML file for static hosting environments.")
+            var experimentalTransformForStaticHostingWithContent = false
+            
+            mutating func validate() throws {
+                if experimentalTransformForStaticHostingWithContent, !transformForStaticHosting {
+                    warnAboutDiagnostic(.init(
+                        severity: .warning,
+                        identifier: "org.swift.docc.IgnoredNoTransformForStaticHosting",
+                        summary: "Passing '--experimental-transform-for-static-hosting-with-content' also implies '--transform-for-static-hosting'. Passing '--no-transform-for-static-hosting' has no effect."
+                    ))
+                    transformForStaticHosting = true
+                }
+            }
         }
         
         /// A Boolean value that is true if the DocC archive produced by this conversion will support static hosting environments.
@@ -194,6 +208,12 @@ extension Docc {
             set { hostingOptions.transformForStaticHosting = newValue }
         }
         
+        /// A Boolean value that is true if the DocC archive produced by this conversion will support browsing without JavaScript enabled.
+        public var experimentalTransformForStaticHostingWithContent: Bool {
+            get { hostingOptions.experimentalTransformForStaticHostingWithContent }
+            set { hostingOptions.experimentalTransformForStaticHostingWithContent = newValue }
+        }
+        
         /// A user-provided relative path to be used in the archived output
         var hostingBasePath: String? {
             hostingOptions.hostingBasePath
diff --git a/Tests/DocCCommandLineTests/ArgumentParsing/ConvertSubcommandTests.swift b/Tests/DocCCommandLineTests/ArgumentParsing/ConvertSubcommandTests.swift
index 60c5630f7..3d0f511d7 100644
--- a/Tests/DocCCommandLineTests/ArgumentParsing/ConvertSubcommandTests.swift
+++ b/Tests/DocCCommandLineTests/ArgumentParsing/ConvertSubcommandTests.swift
@@ -596,6 +596,37 @@ class ConvertSubcommandTests: XCTestCase {
         let disabledFlagConvert = try Docc.Convert.parse(["--disable-mentioned-in"])
         XCTAssertEqual(disabledFlagConvert.enableMentionedIn, false)
     }
+    
+    func testStaticHostingWithContentFlag() throws {
+        // The feature is disabled when no flag is passed.
+        let noFlagConvert = try Docc.Convert.parse([])
+        XCTAssertEqual(noFlagConvert.experimentalTransformForStaticHostingWithContent, false)
+        
+        let enabledFlagConvert = try Docc.Convert.parse(["--experimental-transform-for-static-hosting-with-content"])
+        XCTAssertEqual(enabledFlagConvert.experimentalTransformForStaticHostingWithContent, true)
+        
+        // The '...-transform...-with-content' flag also implies the base '--transform-...' flag.
+        do {
+            let originalErrorLogHandle = Docc.Convert._errorLogHandle
+            let originalDiagnosticFormattingOptions = Docc.Convert._diagnosticFormattingOptions
+            defer {
+                Docc.Convert._errorLogHandle = originalErrorLogHandle
+                Docc.Convert._diagnosticFormattingOptions = originalDiagnosticFormattingOptions
+            }
+            
+            let logStorage = LogHandle.LogStorage()
+            Docc.Convert._errorLogHandle = .memory(logStorage)
+            Docc.Convert._diagnosticFormattingOptions = .formatConsoleOutputForTools
+            
+            let conflictingFlagsConvert = try Docc.Convert.parse(["--experimental-transform-for-static-hosting-with-content", "--no-transform-for-static-hosting"])
+            XCTAssertEqual(conflictingFlagsConvert.experimentalTransformForStaticHostingWithContent, true)
+            XCTAssertEqual(conflictingFlagsConvert.transformForStaticHosting, true)
+            
+            XCTAssertEqual(logStorage.text.trimmingCharacters(in: .whitespacesAndNewlines), """
+            warning: Passing '--experimental-transform-for-static-hosting-with-content' also implies '--transform-for-static-hosting'. Passing '--no-transform-for-static-hosting' has no effect.
+            """)
+        }
+    }
 
     // This test calls ``ConvertOptions.infoPlistFallbacks._unusedVersionForBackwardsCompatibility`` which is deprecated.
     // Deprecating the test silences the deprecation warning when running the tests. It doesn't skip the test.
diff --git a/Tests/DocCCommandLineTests/FileWritingHTMLContentConsumerTests.swift b/Tests/DocCCommandLineTests/FileWritingHTMLContentConsumerTests.swift
index 6d4297a5f..9bb052943 100644
--- a/Tests/DocCCommandLineTests/FileWritingHTMLContentConsumerTests.swift
+++ b/Tests/DocCCommandLineTests/FileWritingHTMLContentConsumerTests.swift
@@ -23,7 +23,7 @@ final class FileWritingHTMLContentConsumerTests: XCTestCase {
             TextFile(name: "SomeArticle.md", utf8Content: """
             # Some article
             
-            This is an _formatted_ article.
+            This is a _formatted_ article.
             
             @DeprecationSummary {
               Description of why this _article_ is deprecated.
@@ -173,6 +173,8 @@ final class FileWritingHTMLContentConsumerTests: XCTestCase {
             targetFolder: URL(fileURLWithPath: "/output-dir"),
             fileManager: fileSystem,
             htmlTemplate: URL(fileURLWithPath: "/template/index.html"),
+            customHeader: nil,
+            customFooter: nil,
             prettyPrintOutput: true
         )
         
@@ -228,7 +230,7 @@ final class FileWritingHTMLContentConsumerTests: XCTestCase {
                   <li>
                     <a href="somearticle/index.html">
                       <p>Some article</p>
-                      <p>This is an <i>formatted</i> article.</p>
+                      <p>This is a <i>formatted</i> article.</p>
                     </a>
                   </li>
                   <li>
@@ -366,7 +368,7 @@ final class FileWritingHTMLContentConsumerTests: XCTestCase {
                 <li>
                   <a href="../../somearticle/index.html">
                     <p>Some article</p>
-                    <p>This is an <i>formatted</i> article.</p>
+                    <p>This is a <i>formatted</i> article.</p>
                   </a>
                 </li>
               </ul>
@@ -384,7 +386,7 @@ final class FileWritingHTMLContentConsumerTests: XCTestCase {
             <link rel="icon" href="/favicon.ico" />
             <title>Some article</title>
             <script>var baseUrl = "/"</script>
-            <meta content="This is an formatted article." name="description"/>
+            <meta content="This is a formatted article." name="description"/>
           </head>
           <body>
             <noscript>
@@ -398,7 +400,7 @@ final class FileWritingHTMLContentConsumerTests: XCTestCase {
                   </ul>
                   <p>Article</p>
                   <h1>Some article</h1>
-                  <p>This is an <i>formatted</i> article.</p>
+                  <p>This is a <i>formatted</i> article.</p>
                   <blockquote class="aside deprecated">
                     <p class="label">Deprecated</p>
                     <p>Description of why this <i>article</i> is deprecated.</p>
@@ -470,6 +472,110 @@ final class FileWritingHTMLContentConsumerTests: XCTestCase {
         """)
     }
 
+    func testAddsTagsToTemplateIfMissing() async throws {
+        let catalog = Folder(name: "Something.docc", content: [
+            TextFile(name: "RootArticle.md", utf8Content: """
+            # A single article
+            
+            This is a _formatted_ article that becomes the root page (because there is only one page).
+            """)
+        ])
+        
+        for withTitleTag in [true, false] {
+            for withNoScriptTag in [true, false] {
+                let maybeTitleTag = withTitleTag ? "<title>Documentation</title>" : ""
+                let maybeNoScriptTag = withNoScriptTag ? """
+                  <noscript>
+                    <p>Some existing information inside the no script tag</p>
+                  </noscript>
+                """ : ""
+                
+                let htmlTemplate = TextFile(name: "index.html", utf8Content: """
+                <html>
+                  <head>
+                    <meta charset="utf-8" />
+                    <link rel="icon" href="/favicon.ico" />
+                    \(maybeTitleTag)
+                  </head>
+                  <body>
+                  \(maybeNoScriptTag)
+                    <div id="app"></div>
+                  </body>
+                </html>
+                """)
+                
+                let fileSystem = try TestFileSystem(folders: [
+                    Folder(name: "path", content: [
+                        Folder(name: "to", content: [
+                            catalog
+                        ])
+                    ]),
+                    Folder(name: "template", content: [
+                        htmlTemplate
+                    ]),
+                    Folder(name: "output-dir", content: [])
+                ])
+                
+                let (inputs, dataProvider) = try DocumentationContext.InputsProvider(fileManager: fileSystem)
+                    .inputsAndDataProvider(startingPoint: URL(fileURLWithPath: "/path/to/\(catalog.name)"), options: .init())
+                
+                let context = try await DocumentationContext(bundle: inputs, dataProvider: dataProvider, configuration: .init())
+                
+                let htmlConsumer = try FileWritingHTMLContentConsumer(
+                    targetFolder: URL(fileURLWithPath: "/output-dir"),
+                    fileManager: fileSystem,
+                    htmlTemplate: URL(fileURLWithPath: "/template/index.html"),
+                    customHeader: nil,
+                    customFooter: nil,
+                    prettyPrintOutput: true
+                )
+                
+                _ = try ConvertActionConverter.convert(
+                    context: context,
+                    outputConsumer: TestOutputConsumer(),
+                    htmlContentConsumer: htmlConsumer,
+                    sourceRepository: nil,
+                    emitDigest: false,
+                    documentationCoverageOptions: .noCoverage
+                )
+                
+                // Because the TestOutputConsumer below doesn't create any files, we only expect the HTML files in the output directory
+                XCTAssertEqual(fileSystem.dump(subHierarchyFrom: "/output-dir"), """
+                output-dir/
+                ╰─ documentation/
+                   ╰─ rootarticle/
+                      ╰─ index.html
+                """)
+                
+                try assert(readHTML: fileSystem.contents(of: URL(fileURLWithPath: "/output-dir/documentation/rootarticle/index.html")), matches: """
+                <html>
+                  <head>
+                    <meta charset="utf-8" />
+                    <link rel="icon" href="/favicon.ico" />
+                    <title>A single article</title>
+                    <meta content="This is a formatted article that becomes the root page (because there is only one page)." name="description"/>
+                  </head>
+                  <body>
+                    <noscript>
+                      <article>
+                        <section>
+                          <ul>
+                            <li>RootArticle</li>
+                          </ul>
+                          <p>
+                          Article</p>
+                          <h1>RootArticle</h1>
+                          <p>This is a <i> formatted</i> article that becomes the root page (because there is only one page).</p>
+                        </section>
+                      </article>
+                    </noscript>
+                    <div id="app"></div>
+                  </body>
+                </html>
+                """)
+            }
+        }
+    }
 }
 
 // MARK: Helpers
@@ -488,7 +594,7 @@ private class TestOutputConsumer: ConvertOutputConsumer, ExternalNodeConsumer {
     func consume(externalRenderNode: ExternalRenderNode) throws { }
 }
 
-private func assert(readHTML: Data, matches expectedHTML: String, file: StaticString = #filePath, line: UInt = #line) {
+func assert(readHTML: Data, matches expectedHTML: String, file: StaticString = #filePath, line: UInt = #line) {
     // XMLNode on macOS and Linux pretty print with different indentation.
     // To compare the XML structure without getting false positive failures because of indentation and other formatting differences,
     // we explicitly process each string into an easy-to-compare format.
diff --git a/Tests/DocCCommandLineTests/StaticHostingWithContentTests.swift b/Tests/DocCCommandLineTests/StaticHostingWithContentTests.swift
new file mode 100644
index 000000000..8248cbbad
--- /dev/null
+++ b/Tests/DocCCommandLineTests/StaticHostingWithContentTests.swift
@@ -0,0 +1,150 @@
+/*
+ This source file is part of the Swift.org open source project
+
+ Copyright (c) 2025 Apple Inc. and the Swift project authors
+ Licensed under Apache License v2.0 with Runtime Library Exception
+
+ See https://swift.org/LICENSE.txt for license information
+ See https://swift.org/CONTRIBUTORS.txt for Swift project authors
+*/
+
+import XCTest
+import Foundation
+@testable import SwiftDocC
+@testable import DocCCommandLine
+import DocCTestUtilities
+
+class StaticHostingWithContentTests: XCTestCase {
+
+    func testIncludesBasePathInPerPageIndexHTMLFile() async throws {
+        let catalog = Folder(name: "Something.docc", content: [
+            TextFile(name: "RootArticle.md", utf8Content: """
+            # A single article
+            
+            This is a _formatted_ article that becomes the root page (because there is only one page).
+            """),
+            
+            TextFile(name: "header.html", utf8Content: """
+            <p>Some header content</p>
+            """),
+            TextFile(name: "footer.html", utf8Content: """
+            <p>Some footer content</p>
+            """),
+        ])
+        let htmlTemplateContent = """
+        <html>
+          <head>
+            <meta charset="utf-8" />
+            <link rel="icon" href="{{BASE_PATH}}/favicon.ico" />
+            <title>Documentation</title>
+          </head>
+          <body>
+            <noscript>
+              <p>Some existing information inside the no script tag</p>
+            </noscript>
+            <div id="app"></div>
+          </body>
+        </html>
+        """
+        
+        let fileSystem = try TestFileSystem(folders: [
+            Folder(name: "path", content: [
+                Folder(name: "to", content: [
+                    catalog
+                ])
+            ]),
+            Folder(name: "template", content: [
+                TextFile(name: "index.html", utf8Content: htmlTemplateContent.replacingOccurrences(of: "{{BASE_PATH}}", with: "")),
+                TextFile(name: "index-template.html", utf8Content: htmlTemplateContent),
+            ]),
+            Folder(name: "output-dir", content: [])
+        ])
+        
+        let basePath = "some/test/base-path"
+        
+        for includeHTMLContent in [true, false] {
+            
+            var action = try ConvertAction(
+                documentationBundleURL: URL(fileURLWithPath: "/path/to/\(catalog.name)"),
+                outOfProcessResolver: nil,
+                analyze: false,
+                targetDirectory: URL(fileURLWithPath: "/output-dir"),
+                htmlTemplateDirectory: URL(fileURLWithPath: "/template"),
+                emitDigest: false,
+                currentPlatforms: nil,
+                buildIndex: false,
+                fileManager: fileSystem,
+                temporaryDirectory: URL(fileURLWithPath: "/tmp"),
+                experimentalEnableCustomTemplates: true,
+                transformForStaticHosting: true,
+                includeContentInEachHTMLFile: includeHTMLContent,
+                hostingBasePath: basePath
+            )
+            // The old `Indexer` type doesn't work with virtual file systems.
+            action._completelySkipBuildingIndex = true
+            
+            _ = try await action.perform(logHandle: .none)
+            
+            // Because the TestOutputConsumer below, doesn't create any files, we only expect the HTML files in the output directory
+            XCTAssertEqual(fileSystem.dump(subHierarchyFrom: "/output-dir"), """
+            output-dir/
+            ├─ data/
+            │  ╰─ documentation/
+            │     ╰─ rootarticle.json
+            ├─ documentation/
+            │  ╰─ rootarticle/
+            │     ╰─ index.html
+            ├─ downloads/
+            │  ╰─ Something/
+            ├─ images/
+            │  ╰─ Something/
+            ├─ index.html
+            ├─ metadata.json
+            ╰─ videos/
+               ╰─ Something/
+            """)
+            
+            let expectedTitleAndMetaContent = includeHTMLContent ? """
+            <title>A single article</title>
+            <meta content="This is a formatted article that becomes the root page (because there is only one page)." name="description"/>
+            """ : "<title>Documentation</title>"
+            
+            let expectedNoScriptContent = includeHTMLContent ? """
+            <article>
+              <section>
+                <ul>
+                  <li>RootArticle</li>
+                </ul>
+                <p>
+                Article</p>
+                <h1>RootArticle</h1>
+                <p>This is a <i> formatted</i> article that becomes the root page (because there is only one page).</p>
+              </section>
+            </article>
+            """ : "<p>Some existing information inside the no script tag</p>"
+            
+            // The footer comes before the header to match the behavior of ConvertFileWritingConsumer.
+            try assert(readHTML: fileSystem.contents(of: URL(fileURLWithPath: "/output-dir/documentation/rootarticle/index.html")), matches: """
+            <html>
+              <head>
+                <meta charset="utf-8" />
+                <link rel="icon" href="/some/test/base-path/favicon.ico" />
+                \(expectedTitleAndMetaContent)
+              </head>
+              <body>
+                <template id="custom-footer">
+                  <p>Some footer content</p>
+                </template>
+                <template id="custom-header">
+                  <p>Some header content</p>
+                </template>
+                <noscript>
+                  \(expectedNoScriptContent)
+                </noscript>
+                <div id="app"></div>
+              </body>
+            </html>
+            """)
+        }
+    }
+}
diff --git a/features.json b/features.json
index 014b9bf65..d7b454d6d 100644
--- a/features.json
+++ b/features.json
@@ -14,6 +14,9 @@
     },
     {
       "name": "synthesized-landing-page-name"
+    },
+    {
+      "name": "static-hosting-with-content"
     }
   ]
 }