From 17a6c55e8fe88783647dc4072610c2a264de0052 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?David=20R=C3=B6nnqvist?= <ronnqvist@apple.com>
Date: Mon, 15 Dec 2025 11:39:36 +0100
Subject: [PATCH 1/9] Add CLI flag to insert minimal HTML content in each
 "index.html" file

rdar://163326857
---
 .../Actions/Convert/ConvertAction.swift       | 16 ++++++++--
 .../ConvertAction+CommandInitialization.swift |  1 +
 .../ArgumentParsing/Subcommands/Convert.swift | 20 ++++++++++++
 .../ConvertSubcommandTests.swift              | 31 +++++++++++++++++++
 features.json                                 |  3 ++
 5 files changed, 69 insertions(+), 2 deletions(-)

diff --git a/Sources/SwiftDocCUtilities/Action/Actions/Convert/ConvertAction.swift b/Sources/SwiftDocCUtilities/Action/Actions/Convert/ConvertAction.swift
index 62d2baf744..6d56ab75c4 100644
--- a/Sources/SwiftDocCUtilities/Action/Actions/Convert/ConvertAction.swift
+++ b/Sources/SwiftDocCUtilities/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
         
@@ -299,9 +303,17 @@ 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)
+        } else {
+            htmlConsumer = nil
+        }
 
         if experimentalModifyCatalogWithGeneratedCuration, let catalogURL = rootURL {
             let writer = GeneratedCurationWriter(context: context, catalogURL: catalogURL, outputURL: catalogURL)
@@ -320,7 +332,7 @@ public struct ConvertAction: AsyncAction {
                 try ConvertActionConverter.convert(
                     context: context,
                     outputConsumer: outputConsumer,
-                    htmlContentConsumer: nil,
+                    htmlContentConsumer: htmlConsumer,
                     sourceRepository: sourceRepository,
                     emitDigest: emitDigest,
                     documentationCoverageOptions: documentationCoverageOptions
diff --git a/Sources/SwiftDocCUtilities/ArgumentParsing/ActionExtensions/ConvertAction+CommandInitialization.swift b/Sources/SwiftDocCUtilities/ArgumentParsing/ActionExtensions/ConvertAction+CommandInitialization.swift
index 4d7272d3a2..8ea1c161f1 100644
--- a/Sources/SwiftDocCUtilities/ArgumentParsing/ActionExtensions/ConvertAction+CommandInitialization.swift
+++ b/Sources/SwiftDocCUtilities/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/SwiftDocCUtilities/ArgumentParsing/Subcommands/Convert.swift b/Sources/SwiftDocCUtilities/ArgumentParsing/Subcommands/Convert.swift
index a33715a625..6398b99221 100644
--- a/Sources/SwiftDocCUtilities/ArgumentParsing/Subcommands/Convert.swift
+++ b/Sources/SwiftDocCUtilities/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/SwiftDocCUtilitiesTests/ArgumentParsing/ConvertSubcommandTests.swift b/Tests/SwiftDocCUtilitiesTests/ArgumentParsing/ConvertSubcommandTests.swift
index 41027fbba1..68f35ac060 100644
--- a/Tests/SwiftDocCUtilitiesTests/ArgumentParsing/ConvertSubcommandTests.swift
+++ b/Tests/SwiftDocCUtilitiesTests/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 enabled 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/features.json b/features.json
index 014b9bf65c..d7b454d6de 100644
--- a/features.json
+++ b/features.json
@@ -14,6 +14,9 @@
     },
     {
       "name": "synthesized-landing-page-name"
+    },
+    {
+      "name": "static-hosting-with-content"
     }
   ]
 }

From 8e996c41cd196bdc0d690b8f423e30531ba5e1ff Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?David=20R=C3=B6nnqvist?= <ronnqvist@apple.com>
Date: Mon, 15 Dec 2025 11:43:10 +0100
Subject: [PATCH 2/9] Support index.html files that are missing the expected
 HTML elements

---
 .../FileWritingHTMLContentConsumer.swift      |  45 +++++---
 .../FileWritingHTMLContentConsumerTests.swift | 102 ++++++++++++++++++
 2 files changed, 134 insertions(+), 13 deletions(-)

