Added support for using relative paths in websites, when needed.

Author: twostraws

Sources/Ignite/Elements/Image.swift

@@ -199,7 +199,7 @@ private extension Image {
     }
 
     /// Creates a `srcset` string from image variants with their corresponding pixel density descriptors,
-    /// e.g., `"/images/hero@2x.jpg 2x"`
+    /// e.g., `"/images/hero@2x.jpg 2x"` or `"images/hero@2x.jpg 2x"` when `useRelativePaths` is enabled.
     /// - Parameter variants: An array of image variant URLs
     /// - Returns: An HTML attribute containing the srcset value, or nil if no valid variants exist
     func generateSourceSet(_ variants: [URL]) -> Attribute? {
@@ -210,7 +210,8 @@ private extension Image {
             let densityDescriptor = getDensityDescriptor(filename).map { " \($0)" } ?? ""
             let relativePath = variant.path.replacingOccurrences(of: assetsDirectory.path, with: "")
             let webPath = relativePath.split(separator: "/").joined(separator: "/")
-            return "/\(webPath)\(densityDescriptor)"
+            let resolvedPath = publishingContext.assetPath("/\(webPath)")
+            return "\(resolvedPath)\(densityDescriptor)"
         }.joined(separator: ", ")
 
         return sources.isEmpty ? nil : .init(name: "srcset", value: sources)

Sources/Ignite/Elements/MetaLink.swift

@@ -97,14 +97,14 @@ public struct MetaLink: HeadElement, Sendable {
     /// Renders this element using publishing context passed in.
     /// - Returns: The HTML for this element.
     ///
-    /// If the link `href` starts with a `\` it is an asset and requires any `subsite` prepended;
-    /// otherwise the `href` is a URL and  doesn't get `subsite` prepended
+    /// If the link `href` starts with a `/` it is a local asset and requires any subsite
+    /// path prepended; otherwise the `href` is treated as-is (e.g., external URLs).
+    /// The path respects the site's `useRelativePaths` setting.
     public func markup() -> Markup {
         var attributes = attributes
-        // char[0] of the link 'href' is '/' for an asset; not for a site URL
-        let basePath = href.starts(with: "/") ? publishingContext.site.url.path : ""
+        let resolvedPath = publishingContext.assetPath(href)
         attributes.append(customAttributes:
-            .init(name: "href", value: "\(basePath)\(href)"),
+            .init(name: "href", value: resolvedPath),
             .init(name: "rel", value: rel))
 
         return Markup("<link\(attributes) />")

Sources/Ignite/Framework/Site.swift

@@ -142,6 +142,13 @@ public protocol Site: Sendable {
     /// The path to the favicon
     var favicon: URL? { get }
 
+    /// When `true`, generates asset paths without leading slashes
+    /// (e.g., `css/bootstrap.min.css` instead of `/css/bootstrap.min.css`).
+    ///
+    /// Use this for single-page sites that need to work when opened directly
+    /// from the filesystem without a web server. Defaults to `false`.
+    var useRelativePaths: Bool { get }
+
     /// An array of all the static pages you want to include in your site.
     @StaticPageBuilder var staticPages: [any StaticPage] { get }
 
@@ -221,9 +228,12 @@ public extension Site {
     /// An empty error page by default, which triggers no error pages being generated.
     var errorPage: EmptyErrorPage { EmptyErrorPage() }
 
-    /// The default favicon being nil
+    /// The default favicon being nil.
     var favicon: URL? { nil }
 
+    /// Default to absolute paths for all local URLs.
+    var useRelativePaths: Bool { false }
+
     /// The syntax highlighting themes from every site theme.
     internal var allHighlighterThemes: OrderedSet<HighlighterTheme> {
         var themes = OrderedSet<HighlighterTheme>()

Sources/Ignite/Publishing/PublishingContext.swift

@@ -169,14 +169,37 @@ final class PublishingContext {
     /// Converts a URL to a site-relative path string.
     /// - Parameter url: The URL to convert.
     /// - Returns: A string path, either preserving remote URLs or
-    /// making local URLs relative to the site root.
+    /// making local URLs relative to the site root. When `site.useRelativePaths`
+    /// is true, local paths will have their leading slash removed.
     func path(for url: URL) -> String {
         let path = url.relativeString
-        return if url.isFileURL {
+        var result = if url.isFileURL {
             site.url.appending(path: path).decodedPath
         } else {
             path
         }
+
+        if site.useRelativePaths, result.hasPrefix("/") {
+            result = String(result.dropFirst())
+        }
+
+        return result
+    }
+
+    /// Converts a path string to a site-relative path, prepending the site's
+    /// subpath if needed and respecting the `useRelativePaths` setting.
+    /// - Parameter path: A path string, typically starting with "/" for local assets.
+    /// - Returns: The resolved path. For subsites, includes the subsite path prefix.
+    /// When `useRelativePaths` is true, the leading slash is removed.
+    func assetPath(_ path: String) -> String {
+        let basePath = path.hasPrefix("/") ? site.url.path : ""
+        var fullPath = "\(basePath)\(path)"
+
+        if site.useRelativePaths, fullPath.hasPrefix("/") {
+            fullPath = String(fullPath.dropFirst())
+        }
+
+        return fullPath
     }
 
     /// Adds a warning during a site build.

Tests/IgniteTesting/RelativePaths/IgniteRelativePathsTestSuite.swift

@@ -0,0 +1,46 @@
+//
+// IgniteRelativePathsTestSuite.swift
+// Ignite
+// https://www.github.com/twostraws/Ignite
+// See LICENSE for license information.
+//
+
+import Foundation
+@testable import Ignite
+
+/// A base class for Ignite tests that use `TestRelativePathsSite` with relative paths enabled.
+@MainActor
+class IgniteRelativePathsTestSuite {
+    let site: any Site = TestRelativePathsSite()
+
+    var publishingContext: PublishingContext {
+        PublishingContext.shared
+    }
+
+    /// Creates a new test instance and initializes the publishing context for `TestRelativePathsSite`.
+    init() throws {
+        try PublishingContext.initialize(for: TestRelativePathsSite(), from: #filePath)
+    }
+}
+
+/// A base class for Ignite tests using `TestRelativePathsSubsite` (relative paths with subsite).
+@MainActor
+class IgniteRelativePathsSubsiteTestSuite {
+    let site: any Site = TestRelativePathsSubsite()
+
+    var publishingContext: PublishingContext {
+        PublishingContext.shared
+    }
+
+    /// Creates a new test instance and initializes the publishing context for `TestRelativePathsSubsite`.
+    init() throws {
+        try PublishingContext.initialize(for: TestRelativePathsSubsite(), from: #filePath)
+    }
+
+    /// Resets the publishing context when the test is deallocated.
+    deinit {
+        Task { @MainActor in
+            try? PublishingContext.initialize(for: TestSite(), from: #filePath)
+        }
+    }
+}