diff --git a/Sources/SwiftDocCUtilities/Action/Actions/Convert/FileWritingHTMLContentConsumer.swift b/Sources/SwiftDocCUtilities/Action/Actions/Convert/FileWritingHTMLContentConsumer.swift
index 2fcaf2eae7..80a7bf8e26 100644
--- a/Sources/SwiftDocCUtilities/Action/Actions/Convert/FileWritingHTMLContentConsumer.swift
+++ b/Sources/SwiftDocCUtilities/Action/Actions/Convert/FileWritingHTMLContentConsumer.swift
@@ -31,23 +31,42 @@ struct FileWritingHTMLContentConsumer: HTMLContentConsumer {
         var descriptionReplacementRange: Range<String.Index>
         
         init(data: Data) throws {
-            let content = String(decoding: data, as: UTF8.self)
+            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
-            
-            let titleStart = content.utf8.firstRange(of:  "<title>".utf8)!.upperBound
-            let titleEnd   = content.utf8.firstRange(of: "</title>".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 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")
diff --git a/Tests/SwiftDocCUtilitiesTests/FileWritingHTMLContentConsumerTests.swift b/Tests/SwiftDocCUtilitiesTests/FileWritingHTMLContentConsumerTests.swift
index ac32af05ec..832de2103b 100644
--- a/Tests/SwiftDocCUtilitiesTests/FileWritingHTMLContentConsumerTests.swift
+++ b/Tests/SwiftDocCUtilitiesTests/FileWritingHTMLContentConsumerTests.swift
@@ -474,6 +474,108 @@ 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 an _formatted_ article that becomes the root page (because there's 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"),
+                    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 an formatted article that becomes the root page (because there’s only one page)." name="description"/>
+                  </head>
+                  <body>
+                    <noscript>
+                      <article>
+                        <section>
+                          <ul>
+                            <li>RootArticle</li>
+                          </ul>
+                          <p>
+                          Article</p>
+                          <h1>RootArticle</h1>
+                          <p>This is an <i> formatted</i> article that becomes the root page (because there’s only one page).</p>
+                        </section>
+                      </article>
+                    </noscript>
+                    <div id="app"></div>
+                  </body>
+                </html>
+                """)
+            }
+        }
+    }
 }
 
 // MARK: Helpers

From 4bab357ac12d682645078f961997571a6aa38773 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?David=20R=C3=B6nnqvist?= <ronnqvist@apple.com>
Date: Mon, 15 Dec 2025 12:08:33 +0100
Subject: [PATCH 3/9] Test that index.html files with content includes the
 hosting base path

---
 .../Actions/Convert/ConvertAction.swift       |   6 +-
 .../FileWritingHTMLContentConsumerTests.swift |   2 +-
 .../StaticHostingWithContentTests.swift       | 124 ++++++++++++++++++
 3 files changed, 129 insertions(+), 3 deletions(-)
 create mode 100644 Tests/SwiftDocCUtilitiesTests/StaticHostingWithContentTests.swift

diff --git a/Sources/SwiftDocCUtilities/Action/Actions/Convert/ConvertAction.swift b/Sources/SwiftDocCUtilities/Action/Actions/Convert/ConvertAction.swift
index 6d56ab75c4..b59909ef16 100644
--- a/Sources/SwiftDocCUtilities/Action/Actions/Convert/ConvertAction.swift
+++ b/Sources/SwiftDocCUtilities/Action/Actions/Convert/ConvertAction.swift
@@ -193,6 +193,8 @@ 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)?
 
+    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 {
@@ -290,7 +292,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)
@@ -387,7 +389,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/Tests/SwiftDocCUtilitiesTests/FileWritingHTMLContentConsumerTests.swift b/Tests/SwiftDocCUtilitiesTests/FileWritingHTMLContentConsumerTests.swift
index 832de2103b..e8e58282bc 100644
--- a/Tests/SwiftDocCUtilitiesTests/FileWritingHTMLContentConsumerTests.swift
+++ b/Tests/SwiftDocCUtilitiesTests/FileWritingHTMLContentConsumerTests.swift
@@ -594,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/SwiftDocCUtilitiesTests/StaticHostingWithContentTests.swift b/Tests/SwiftDocCUtilitiesTests/StaticHostingWithContentTests.swift
new file mode 100644
index 0000000000..4103742893
--- /dev/null
+++ b/Tests/SwiftDocCUtilitiesTests/StaticHostingWithContentTests.swift
@@ -0,0 +1,124 @@
+/*
+ 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 SwiftDocCUtilities
+import SwiftDocCTestUtilities
+
+class StaticHostingWithContentTests: XCTestCase {
+
+    func testIncludesBasePathInPerPageIndexHTMLFile() async throws {
+        let catalog = Folder(name: "Something.docc", content: [
+            TextFile(name: "RootArticle.md", utf8Content: """
+            # A single article
+            
+            This is an _formatted_ article that becomes the root page (because there's only one page).
+            """)
+        ])
+        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"
+        
+        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"),
+            transformForStaticHosting: true,
+            includeContentInEachHTMLFile: true,
+            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/
+        """)
+        
+        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" />
+            <title>A single article</title>
+            <meta content="This is an formatted article that becomes the root page (because there’s only one page)." name="description"/>
+          </head>
+          <body>
+            <noscript>
+              <article>
+                <section>
+                  <ul>
+                    <li>RootArticle</li>
+                  </ul>
+                  <p>
+                  Article</p>
+                  <h1>RootArticle</h1>
+                  <p>This is an <i> formatted</i> article that becomes the root page (because there’s only one page).</p>
+                </section>
+              </article>
+            </noscript>
+            <div id="app"></div>
+          </body>
+        </html>
+        """)
+    }
+}

From 4910bf9d51be58c3851012e6e33ea7e725ad69da Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?David=20R=C3=B6nnqvist?= <ronnqvist@apple.com>
Date: Mon, 15 Dec 2025 14:45:18 +0100
Subject: [PATCH 4/9] Support custom header/footer templates alongside the
 per-page content

---
 .../Actions/Convert/ConvertAction.swift       |   8 +-
 .../Convert/ConvertFileWritingConsumer.swift  |   2 +-
 .../FileWritingHTMLContentConsumer.swift      |  30 +++-
 .../FileWritingHTMLContentConsumerTests.swift |   4 +
 .../StaticHostingWithContentTests.swift       | 153 ++++++++++--------
 5 files changed, 129 insertions(+), 68 deletions(-)

diff --git a/Sources/SwiftDocCUtilities/Action/Actions/Convert/ConvertAction.swift b/Sources/SwiftDocCUtilities/Action/Actions/Convert/ConvertAction.swift
index b59909ef16..b46d870538 100644
--- a/Sources/SwiftDocCUtilities/Action/Actions/Convert/ConvertAction.swift
+++ b/Sources/SwiftDocCUtilities/Action/Actions/Convert/ConvertAction.swift
@@ -312,7 +312,13 @@ public struct ConvertAction: AsyncAction {
         
         let htmlConsumer: FileWritingHTMLContentConsumer?
         if includeContentInEachHTMLFile, let indexHTML {
-            htmlConsumer = try FileWritingHTMLContentConsumer(targetFolder: temporaryFolder, fileManager: fileManager, htmlTemplate: indexHTML)
+            htmlConsumer = try FileWritingHTMLContentConsumer(
+                targetFolder: temporaryFolder,
+                fileManager: fileManager,
+                htmlTemplate: indexHTML,
+                customHeader: experimentalEnableCustomTemplates ? inputs.customHeader : nil,
+                customFooter: experimentalEnableCustomTemplates ? inputs.customFooter : nil
+            )
         } else {
             htmlConsumer = nil
         }
diff --git a/Sources/SwiftDocCUtilities/Action/Actions/Convert/ConvertFileWritingConsumer.swift b/Sources/SwiftDocCUtilities/Action/Actions/Convert/ConvertFileWritingConsumer.swift
index 56e4925851..9b570988d6 100644
--- a/Sources/SwiftDocCUtilities/Action/Actions/Convert/ConvertFileWritingConsumer.swift
+++ b/Sources/SwiftDocCUtilities/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/SwiftDocCUtilities/Action/Actions/Convert/FileWritingHTMLContentConsumer.swift b/Sources/SwiftDocCUtilities/Action/Actions/Convert/FileWritingHTMLContentConsumer.swift
index 80a7bf8e26..ff46f021dd 100644
--- a/Sources/SwiftDocCUtilities/Action/Actions/Convert/FileWritingHTMLContentConsumer.swift
+++ b/Sources/SwiftDocCUtilities/Action/Actions/Convert/FileWritingHTMLContentConsumer.swift
@@ -30,7 +30,11 @@ struct FileWritingHTMLContentConsumer: HTMLContentConsumer {
         var titleReplacementRange:       Range<String.Index>
         var descriptionReplacementRange: Range<String.Index>
         
-        init(data: Data) throws {
+        struct CustomTemplate {
+            var id, content: String
+        }
+        
+        init(data: Data, customTemplates: [CustomTemplate]) throws {
             var content = String(decoding: data, as: UTF8.self)
             
             // Ensure that the index.html file has at least a `<head>` and a `<body>`.
@@ -43,6 +47,10 @@ struct FileWritingHTMLContentConsumer: HTMLContentConsumer {
                 throw MissingRequiredTagsError()
             }
             
+            for template in customTemplates { // Use the order as `ConvertFileWritingConsumer`
+                content.insert(contentsOf: "<template id=\"\(template.id)\">\(template.content)</template>", at: afterStartOfBody)
+            }
+            
             if let titleStart = content.utf8.firstRange(of:  "<title>".utf8)?.upperBound,
                let titleEnd   = content.utf8.firstRange(of: "</title>".utf8)?.lowerBound
             {
@@ -97,11 +105,29 @@ 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/Tests/SwiftDocCUtilitiesTests/FileWritingHTMLContentConsumerTests.swift b/Tests/SwiftDocCUtilitiesTests/FileWritingHTMLContentConsumerTests.swift
index e8e58282bc..1e534a5f00 100644
--- a/Tests/SwiftDocCUtilitiesTests/FileWritingHTMLContentConsumerTests.swift
+++ b/Tests/SwiftDocCUtilitiesTests/FileWritingHTMLContentConsumerTests.swift
@@ -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
         )
         
@@ -527,6 +529,8 @@ final class FileWritingHTMLContentConsumerTests: XCTestCase {
                     targetFolder: URL(fileURLWithPath: "/output-dir"),
                     fileManager: fileSystem,
                     htmlTemplate: URL(fileURLWithPath: "/template/index.html"),
+                    customHeader: nil,
+                    customFooter: nil,
                     prettyPrintOutput: true
                 )
                 
diff --git a/Tests/SwiftDocCUtilitiesTests/StaticHostingWithContentTests.swift b/Tests/SwiftDocCUtilitiesTests/StaticHostingWithContentTests.swift
index 4103742893..3fc478b2cc 100644
--- a/Tests/SwiftDocCUtilitiesTests/StaticHostingWithContentTests.swift
+++ b/Tests/SwiftDocCUtilitiesTests/StaticHostingWithContentTests.swift
@@ -22,7 +22,14 @@ class StaticHostingWithContentTests: XCTestCase {
             # A single article
             
             This is an _formatted_ article that becomes the root page (because there's 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>
@@ -55,70 +62,88 @@ class StaticHostingWithContentTests: XCTestCase {
         
         let basePath = "some/test/base-path"
         
-        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"),
-            transformForStaticHosting: true,
-            includeContentInEachHTMLFile: true,
-            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/
-        """)
-        
-        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" />
+        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 an formatted article that becomes the root page (because there’s only one page)." name="description"/>
-          </head>
-          <body>
-            <noscript>
-              <article>
-                <section>
-                  <ul>
-                    <li>RootArticle</li>
-                  </ul>
-                  <p>
-                  Article</p>
-                  <h1>RootArticle</h1>
-                  <p>This is an <i> formatted</i> article that becomes the root page (because there’s only one page).</p>
-                </section>
-              </article>
-            </noscript>
-            <div id="app"></div>
-          </body>
-        </html>
-        """)
+            """ : "<title>Documentation</title>"
+            
+            let expectedNoScriptContent = includeHTMLContent ? """
+            <article>
+              <section>
+                <ul>
+                  <li>RootArticle</li>
+                </ul>
+                <p>
+                Article</p>
+                <h1>RootArticle</h1>
+                <p>This is an <i> formatted</i> article that becomes the root page (because there’s only one page).</p>
+              </section>
+            </article>
+            """ : "<p>Some existing information inside the no script tag</p>"
+            
+            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>
+            """)
+        }
     }
 }

From 9aa583e4a1f1c591c1e0599b8ec0bfc32de60c0b Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?David=20R=C3=B6nnqvist?= <ronnqvist@apple.com>
Date: Mon, 15 Dec 2025 16:26:08 +0100
Subject: [PATCH 5/9] Remove properties that are never read

---
 .../Actions/Convert/FileWritingHTMLContentConsumer.swift      | 4 ----
 1 file changed, 4 deletions(-)

diff --git a/Sources/SwiftDocCUtilities/Action/Actions/Convert/FileWritingHTMLContentConsumer.swift b/Sources/SwiftDocCUtilities/Action/Actions/Convert/FileWritingHTMLContentConsumer.swift
index ff46f021dd..83db0611ac 100644
--- a/Sources/SwiftDocCUtilities/Action/Actions/Convert/FileWritingHTMLContentConsumer.swift
+++ b/Sources/SwiftDocCUtilities/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 {
@@ -109,8 +107,6 @@ struct FileWritingHTMLContentConsumer: HTMLContentConsumer {
         customFooter: URL?,
         prettyPrintOutput: Bool = shouldPrettyPrintOutputJSON
     ) throws {
-        self.targetFolder = targetFolder
-        self.fileManager = fileManager
         var customTemplates: [HTMLTemplate.CustomTemplate] = []
         if let customHeader {
             customTemplates.append(.init(

From e87ea02f1d015516832af27292aaa43cf8a3a66d Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?David=20R=C3=B6nnqvist?= <ronnqvist@apple.com>
Date: Mon, 15 Dec 2025 16:38:39 +0100
Subject: [PATCH 6/9] Avoid HTML encoding difference between platforms in new
 test

---
 .../FileWritingHTMLContentConsumerTests.swift               | 6 +++---
 .../StaticHostingWithContentTests.swift                     | 6 +++---
 2 files changed, 6 insertions(+), 6 deletions(-)

diff --git a/Tests/SwiftDocCUtilitiesTests/FileWritingHTMLContentConsumerTests.swift b/Tests/SwiftDocCUtilitiesTests/FileWritingHTMLContentConsumerTests.swift
index 1e534a5f00..90aa99d790 100644
--- a/Tests/SwiftDocCUtilitiesTests/FileWritingHTMLContentConsumerTests.swift
+++ b/Tests/SwiftDocCUtilitiesTests/FileWritingHTMLContentConsumerTests.swift
@@ -481,7 +481,7 @@ final class FileWritingHTMLContentConsumerTests: XCTestCase {
             TextFile(name: "RootArticle.md", utf8Content: """
             # A single article
             
-            This is an _formatted_ article that becomes the root page (because there's only one page).
+            This is an _formatted_ article that becomes the root page (because there is only one page).
             """)
         ])
         
@@ -557,7 +557,7 @@ final class FileWritingHTMLContentConsumerTests: XCTestCase {
                     <meta charset="utf-8" />
                     <link rel="icon" href="/favicon.ico" />
                     <title>A single article</title>
-                    <meta content="This is an formatted article that becomes the root page (because there’s only one page)." name="description"/>
+                    <meta content="This is an formatted article that becomes the root page (because there is only one page)." name="description"/>
                   </head>
                   <body>
                     <noscript>
@@ -569,7 +569,7 @@ final class FileWritingHTMLContentConsumerTests: XCTestCase {
                           <p>
                           Article</p>
                           <h1>RootArticle</h1>
-                          <p>This is an <i> formatted</i> article that becomes the root page (because there’s only one page).</p>
+                          <p>This is an <i> formatted</i> article that becomes the root page (because there is only one page).</p>
                         </section>
                       </article>
                     </noscript>
diff --git a/Tests/SwiftDocCUtilitiesTests/StaticHostingWithContentTests.swift b/Tests/SwiftDocCUtilitiesTests/StaticHostingWithContentTests.swift
index 3fc478b2cc..0e58b07afd 100644
--- a/Tests/SwiftDocCUtilitiesTests/StaticHostingWithContentTests.swift
+++ b/Tests/SwiftDocCUtilitiesTests/StaticHostingWithContentTests.swift
@@ -21,7 +21,7 @@ class StaticHostingWithContentTests: XCTestCase {
             TextFile(name: "RootArticle.md", utf8Content: """
             # A single article
             
-            This is an _formatted_ article that becomes the root page (because there's only one page).
+            This is an _formatted_ article that becomes the root page (because there is only one page).
             """),
             
             TextFile(name: "header.html", utf8Content: """
@@ -106,7 +106,7 @@ class StaticHostingWithContentTests: XCTestCase {
             
             let expectedTitleAndMetaContent = includeHTMLContent ? """
             <title>A single article</title>
-            <meta content="This is an formatted article that becomes the root page (because there’s only one page)." name="description"/>
+            <meta content="This is an formatted article that becomes the root page (because there is only one page)." name="description"/>
             """ : "<title>Documentation</title>"
             
             let expectedNoScriptContent = includeHTMLContent ? """
@@ -118,7 +118,7 @@ class StaticHostingWithContentTests: XCTestCase {
                 <p>
                 Article</p>
                 <h1>RootArticle</h1>
-                <p>This is an <i> formatted</i> article that becomes the root page (because there’s only one page).</p>
+                <p>This is an <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>"

From e622fc69d106cff892f66a3e24a067e7574b421d Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?David=20R=C3=B6nnqvist?= <ronnqvist@apple.com>
Date: Thu, 18 Dec 2025 13:58:01 +0100
Subject: [PATCH 7/9] Add code comments about confusing test behaviors

---
 .../DocCCommandLine/Action/Actions/Convert/ConvertAction.swift | 3 +++
 Tests/DocCCommandLineTests/StaticHostingWithContentTests.swift | 1 +
 2 files changed, 4 insertions(+)

diff --git a/Sources/DocCCommandLine/Action/Actions/Convert/ConvertAction.swift b/Sources/DocCCommandLine/Action/Actions/Convert/ConvertAction.swift
index b46d870538..b9fb3a088d 100644
--- a/Sources/DocCCommandLine/Action/Actions/Convert/ConvertAction.swift
+++ b/Sources/DocCCommandLine/Action/Actions/Convert/ConvertAction.swift
@@ -193,6 +193,9 @@ 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,
diff --git a/Tests/DocCCommandLineTests/StaticHostingWithContentTests.swift b/Tests/DocCCommandLineTests/StaticHostingWithContentTests.swift
index 409ea155f1..21495fc68b 100644
--- a/Tests/DocCCommandLineTests/StaticHostingWithContentTests.swift
+++ b/Tests/DocCCommandLineTests/StaticHostingWithContentTests.swift
@@ -123,6 +123,7 @@ class StaticHostingWithContentTests: XCTestCase {
             </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>

From d1c4f4bac89d185acad72f5c5d1f00459792353b Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?David=20R=C3=B6nnqvist?= <ronnqvist@apple.com>
Date: Thu, 18 Dec 2025 13:58:46 +0100
Subject: [PATCH 8/9] Apply suggestions from code review

Co-authored-by: Andrea Fernandez Buitrago <15234535+anferbui@users.noreply.github.com>
---
 .../ArgumentParsing/ConvertSubcommandTests.swift              | 2 +-
 .../FileWritingHTMLContentConsumerTests.swift                 | 4 ++--
 2 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/Tests/DocCCommandLineTests/ArgumentParsing/ConvertSubcommandTests.swift b/Tests/DocCCommandLineTests/ArgumentParsing/ConvertSubcommandTests.swift
index 6720dd3084..3d0f511d7e 100644
--- a/Tests/DocCCommandLineTests/ArgumentParsing/ConvertSubcommandTests.swift
+++ b/Tests/DocCCommandLineTests/ArgumentParsing/ConvertSubcommandTests.swift
@@ -598,7 +598,7 @@ class ConvertSubcommandTests: XCTestCase {
     }
     
     func testStaticHostingWithContentFlag() throws {
-        // The feature is enabled when no flag is passed.
+        // The feature is disabled when no flag is passed.
         let noFlagConvert = try Docc.Convert.parse([])
         XCTAssertEqual(noFlagConvert.experimentalTransformForStaticHostingWithContent, false)
         
diff --git a/Tests/DocCCommandLineTests/FileWritingHTMLContentConsumerTests.swift b/Tests/DocCCommandLineTests/FileWritingHTMLContentConsumerTests.swift
index fb01b172ae..a3b43a1bb8 100644
--- a/Tests/DocCCommandLineTests/FileWritingHTMLContentConsumerTests.swift
+++ b/Tests/DocCCommandLineTests/FileWritingHTMLContentConsumerTests.swift
@@ -481,7 +481,7 @@ final class FileWritingHTMLContentConsumerTests: XCTestCase {
             TextFile(name: "RootArticle.md", utf8Content: """
             # A single article
             
-            This is an _formatted_ article that becomes the root page (because there is only one page).
+            This is a _formatted_ article that becomes the root page (because there is only one page).
             """)
         ])
         
@@ -543,7 +543,7 @@ final class FileWritingHTMLContentConsumerTests: XCTestCase {
                     documentationCoverageOptions: .noCoverage
                 )
                 
-                // Because the TestOutputConsumer below, doesn't create any files, we only expect the HTML files in the output directory
+                // 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/

From 296db91eb973b26b619ba99d8bdf45f744af0470 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?David=20R=C3=B6nnqvist?= <ronnqvist@apple.com>
Date: Thu, 18 Dec 2025 14:45:13 +0100
Subject: [PATCH 9/9] Fix typo in test data

---
 .../FileWritingHTMLContentConsumerTests.swift          | 10 +++++-----
 .../StaticHostingWithContentTests.swift                |  6 +++---
 2 files changed, 8 insertions(+), 8 deletions(-)

diff --git a/Tests/DocCCommandLineTests/FileWritingHTMLContentConsumerTests.swift b/Tests/DocCCommandLineTests/FileWritingHTMLContentConsumerTests.swift
index d8782c7c80..9bb0529438 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.
@@ -230,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>
@@ -368,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>
@@ -386,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>
@@ -400,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>
diff --git a/Tests/DocCCommandLineTests/StaticHostingWithContentTests.swift b/Tests/DocCCommandLineTests/StaticHostingWithContentTests.swift
index 21495fc68b..8248cbbad4 100644
--- a/Tests/DocCCommandLineTests/StaticHostingWithContentTests.swift
+++ b/Tests/DocCCommandLineTests/StaticHostingWithContentTests.swift
@@ -21,7 +21,7 @@ class StaticHostingWithContentTests: XCTestCase {
             TextFile(name: "RootArticle.md", utf8Content: """
             # A single article
             
-            This is an _formatted_ article that becomes the root page (because there is only one page).
+            This is a _formatted_ article that becomes the root page (because there is only one page).
             """),
             
             TextFile(name: "header.html", utf8Content: """
@@ -106,7 +106,7 @@ class StaticHostingWithContentTests: XCTestCase {
             
             let expectedTitleAndMetaContent = includeHTMLContent ? """
             <title>A single article</title>
-            <meta content="This is an formatted article that becomes the root page (because there is only one page)." name="description"/>
+            <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 ? """
@@ -118,7 +118,7 @@ class StaticHostingWithContentTests: XCTestCase {
                 <p>
                 Article</p>
                 <h1>RootArticle</h1>
-                <p>This is an <i> formatted</i> article that becomes the root page (because there is only one page).</p>
+                <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>"