Fix external links in related content

.gitignore

@@ -2,3 +2,4 @@ config.json
 .build
 .swiftpm
 Package.resolved
+Issues.md

Sources/Generator/Content/Element+LocalizedMetadata.swift

@@ -140,6 +140,18 @@ extension Element {
          This property is mandatory at root level, and is propagated to child elements.
          */
         let navigationTextAsPreviousPage: String
+
+        /**
+         The text to display above a slideshow for most recent items.
+         Only used for elements that define `showMostRecentSection = true`
+         */
+        let mostRecentTitle: String?
+
+        /**
+         The text to display above a slideshow for featured items.
+         Only used for elements that define `showFeaturedSection = true`
+         */
+        let featuredTitle: String?
     }
 }
 
@@ -171,6 +183,8 @@ extension Element.LocalizedMetadata {
         self.relatedContentText = log.required(data.relatedContentText, name: "relatedContentText", source: source, &isValid)
         self.navigationTextAsNextPage = log.required(data.navigationTextAsNextPage, name: "navigationTextAsNextPage", source: source, &isValid)
         self.navigationTextAsPreviousPage = log.required(data.navigationTextAsPreviousPage, name: "navigationTextAsPreviousPage", source: source, &isValid)
+        self.mostRecentTitle = data.mostRecentTitle
+        self.featuredTitle = data.featuredTitle
 
         guard isValid else {
             return nil
@@ -202,6 +216,8 @@ extension Element.LocalizedMetadata {
         self.relatedContentText = data.relatedContentText ?? parent.relatedContentText
         self.navigationTextAsPreviousPage = data.navigationTextAsPreviousPage ?? parent.navigationTextAsPreviousPage
         self.navigationTextAsNextPage = data.navigationTextAsNextPage ?? parent.navigationTextAsNextPage
+        self.mostRecentTitle = data.mostRecentTitle ?? parent.mostRecentTitle
+        self.featuredTitle = data.featuredTitle ?? parent.featuredTitle
 
         guard isValid else {
             return nil

Sources/Generator/Content/Element.swift

@@ -65,7 +65,7 @@ struct Element {
     let sortIndex: Int?
 
     /**
-     All files which may occur in content but is stored externally.
+     All files which may occur in content but are stored externally.
 
      Missing files which would otherwise produce a warning are ignored when included here.
      - Note: This property defaults to an empty set.
@@ -132,6 +132,13 @@ struct Element {
      */
     let showMostRecentSection: Bool
 
+    /**
+     Indicate that the overview section should contain a `Featured Content` section before the other sections.
+     The elements are the page ids of the elements contained in the feature.
+     - Note: If not specified, this property defaults to `false`
+     */
+    let featuredPages: [String]
+
     /**
      The localized metadata for each language.
      */
@@ -190,6 +197,7 @@ struct Element {
         self.overviewItemCount = metadata.overviewItemCount ?? Element.overviewItemCountDefault
         self.headerType = log.cast(metadata.headerType, "headerType", source: source)
         self.showMostRecentSection = metadata.showMostRecentSection ?? false
+        self.featuredPages = metadata.featuredPages ?? []
         self.languages = log.required(metadata.languages, name: "languages", source: source, &isValid)
             .compactMap { language in
                     .init(atRoot: folder, data: language, log: log)
@@ -232,6 +240,10 @@ struct Element {
         guard let metadata = GenericMetadata(source: source, log: log) else {
             return nil
         }
+        let state: PageState = log.cast(metadata.state, "state", source: source)
+        guard state != .ignored else {
+            return nil
+        }
 
         var isValid = true
 
@@ -240,7 +252,7 @@ struct Element {
         self.topBarTitle = log.unused(metadata.topBarTitle, "topBarTitle", source: source)
         self.date = metadata.date.unwrapped { log.cast($0, "date", source: source) }
         self.endDate = metadata.endDate.unwrapped { log.cast($0, "endDate", source: source) }
-        self.state = log.cast(metadata.state, "state", source: source)
+        self.state = state
         self.sortIndex = metadata.sortIndex
         // TODO: Propagate external files from the parent if subpath matches?
         self.externalFiles = Element.rootPaths(for: metadata.externalFiles, path: path)
@@ -252,6 +264,7 @@ struct Element {
         self.overviewItemCount = metadata.overviewItemCount ?? parent.overviewItemCount
         self.headerType = log.cast(metadata.headerType, "headerType", source: source)
         self.showMostRecentSection = metadata.showMostRecentSection ?? false
+        self.featuredPages = metadata.featuredPages ?? []
         self.languages = parent.languages.compactMap { parentData in
             guard let data = metadata.languages?.first(where: { $0.language == parentData.language }) else {
                 log.warning("Language '\(parentData.language)' not found", source: source)
@@ -285,11 +298,28 @@ struct Element {
             return nil
         }
 
-        //files.add(page: path, id: id)
         self.readElements(in: folder, source: path, log: log)
+
+        if showMostRecentSection {
+            if elements.isEmpty {
+                log.error("Page has no children", source: source)
+            }
+            languages.filter { $0.mostRecentTitle == nil }.forEach {
+                log.error("'showMostRecentSection' = true, but 'mostRecentTitle' not set for language '\($0.language)'", source: source)
+            }
+        }
+
+        if !featuredPages.isEmpty {
+            if elements.isEmpty {
+                log.error("'featuredPages' contains elements, but page has no children", source: source)
+            }
+            languages.filter { $0.featuredTitle == nil }.forEach {
+                log.error("'featuredPages' contains elements, but 'featuredTitle' not set for language '\($0.language)'", source: source)
+            }
+        }
     }
 
-    func getExternalPageMap(language: String) -> [String : String] {
+    func getExternalPageMap(language: String, log: MetadataInfoLogger) -> [String : String] {
         var result = [String : String]()
         if let ext = getExternalLink(for: language) {
             result[id] = ext
@@ -297,7 +327,10 @@ struct Element {
             result[id] = path + Element.htmlPagePathAddition(for: language)
         }
         elements.forEach { element in
-            element.getExternalPageMap(language: language).forEach { key, value in
+            element.getExternalPageMap(language: language, log: log).forEach { key, value in
+                if result[key] != nil {
+                    log.error("Page id '\(key)' is used twice", source: value)
+                }
                 result[key] = value
             }
         }
@@ -307,6 +340,14 @@ struct Element {
     private func getExternalLink(for language: String) -> String? {
         languages.first { $0.language == language }?.externalUrl
     }
+
+    var needsFirstSection: Bool {
+        showMostRecentSection || !featuredPages.isEmpty
+    }
+
+    var hasVisibleChildren: Bool {
+        !elements.filter { $0.state == .standard }.isEmpty
+    }
 }
 
 // MARK: Paths
@@ -332,7 +373,7 @@ extension Element {
     }
 
     var hasNestingElements: Bool {
-        elements.contains { $0.containsElements }
+        elements.contains { $0.hasVisibleChildren }
     }
 
     func itemsForOverview(_ count: Int? = nil) -> [Element] {
@@ -344,12 +385,15 @@ extension Element {
     }
 
     func mostRecentElements(_ count: Int) -> [Element] {
+        guard self.thumbnailStyle == .large else {
+            return []
+        }
         guard self.containsElements else {
             return [self]
         }
         let all = shownItems
             .reduce(into: [Element]()) { $0 += $1.mostRecentElements(count) }
-            .filter { $0.date != nil }
+            .filter { $0.thumbnailStyle == .large && $0.state == .standard && $0.date != nil }
             .sorted { $0.date! > $1.date! }
         return Array(all.prefix(count))
     }
@@ -388,7 +432,7 @@ extension Element {
      - Returns: The relative url from a localized page of the element to the target file.
      */
     func relativePathToOtherSiteElement(file: String) -> String {
-        guard !file.hasPrefix("/") else {
+        guard !file.hasPrefix("/"), !file.hasPrefix("https://"), !file.hasPrefix("http://") else {
             return file
         }
         // Note: The element `path` is missing the last component
@@ -398,7 +442,7 @@ extension Element {
 
         // Find the common elements of the path, which can be discarded
         var index = 0
-        while pageParts[index] == ownParts[index] {
+        while index < pageParts.count && index < ownParts.count && pageParts[index] == ownParts[index] {
             index += 1
         }
         // The relative path needs to go down to the first common folder,

Sources/Generator/Content/GenericMetadata+Localized.swift

@@ -133,6 +133,18 @@ extension GenericMetadata {
          This property is mandatory at root level, and is propagated to child elements.
          */
         let navigationTextAsNextPage: String?
+
+        /**
+         The text to display above a slideshow for most recent items.
+         Only used for elements that define `showMostRecentSection = true`
+         */
+        let mostRecentTitle: String?
+
+        /**
+         The text to display above a slideshow for featured items.
+         Only used for elements that define `showFeaturedSection = true`
+         */
+        let featuredTitle: String?
     }
 }
 
@@ -158,6 +170,8 @@ extension GenericMetadata.LocalizedMetadata: Codable {
             .relatedContentText,
             .navigationTextAsPreviousPage,
             .navigationTextAsNextPage,
+            .mostRecentTitle,
+            .featuredTitle,
         ]
     }
 
@@ -190,7 +204,9 @@ extension GenericMetadata.LocalizedMetadata {
             externalUrl: nil,
             relatedContentText: nil,
             navigationTextAsPreviousPage: nil,
-            navigationTextAsNextPage: nil)
+            navigationTextAsNextPage: nil,
+            mostRecentTitle: nil,
+            featuredTitle: nil)
     }
 
     /**
@@ -214,7 +230,9 @@ extension GenericMetadata.LocalizedMetadata {
               externalUrl: nil,
               relatedContentText: "",
               navigationTextAsPreviousPage: "",
-              navigationTextAsNextPage: "")
+              navigationTextAsNextPage: "",
+              mostRecentTitle: nil,
+              featuredTitle: nil)
     }
 
     static var full: GenericMetadata.LocalizedMetadata {
@@ -235,6 +253,8 @@ extension GenericMetadata.LocalizedMetadata {
               externalUrl: "",
               relatedContentText: "",
               navigationTextAsPreviousPage: "",
-              navigationTextAsNextPage: "")
+              navigationTextAsNextPage: "",
+              mostRecentTitle: "",
+              featuredTitle: "")
     }
 }

Sources/Generator/Content/GenericMetadata.swift

@@ -131,6 +131,13 @@ struct GenericMetadata {
      */
     let showMostRecentSection: Bool?
 
+    /**
+     Indicate that the overview section should contain a `Featured Content` section before the other sections.
+     The elements are the page ids of the elements contained in the feature.
+     - Note: If not specified, this property defaults to `false`
+     */
+    let featuredPages: [String]?
+
     /**
      The localized metadata for each language.
      */
@@ -157,6 +164,7 @@ extension GenericMetadata: Codable {
             .overviewItemCount,
             .headerType,
             .showMostRecentSection,
+            .featuredPages,
             .languages,
         ]
     }
@@ -229,6 +237,7 @@ extension GenericMetadata {
             overviewItemCount: 6,
             headerType: "left",
             showMostRecentSection: false,
+            featuredPages: [],
             languages: [.full])
     }
 }

Sources/Generator/Content/PageState.swift

@@ -15,6 +15,11 @@ enum PageState: String {
      Generate the page, but don't include it in overviews of the parent.
      */
     case hidden
+
+    /**
+     Completely ignore the element.
+     */
+    case ignored
 }
 
 extension PageState {
@@ -23,7 +28,7 @@ extension PageState {
         switch self {
         case .standard, .draft:
             return true
-        case .hidden:
+        case .hidden, .ignored:
             return false
         }
     }
@@ -32,9 +37,7 @@ extension PageState {
         switch self {
         case .standard:
             return true
-        case .draft:
-            return false
-        case .hidden:
+        case .draft, .hidden, .ignored:
             return false
         }
     }
@@ -47,7 +50,7 @@ extension PageState: StringProperty {
     }
 
     static var castFailureReason: String {
-        "Page state must be 'standard', 'draft' or 'hidden'"
+        "Page state must be 'standard', 'draft', 'hidden', or 'ignored'"
     }
 }
 

Sources/Generator/Extensions/String+Extensions.swift

@@ -56,6 +56,11 @@ extension String {
         return parts.dropLast().joined(separator: separator) + content + separator + parts.last!
     }
 
+    /**
+     Remove everything behind the first separator.
+
+     Also removes the separator itself. If the separator is not contained in the string, then the full string is returned.
+     */
     func dropAfterFirst<T>(_ separator: T) -> String where T: StringProtocol {
         components(separatedBy: separator).first!
     }
@@ -67,10 +72,25 @@ extension String {
 
 extension Substring {
 
+    func dropBeforeFirst(_ separator: String) -> String {
+        guard contains(separator) else {
+            return String(self)
+        }
+        return components(separatedBy: separator).dropFirst().joined(separator: separator)
+    }
+
     func between(_ start: String, and end: String) -> String {
         components(separatedBy: start).last!
             .components(separatedBy: end).first!
     }
+
+    func between(first: String, andLast last: String) -> String {
+        dropBeforeFirst(first).dropAfterLast(last)
+    }
+
+    func last(after: String) -> String {
+        components(separatedBy: after).last!
+    }
 }
 
 extension String {

Sources/Generator/Extensions/URL+Extensions.swift

@@ -50,4 +50,23 @@ extension URL {
         let attributes = try? FileManager.default.attributesOfItem(atPath: path)
         return (attributes?[.size] as? NSNumber)?.intValue
     }
+
+    func resolvingFolderTraversal() -> URL? {
+        var components = [String]()
+        absoluteString.components(separatedBy: "/").forEach { part in
+            if part == ".." {
+                if !components.isEmpty {
+                    _ = components.popLast()
+                } else {
+                    components.append("..")
+                }
+                return
+            }
+            if part == "." {
+                return
+            }
+            components.append(part)
+        }
+        return URL(string: components.joined(separator: "/"))
+    }
 }

Sources/Generator/Files/Configuration.swift

@@ -16,22 +16,35 @@ struct Configuration: Codable {
     let pageImageWidth: Int
 
     /**
-     Automatically minify all `.css` and `.js` resources which are copied
+     The maximum width (in pixels) for images shown full screen.
+     */
+    let fullScreenImageWidth: Int
+
+    /**
+     Automatically minify all `.css` resources which are copied
      to the output folder.
-     - Note: This option requires the `uglifyjs` and `clean-css` tools,
+     - Note: This option requires the `clean-css` tool,
      which can be installed using the `install.sh` script in the root folder of the generator.
      */
-    let minifyCSSandJS: Bool
+    let minifyCSS: Bool
+
+    /**
+     Automatically minify all `.js` resources which are copied
+     to the output folder.
+     - Note: This option requires the `uglifyjs` tool,
+     which can be installed using the `install.sh` script in the root folder of the generator.
+     */
+    let minifyJavaScript: Bool
 
     /**
      The path to the directory where the root element metadata is located.
      */
-    let contentPath: String
+    var contentPath: String
 
     /**
      The path where the generated website should be written.
      */
-    let outputPath: String
+    var outputPath: String
 
     /**
      Create .md files for content pages, if they don't exist.
@@ -57,12 +70,22 @@ struct Configuration: Codable {
         .init(fileURLWithPath: outputPath)
     }
 
+    mutating func adjustPathsRelative(to folder: URL) {
+        if !contentPath.hasPrefix("/") {
+            contentPath = folder.appendingPathComponent(contentPath).resolvingFolderTraversal()!.path
+        }
+        if !outputPath.hasPrefix("/") {
+            outputPath = folder.appendingPathComponent(outputPath).resolvingFolderTraversal()!.path
+        }
+    }
+
     func printOverview() {
         print("         Source folder: \(contentDirectory.path)")
         print("         Output folder: \(outputDirectory.path)")
         print("            Page width: \(pageImageWidth)")
-        print("     Minify JavaScript: \(minifyCSSandJS)")
-        print("            Minify CSS: \(minifyCSSandJS)")
+        print("     Full-screen width: \(fullScreenImageWidth)")
+        print("     Minify JavaScript: \(minifyJavaScript)")
+        print("            Minify CSS: \(minifyCSS)")
         print(" Create markdown files: \(createMdFilesIfMissing)")
     }
 }

Sources/Generator/Files/VideoType.swift

@@ -3,6 +3,7 @@ import Foundation
 enum VideoType: String, CaseIterable {
     case mp4
     case m4v
+    case webm
 
     var htmlType: String {
         switch self {
@@ -10,6 +11,8 @@ enum VideoType: String, CaseIterable {
             return "video/mp4"
         case .m4v:
             return "video/mp4"
+        case .webm:
+            return "video/webm"
         }
     }
 }

Sources/Generator/Generators/HTMLElementsGenerator.swift

@@ -1,11 +1,9 @@
 import Foundation
 
+typealias SVGSelection = (x: Int, y: Int, width: Int, height: Int)
+
 struct HTMLElementsGenerator {
 
-    init() {
-
-    }
-
     func make(title: String, suffix: String) -> String {
         "\(title)<span class=\"suffix\">\(suffix)</span>"
     }
@@ -37,20 +35,18 @@ struct HTMLElementsGenerator {
         "\(text)<span class=\"icon-next\"></span>"
     }
 
-    func svgImage(file: String) -> String {
-        """
+    func image(file: String, width: Int, height: Int, altText: String) -> String {
+        let ratio = Float(width) / Float(height)
+        return """
         <span class="image">
-            <img src="\(file)"/>
+            <img src="\(file)" loading="lazy" style="aspect-ratio:\(ratio)" alt="\(altText)"/>
         </span>
         """
     }
 
-    func svgImage(file: String, x: Int, y: Int, width: Int, height: Int) -> String {
-        """
-        <span class="image">
-            <img src="\(file)#svgView(viewBox(\(x), \(y), \(width), \(height)))" style="aspect-ratio:\(Float(width)/Float(height))"/>
-        </span>
-        """
+    func svgImage(file: String, part: SVGSelection, altText: String) -> String {
+        let path = "\(file)#svgView(viewBox(\(part.x), \(part.y), \(part.width), \(part.height)))"
+        return image(file: path, width: part.width, height: part.height, altText: altText)
     }
 
     func downloadButtons(_ buttons: [(file: String, text: String, downloadName: String?)]) -> String {
@@ -103,8 +99,11 @@ struct HTMLElementsGenerator {
         """
     }
 
-    func scriptInclude(path: String) -> String {
-        "<script src=\"\(path)\"></script>"
+    func scriptInclude(path: String, asModule: Bool) -> String {
+        if asModule {
+            return "<script type=\"module\" src=\"\(path)\"></script>"
+        }
+        return "<script src=\"\(path)\"></script>"
     }
 
     func codeHighlightFooter() -> String {

Sources/Generator/Generators/OverviewPageGenerator.swift

@@ -25,6 +25,7 @@ struct OverviewPageGenerator {
                 sectionUrl: section.sectionUrl(for: language),
                 languageButton: languageButton,
                 page: section)
+            content[.language] = language
             content[.contentClass] = "overview"
             content[.header] = makeHeader(page: section, metadata: metadata, language: language)
             content[.content] = makeContent(section: section, language: language)

Sources/Generator/Generators/OverviewSectionGenerator.swift

@@ -2,36 +2,81 @@ import Foundation
 
 struct OverviewSectionGenerator {
 
-    private let multipleSectionsTemplate: OverviewSectionTemplate
-
-    private let singleSectionsTemplate: OverviewSectionCleanTemplate
+    private let factory: TemplateFactory
 
     private let generator: ThumbnailListGenerator
 
-    init(factory: TemplateFactory, results: GenerationResultsHandler) {
-        self.multipleSectionsTemplate = factory.overviewSection
-        self.singleSectionsTemplate = factory.overviewSectionClean
+    private let siteRoot: Element
+
+    private let results: GenerationResultsHandler
+
+    init(factory: TemplateFactory, siteRoot: Element, results: GenerationResultsHandler) {
+        self.factory = factory
+        self.siteRoot = siteRoot
+        self.results = results
         self.generator = ThumbnailListGenerator(factory: factory, results: results)
     }
 
     func generate(sections: [Element], in parent: Element, language: String, sectionItemCount: Int) -> String {
         let content = sectionsContent(sections, in: parent, language: language, sectionItemCount: sectionItemCount)
-        if parent.showMostRecentSection {
-            let news = newsSectionContent(for: parent, language: language, sectionItemCount: sectionItemCount)
-            return news + "\n" + content
-        } else {
-            return content
-        }
+        let firstSection = firstSectionContent(for: parent, language: language, sectionItemCount: sectionItemCount)
+        return firstSection + content
     }
 
-    private func newsSectionContent(for element: Element, language: String, sectionItemCount: Int) -> String {
-        // let shownElements = element.mostRecentElements(sectionItemCount)
-        return ""
-//        return generator.generateContent(
-//            items: shownElements,
-//            parent: element,
-//            language: language,
-//            style: element.thumbnailStyle)
+    private func firstSectionContent(for element: Element, language: String, sectionItemCount: Int) -> String {
+        guard element.needsFirstSection else {
+            return ""
+        }
+        let metadata = element.localized(for: language)
+        var result = ""
+        if element.showMostRecentSection {
+            let shownElements = element.mostRecentElements(4).enumerated().map { (number, child) in
+                makeSlideshowItem(child, parent: element, language: language, number: number)
+            }
+            let title = metadata.mostRecentTitle ?? "Recent"
+            result = factory.slideshow.generate([.content: shownElements.joined(separator: "\n"), .title: title])
+        }
+        if !element.featuredPages.isEmpty {
+            let elements = element.featuredPages.compactMap { id -> Element? in
+                guard let linked = siteRoot.find(id) else {
+                    results.warning("Unknown id '\(id)' in 'featuredPages'", source: element.path)
+                    return nil
+                }
+                return linked
+            }.prefix(4).enumerated().map { number, page in
+                makeSlideshowItem(page, parent: element, language: language, number: number)
+            }
+            let title = metadata.featuredTitle ?? "Featured"
+            result += factory.slideshow.generate([.content: elements.joined(separator: "\n"), .title: title])
+        }
+        return factory.slideshows.generate([.content : result])
+    }
+
+    private func makeSlideshowItem(_ item: Element, parent: Element, language: String, number: Int) -> String {
+        let metadata = item.localized(for: language)
+        var content = [SlideshowImageTemplate.Key : String]()
+        content[.number] = "\(number + 1)"
+        content[.altText] = metadata.linkPreviewDescription
+
+        if item.state.hasThumbnailLink {
+            let fullPageUrl = item.fullPageUrl(for: language)
+            let relativePageUrl = parent.relativePathToFileWithPath(fullPageUrl)
+            content[.url] = "href=\"\(relativePageUrl)\""
+        }
+
+        // Image already assumed to be generated
+        let (_, thumbnailDestPath) = item.thumbnailFilePath(for: language)
+        let thumbnailDestNoExtension = thumbnailDestPath.dropAfterLast(".")
+        content[.image] = parent.relativePathToFileWithPath(thumbnailDestNoExtension)
+
+        if let suffix = metadata.thumbnailSuffix {
+            content[.title] = factory.html.make(title: metadata.title, suffix: suffix)
+        } else {
+            content[.title] = metadata.title
+        }
+        let path = item.makePath(language: language, from: siteRoot)
+        content[.subtitle] = factory.pageLink.makePath(components: path)
+        return factory.slideshowImage.generate(content)
     }
 
     private func sectionsContent(_ sections: [Element], in parent: Element, language: String, sectionItemCount: Int) -> String {
@@ -50,7 +95,7 @@ struct OverviewSectionGenerator {
                 style: section.thumbnailStyle)
             content[.more] = metadata.moreLinkText
 
-            return multipleSectionsTemplate.generate(content)
+            return factory.overviewSection.generate(content)
         }
         .joined(separator: "\n")
     }
@@ -62,6 +107,6 @@ struct OverviewSectionGenerator {
             parent: section,
             language: language,
             style: section.thumbnailStyle)
-        return singleSectionsTemplate.generate(content)
+        return factory.overviewSectionClean.generate(content)
     }
 }

Sources/Generator/Generators/PageContentGenerator.swift

@@ -6,8 +6,6 @@ struct PageContentGenerator {
 
     private let factory: TemplateFactory
 
-    private let swift = SyntaxHighlighter(format: HTMLOutputFormat())
-
     private let siteRoot: Element
 
     private let results: GenerationResultsHandler
@@ -18,42 +16,89 @@ struct PageContentGenerator {
         self.results = results
     }
 
-    func generate(page: Element, language: String, content: String) -> (content: String, includesCode: Bool) {
-        var hasCodeContent = false
+    func generate(page: Element, language: String, content: String) -> (content: String, headers: RequiredHeaders) {
+        let parser = PageContentParser(
+            factory: factory,
+            siteRoot: siteRoot,
+            results: results,
+            page: page, 
+            language: language)
+        return parser.generatePage(from: content)
+    }
+
+}
+
+final class PageContentParser {
+
+    private let pageLinkMarker = "page:"
+
+    private let largeImageIndicator = "*large*"
+
+    private let factory: TemplateFactory
+
+    private let swift = SyntaxHighlighter(format: HTMLOutputFormat())
+
+    private let siteRoot: Element
+
+    private let results: GenerationResultsHandler
+
+    private let page: Element
+
+    private let language: String
+
+    private var headers = RequiredHeaders()
+
+    private var largeImageCount: Int = 0
+
+    init(factory: TemplateFactory, siteRoot: Element, results: GenerationResultsHandler, page: Element, language: String) {
+        self.factory = factory
+        self.siteRoot = siteRoot
+        self.results = results
+        self.page = page
+        self.language = language
+    }
+
+    func generatePage(from content: String) -> (content: String, headers: RequiredHeaders) {
+        headers = .init()
 
         let imageModifier = Modifier(target: .images) { html, markdown in
-            processMarkdownImage(markdown: markdown, html: html, page: page, language: language)
+            self.processMarkdownImage(markdown: markdown, html: html)
         }
         let codeModifier = Modifier(target: .codeBlocks) { html, markdown in
             if markdown.starts(with: "```swift") {
                 let code = markdown.between("```swift", and: "```").trimmed
-                return "<pre><code>" + swift.highlight(code) + "</pre></code>"
+                return "<pre><code>" + self.swift.highlight(code) + "</pre></code>"
             }
-            hasCodeContent = true
+            self.headers.insert(.codeHightlighting)
             return html
         }
         let linkModifier = Modifier(target: .links) { html, markdown in
-            handleLink(page: page, language: language, html: html, markdown: markdown)
+            self.handleLink(html: html, markdown: markdown)
         }
         let htmlModifier = Modifier(target: .html) { html, markdown in
-            handleHTML(page: page, language: language, html: html, markdown: markdown)
+            self.handleHTML(html: html, markdown: markdown)
+        }
+        let headlinesModifier = Modifier(target: .headings) { html, markdown in
+            self.handleHeadlines(html: html, markdown: markdown)
         }
 
-        let parser = MarkdownParser(modifiers: [imageModifier, codeModifier, linkModifier, htmlModifier])
-        return (parser.html(from: content), hasCodeContent)
+        let parser = MarkdownParser(modifiers: [imageModifier, codeModifier, linkModifier, htmlModifier, headlinesModifier])
+        return (parser.html(from: content), headers)
+
     }
 
-    private func handleLink(page: Element, language: String, html: String, markdown: Substring) -> String {
+    private func handleLink(html: String, markdown: Substring) -> String {
         let file = markdown.between("(", and: ")")
-        if file.hasPrefix("page:") {
-            let pageId = file.replacingOccurrences(of: "page:", with: "")
+        if file.hasPrefix(pageLinkMarker) {
+            let textToChange = file.dropAfterFirst("#")
+            let pageId = textToChange.replacingOccurrences(of: pageLinkMarker, with: "")
             guard let pagePath = results.getPagePath(for: pageId, source: page.path, language: language) else {
                 // Remove link since the page can't be found
                 return markdown.between("[", and: "]")
             }
             // Adjust file path to get the page url
             let url = page.relativePathToOtherSiteElement(file: pagePath)
-            return html.replacingOccurrences(of: file, with: url)
+            return html.replacingOccurrences(of: textToChange, with: url)
         }
 
         if let filePath = page.nonAbsolutePathRelativeToRootForContainedInputFile(file) {
@@ -63,7 +108,7 @@ struct PageContentGenerator {
         return html
     }
 
-    private func handleHTML(page: Element, language: String, html: String, markdown: Substring) -> String {
+    private func handleHTML(html: String, markdown: Substring) -> String {
         // TODO: Check HTML code in markdown for required resources
         //print("[HTML] Found in page \(page.path):")
         //print(markdown)
@@ -74,20 +119,37 @@ struct PageContentGenerator {
         return html
     }
 
-    private func processMarkdownImage(markdown: Substring, html: String, page: Element, language: String) -> String {
+    private func handleHeadlines(html: String, markdown: Substring) -> String {
+        let id = markdown
+            .last(after: "#")
+            .trimmed
+            .filter { $0.isNumber || $0.isLetter || $0 == " " }
+            .lowercased()
+            .components(separatedBy: " ")
+            .filter { $0 != "" }
+            .joined(separator: "-")
+        let parts =  html.components(separatedBy: ">")
+        return parts[0] + " id=\"\(id)\">" + parts.dropFirst().joined(separator: ">")
+    }
+
+    private func processMarkdownImage(markdown: Substring, html: String) -> String {
         // Split the markdown ![alt](file title)
         // There are several known shorthand commands
-        // For images: ![left_title](file right_title)
+        // For images: ![*large* left_title](file right_title)
         // For videos: ![option1,option2,...](file)
         // For svg with custom area: ![x,y,width,height](file.svg)
-        // For downloads: ![download](file1, text1; file2, text2, ...)
-        // For a simple boxes: ![box](title;body)
+        // For downloads: ![download](file1, text1; file2, text2, (download-name); ...)
+        // For a simple box: ![box](title;body)
+        // For 3D models: ![3d](file;Description)
         // A fancy page link: ![page](page_id)
         // External pages: ![external](url1, text1; url2, text2, ...)
-        let fileAndTitle = markdown.between("(", and: ")")
-        let alt = markdown.between("[", and: "]").nonEmpty
+        guard let fileAndTitle = markdown.between(first: "](", andLast: ")").removingPercentEncoding else {
+            results.warning("Invalid percent encoding for markdown image", source: page.path)
+            return ""
+        }
+        let alt = markdown.between("[", and: "]").nonEmpty?.removingPercentEncoding
         if let alt = alt, let command = ShorthandMarkdownKey(rawValue: alt) {
-            return handleShortHandCommand(command, page: page, language: language, content: fileAndTitle)
+            return handleShortHandCommand(command, content: fileAndTitle)
         }
 
         let file = fileAndTitle.dropAfterFirst(" ")
@@ -95,51 +157,80 @@ struct PageContentGenerator {
 
         let fileExtension = file.lastComponentAfter(".").lowercased()
         if let _ = ImageType(fileExtension: fileExtension) {
-            return handleImage(page: page, file: file, rightTitle: title, leftTitle: alt)
+            return handleImage(file: file, rightTitle: title, leftTitle: alt, largeImageCount: &largeImageCount)
         }
         if let _ = VideoType(rawValue: fileExtension) {
-            return handleVideo(page: page, file: file, optionString: alt)
+            return handleVideo(file: file, optionString: alt)
         }
-        if fileExtension == "svg" {
-            return handleSvg(page: page, file: file, area: alt)
+        switch fileExtension {
+        case "svg":
+            return handleSvg(file: file, area: alt)
+        case "gif":
+            return handleGif(file: file, altText: alt ?? "gif image")
+        default:
+            return handleFile(file: file, fileExtension: fileExtension)
         }
-        return handleFile(page: page, file: file, fileExtension: fileExtension)
     }
 
-    private func handleShortHandCommand(_ command: ShorthandMarkdownKey, page: Element, language: String, content: String) -> String {
+    private func handleShortHandCommand(_ command: ShorthandMarkdownKey, content: String) -> String {
         switch command {
         case .downloadButtons:
-            return handleDownloadButtons(page: page, content: content)
+            return handleDownloadButtons(content: content)
         case .externalLink:
-            return handleExternalButtons(page: page, content: content)
+            return handleExternalButtons(content: content)
         case .includedHtml:
-            return handleExternalHTML(page: page, file: content)
+            return handleExternalHTML(file: content)
         case .box:
-            return handleSimpleBox(page: page, content: content)
+            return handleSimpleBox(content: content)
         case .pageLink:
-            return handlePageLink(page: page, language: language, pageId: content)
+            return handlePageLink(pageId: content)
+        case .model3d:
+            return handle3dModel(content: content)
         }
     }
 
-    private func handleImage(page: Element, file: String, rightTitle: String?, leftTitle: String?) -> String {
+    private func handleImage(file: String, rightTitle: String?, leftTitle: String?, largeImageCount: inout Int) -> String {
         let imagePath = page.pathRelativeToRootForContainedInputFile(file)
-
+        let left: String
+        let createFullScreenVersion: Bool
+        if let leftTitle {
+            createFullScreenVersion = leftTitle.hasPrefix(largeImageIndicator)
+            left = leftTitle.dropBeforeFirst(largeImageIndicator).trimmed
+        } else {
+            left = ""
+            createFullScreenVersion = false
+        }
         let size = results.requireFullSizeMultiVersionImage(
             source: imagePath,
             destination: imagePath,
             requiredBy: page.path)
 
-        let content: [PageImageTemplate.Key : String] = [
-            .image: file.dropAfterLast("."),
-            .imageExtension: file.lastComponentAfter("."),
-            .width: "\(Int(size.width))",
-            .height: "\(Int(size.height))",
-            .leftText: leftTitle ?? "",
-            .rightText: rightTitle ?? ""]
-        return factory.image.generate(content)
+        let altText = left.nonEmpty ?? rightTitle ?? "image"
+
+        var content = [PageImageTemplateKey : String]()
+        content[.altText] = altText
+        content[.image] = file.dropAfterLast(".")
+        content[.imageExtension] = file.lastComponentAfter(".")
+        content[.width] = "\(Int(size.width))"
+        content[.height] = "\(Int(size.height))"
+        content[.leftText] = left
+        content[.rightText] = rightTitle ?? ""
+
+        guard createFullScreenVersion else {
+            return factory.image.generate(content)
+        }
+
+        results.requireOriginalSizeImages(
+            source: imagePath,
+            destination: imagePath,
+            requiredBy: page.path)
+
+        largeImageCount += 1
+        content[.number] = "\(largeImageCount)"
+        return factory.largeImage.generate(content)
     }
 
-    private func handleVideo(page: Element, file: String, optionString: String?) -> String {
+    private func handleVideo(file: String, optionString: String?) -> String {
         let options: [PageVideoTemplate.VideoOption] = optionString.unwrapped { string in
             string.components(separatedBy: " ").compactMap { optionText -> PageVideoTemplate.VideoOption? in
                 guard let optionText = optionText.trimmed.nonEmpty else {
@@ -152,46 +243,105 @@ struct PageContentGenerator {
                 return option
             }
         } ?? []
-        // TODO: Check page folder for alternative video versions
-        let sources: [PageVideoTemplate.VideoSource] = [(url: file, type: .mp4)]
 
-        let filePath = page.pathRelativeToRootForContainedInputFile(file)
-        results.require(file: filePath, source: page.path)
+        let prefix = file.lastComponentAfter("/").dropAfterLast(".")
+
+        // Find all video files starting with the name of the video as a prefix
+        var sources: [PageVideoTemplate.VideoSource] = []
+        do {
+            let folder = results.contentFolder.appendingPathComponent(page.path)
+            let filesInFolder = try FileManager.default.contentsOfDirectory(atPath: folder.path)
+            sources += selectVideoFiles(with: prefix, from: filesInFolder)
+        } catch {
+            results.warning("Failed to check for additional videos", source: page.path)
+        }
+        // Also look in external files
+        sources += selectVideoFiles(with: prefix, from: page.externalFiles)
+            .map { (page.relativePathToFileWithPath($0.url), $0.type) }
+
+        // Require all video files
+        sources.forEach {
+            let path = page.pathRelativeToRootForContainedInputFile($0.url)
+            results.require(file: path, source: page.path)
+        }
+        // Sort, so that order of selection in browser is defined
+        sources.sort { $0.url < $1.url }
         return factory.video.generate(sources: sources, options: options)
     }
 
-    private func handleSvg(page: Element, file: String, area: String?) -> String {
+    private func selectVideoFiles<T>(with prefix: String, from all: T) -> [PageVideoTemplate.VideoSource] where T: Sequence, T.Element == String {
+        all.compactMap {
+                guard $0.lastComponentAfter("/").hasPrefix(prefix) else {
+                    return nil
+                }
+                guard let type = VideoType(rawValue: $0.lastComponentAfter(".").lowercased()) else {
+                    return nil
+                }
+                return (url: $0, type: type)
+            }
+    }
+
+    private func handleGif(file: String, altText: String) -> String {
         let imagePath = page.pathRelativeToRootForContainedInputFile(file)
         results.require(file: imagePath, source: page.path)
 
-        guard let area = area else {
-            return factory.html.svgImage(file: file)
+        guard let size = results.getImageSize(atPath: imagePath, source: page.path) else {
+            return ""
         }
-        let parts = area.components(separatedBy: ",").map { $0.trimmed }
-        guard parts.count == 4,
-              let x = Int(parts[0].trimmed),
-              let y = Int(parts[1].trimmed),
-              let width = Int(parts[2].trimmed),
-              let height = Int(parts[3].trimmed) else {
-            results.warning("Invalid area string for svg image", source: page.path)
-            return factory.html.svgImage(file: file)
-        }
-
-        return factory.html.svgImage(file: file, x: x, y: y, width: width, height: height)
+        let width = Int(size.width)
+        let height = Int(size.height)
+        return factory.html.image(file: file, width: width, height: height, altText: altText)
     }
 
-    private func handleFile(page: Element, file: String, fileExtension: String) -> String {
+    private func handleSvg(file: String, area: String?) -> String {
+        let imagePath = page.pathRelativeToRootForContainedInputFile(file)
+        results.require(file: imagePath, source: page.path)
+
+        guard let size = results.getImageSize(atPath: imagePath, source: page.path) else {
+            return "" // Missing image warning already produced
+        }
+        let width = Int(size.width)
+        let height = Int(size.height)
+
+        var altText = "image " + file.lastComponentAfter("/")
+        guard let area = area else {
+            return factory.html.image(file: file, width: width, height: height, altText: altText)
+        }
+        let parts = area.components(separatedBy: ",").map { $0.trimmed }
+        switch parts.count {
+        case 1:
+            return factory.html.image(file: file, width: width, height: height, altText: parts[0])
+        case 4:
+            break
+        case 5:
+            altText = parts[4]
+        default:
+            results.warning("Invalid area string for svg image", source: page.path)
+            return factory.html.image(file: file, width: width, height: height, altText: altText)
+        }
+        guard let x = Int(parts[0]),
+              let y = Int(parts[1]),
+              let partWidth = Int(parts[2]),
+              let partHeight = Int(parts[3]) else {
+            results.warning("Invalid area string for svg image", source: page.path)
+            return factory.html.image(file: file, width: width, height: height, altText: altText)
+        }
+        let part = SVGSelection(x, y, partWidth, partHeight)
+        return factory.html.svgImage(file: file, part: part, altText: altText)
+    }
+
+    private func handleFile(file: String, fileExtension: String) -> String {
         results.warning("Unhandled file \(file) with extension \(fileExtension)", source: page.path)
         return ""
     }
 
-    private func handleDownloadButtons(page: Element, content: String) -> String {
+    private func handleDownloadButtons(content: String) -> String {
         let buttons = content
             .components(separatedBy: ";")
             .compactMap { button -> (file: String, text: String, downloadName: String?)? in
                 let parts = button.components(separatedBy: ",")
                 guard parts.count == 2 || parts.count == 3 else {
-                    results.warning("Invalid button definition", source: page.path)
+                    results.warning("Invalid download definition with \(parts)", source: page.path)
                     return nil
                 }
                 let file = parts[0].trimmed
@@ -207,7 +357,7 @@ struct PageContentGenerator {
         return factory.html.downloadButtons(buttons)
     }
 
-    private func handleExternalButtons(page: Element, content: String) -> String {
+    private func handleExternalButtons(content: String) -> String {
         let buttons = content
             .components(separatedBy: ";")
             .compactMap { button -> (url: String, text: String)? in
@@ -216,7 +366,10 @@ struct PageContentGenerator {
                     results.warning("Invalid external link definition", source: page.path)
                     return nil
                 }
-                let url = parts[0].trimmed
+                guard let url = parts[0].trimmed.addingPercentEncoding(withAllowedCharacters: .urlQueryAllowed) else {
+                    results.warning("Invalid external link \(parts[0].trimmed)", source: page.path)
+                    return nil
+                }
                 let title = parts[1].trimmed
 
                 return (url, title)
@@ -224,12 +377,12 @@ struct PageContentGenerator {
         return factory.html.externalButtons(buttons)
     }
 
-    private func handleExternalHTML(page: Element, file: String) -> String {
+    private func handleExternalHTML(file: String) -> String {
         let path = page.pathRelativeToRootForContainedInputFile(file)
         return results.getContentOfRequiredFile(at: path, source: page.path) ?? ""
     }
 
-    private func handleSimpleBox(page: Element, content: String) -> String {
+    private func handleSimpleBox(content: String) -> String {
         let parts = content.components(separatedBy: ";")
         guard parts.count > 1 else {
             results.warning("Invalid box specification", source: page.path)
@@ -240,16 +393,21 @@ struct PageContentGenerator {
         return factory.makePlaceholder(title: title, text: text)
     }
 
-    private func handlePageLink(page: Element, language: String, pageId: String) -> String {
+    private func handlePageLink(pageId: String) -> String {
         guard let linkedPage = siteRoot.find(pageId) else {
             // Checking the page path will add it to the missing pages
             _ = results.getPagePath(for: pageId, source: page.path, language: language)
             // Remove link since the page can't be found
             return ""
         }
+        guard linkedPage.state == .standard else {
+            // Prevent linking to unpublished content
+            return ""
+        }
         var content = [PageLinkTemplate.Key: String]()
         
         content[.title] = linkedPage.title(for: language)
+        content[.altText] = ""
 
         let fullThumbnailPath = linkedPage.thumbnailFilePath(for: language).destination
         // Note: Here we assume that the thumbnail was already used elsewhere, so already generated
@@ -280,4 +438,29 @@ struct PageContentGenerator {
         // We assume that the thumbnail images are already required by overview pages.
         return factory.pageLink.generate(content)
     }
+
+    private func handle3dModel(content: String) -> String {
+        let parts = content.components(separatedBy: ";")
+        guard parts.count > 1 else {
+            results.warning("Invalid 3d model specification", source: page.path)
+            return ""
+        }
+        let file = parts[0]
+        guard file.hasSuffix(".glb") else {
+            results.warning("Invalid 3d model file \(file) (must be .glb)", source: page.path)
+            return ""
+        }
+
+        // Ensure that file is available
+        let filePath = page.pathRelativeToRootForContainedInputFile(file)
+        results.require(file: filePath, source: page.path)
+
+        // Add required file to head
+        headers.insert(.modelViewer)
+
+        let description = parts.dropFirst().joined(separator: ";")
+        return """
+        <model-viewer alt="\(description)" src="\(file)" ar shadow-intensity="1" camera-controls touch-action="pan-y"></model-viewer>
+        """
+    }
 }

Sources/Generator/Generators/PageGenerator.swift

@@ -24,11 +24,12 @@ struct PageGenerator {
         let inputContentPath = page.path + "/\(language).md"
         let metadata = page.localized(for: language)
         let nextLanguage = page.nextLanguage(for: language)
-        let (pageContent, pageIncludesCode) = makeContent(
+        let (pageContent, additionalHeaders) = makeContent(
             page: page, metadata: metadata, language: language, path: inputContentPath)
 
         var content = [PageTemplate.Key : String]()
-        content[.head] = factory.pageHead.generate(page: page, language: language, includesCode: pageIncludesCode)
+        content[.language] = language
+        content[.head] = factory.pageHead.generate(page: page, language: language, headers: additionalHeaders)
         let sectionUrl = page.sectionUrl(for: language)
         content[.topBar] = factory.topBar.generate(sectionUrl: sectionUrl, languageButton: nextLanguage, page: page)
         content[.contentClass] = "content"
@@ -41,7 +42,7 @@ struct PageGenerator {
         content[.nextPageUrl] = navLink(from: page, to: nextPage, language: language)
         content[.footer] = results.getContentOfOptionalFile(at: page.additionalFooterContentPath, source: page.path)
 
-        if pageIncludesCode {
+        if additionalHeaders.contains(.codeHightlighting) {
             let highlightCode = factory.factory.html.codeHighlightFooter()
             content[.footer] = (content[.footer].unwrapped { $0 + "\n" } ?? "") + highlightCode
         }
@@ -73,7 +74,7 @@ struct PageGenerator {
         return factory.factory.html.makeNextText(text)
     }
 
-    private func makeContent(page: Element, metadata: Element.LocalizedMetadata, language: String, path: String) -> (content: String, includesCode: Bool) {
+    private func makeContent(page: Element, metadata: Element.LocalizedMetadata, language: String, path: String) -> (content: String, headers: RequiredHeaders) {
         if let raw = results.getContentOfMdFile(at: path, source: page.path)?.trimmed.nonEmpty {
             let (content, includesCode) = contentGenerator.generate(page: page, language: language, content: raw)
             return (content, includesCode)

Sources/Generator/Generators/PageHeadGenerator.swift

@@ -14,7 +14,7 @@ struct PageHeadGenerator {
         self.results = results
     }
 
-    func generate(page: Element, language: String, includesCode: Bool = false) -> String {
+    func generate(page: Element, language: String, headers: RequiredHeaders = .init()) -> String {
         let metadata = page.localized(for: language)
 
         var content = [PageHeadTemplate.Key : String]()
@@ -36,17 +36,16 @@ struct PageHeadGenerator {
             content[.image] =  factory.html.linkPreviewImage(file: linkPreviewImageName)
         }
         content[.customPageContent] = results.getContentOfOptionalFile(at: page.additionalHeadContentPath, source: page.path)
-        if includesCode {
-            let scriptPath = "assets/js/highlight.js"
-            let relative = page.relativePathToOtherSiteElement(file: scriptPath)
-            let includeText = factory.html.scriptInclude(path: relative)
-            if let head = content[.customPageContent] {
-                content[.customPageContent] = head + "\n" + includeText
-            } else {
-                content[.customPageContent] = includeText
-            }
-        }
 
+        let head = (content[.customPageContent].unwrapped { [$0] } ?? []) + headers
+            .sorted { $0.rawValue < $1.rawValue }
+            .map { option in
+                let scriptPath = "assets/js/\(option.rawValue)"
+                let relative = page.relativePathToOtherSiteElement(file: scriptPath)
+                return factory.html.scriptInclude(path: relative, asModule: option.asModule)
+            }
+
+        content[.customPageContent] = head.joined(separator: "\n")
         return factory.pageHead.generate(content)
     }
 }

Sources/Generator/Generators/ShorthandMarkdownKey.swift

@@ -26,4 +26,9 @@ enum ShorthandMarkdownKey: String {
      A pretty link to another page on the site.
      */
     case pageLink = "page"
+
+    /**
+     A 3D model to display
+     */
+    case model3d = "3d"
 }

Sources/Generator/Generators/SiteGenerator.swift

@@ -38,7 +38,7 @@ struct SiteGenerator {
             elementsToProcess.append(contentsOf: element.linkedElements)
 
             processAllFiles(for: element)
-            if !element.elements.isEmpty {
+            if element.hasVisibleChildren {
                 overviewGenerator.generate(section: element, language: language)
             } else {
                 pageGenerator.generate(

Sources/Generator/Generators/ThumbnailListGenerator.swift

@@ -30,6 +30,7 @@ struct ThumbnailListGenerator {
         let (thumbnailSourcePath, thumbnailDestPath) = item.thumbnailFilePath(for: language)
         let thumbnailDestNoExtension = thumbnailDestPath.dropAfterLast(".")
         content[.image] = parent.relativePathToFileWithPath(thumbnailDestNoExtension)
+        content[.altText] = metadata.linkPreviewDescription
 
         if style == .large, let suffix = metadata.thumbnailSuffix {
             content[.title] = factory.html.make(title: metadata.title, suffix: suffix)

Sources/Generator/Processing/DependencyCheck.swift

@@ -4,7 +4,14 @@ func checkDependencies() -> Bool {
     print("--- DEPENDENCIES -----------------------------------")
     print("                                                    ")
     defer { print("                                                    ") }
-    return checkImageOptimAvailability() && checkMagickAvailability() && checkCwebpAvailability() && checkAvifAvailability()
+    var valid = true
+    valid = checkImageOptimAvailability() && valid
+    valid = checkMagickAvailability() && valid
+    valid = checkCwebpAvailability() && valid
+    valid = checkAvifAvailability() && valid
+    valid = checkUglifyJsAvailability() && valid
+    valid = checkCleanCssAvailability() && valid
+    return valid
 }
 
 private func checkImageOptimAvailability() -> Bool {
@@ -14,7 +21,7 @@ private func checkImageOptimAvailability() -> Bool {
         if version.count > 1 {
             print("            ImageOptim: \(version.map { "\($0)" }.joined(separator: "."))")
         } else {
-            print("            ImageOptim: Not found")
+            print("            ImageOptim: Not found, download app from https://imageoptim.com/mac and install using 'npm install imageoptim-cli'")
             return false
         }
     } catch {
@@ -29,7 +36,7 @@ private func checkMagickAvailability() -> Bool {
         let output = try safeShell("magick --version")
         guard let version = output.components(separatedBy: "ImageMagick ").dropFirst().first?
             .components(separatedBy: " ").first else {
-            print("                Magick: Not found")
+            print("                Magick: Not found, install using 'brew install imagemagick'")
             return false
         }
         print("                Magick: \(version)")
@@ -47,7 +54,7 @@ private func checkCwebpAvailability() -> Bool {
         if version.count > 1 {
             print("                 cwebp: \(version.map { "\($0)" }.joined(separator: "."))")
         } else {
-            print("                 cwebp: Not found")
+            print("                 cwebp: Not found, download from https://developers.google.com/speed/webp/download")
             return false
         }
     } catch {
@@ -64,7 +71,7 @@ private func checkAvifAvailability() -> Bool {
         if version.count > 1 {
             print("                  avif: \(version.map { "\($0)" }.joined(separator: "."))")
         } else {
-            print("                  avif: Not found")
+            print("                  avif: Not found, install using 'npm install avif'")
             return false
         }
     } catch {
@@ -73,3 +80,40 @@ private func checkAvifAvailability() -> Bool {
     }
     return true
 }
+
+
+private func checkUglifyJsAvailability() -> Bool {
+    do {
+        let output = try safeShell("uglifyjs --version")
+        let version = output.dropBeforeFirst("uglify-js").components(separatedBy: ".").compactMap { Int($0.trimmed) }
+        if version.count > 1 {
+            print("             uglify-js: \(version.map { "\($0)" }.joined(separator: "."))")
+        } else {
+            print("'\(output)'")
+            print("             uglify-js: Not found, install using 'npm install uglify-js'")
+            return false
+        }
+    } catch {
+        print("             uglify-js: Failed to get version (\(error))")
+        return false
+    }
+    return true
+}
+
+
+private func checkCleanCssAvailability() -> Bool {
+    do {
+        let output = try safeShell("cleancss --version")
+        let version = output.components(separatedBy: ".").compactMap { Int($0.trimmed) }
+        if version.count > 1 {
+            print("              cleancss: \(version.map { "\($0)" }.joined(separator: "."))")
+        } else {
+            print("              cleancss: Not found, install using 'npm install clean-css-cli'")
+            return false
+        }
+    } catch {
+        print("              cleancss: Failed to get version (\(error))")
+        return false
+    }
+    return true
+}

Sources/Generator/Processing/FileGenerator.swift

@@ -61,26 +61,6 @@ final class FileGenerator {
         print("")
     }
 
-    func writeResultsToFile(file: URL) throws {
-        var lines: [String] = []
-        func add<S>(_ name: String, _ property: S, convert: (S.Element) -> String) where S: Sequence {
-            let elements = property.map { "  " + convert($0) }.sorted()
-            guard !elements.isEmpty else {
-                return
-            }
-            lines.append("\(name):")
-            lines.append(contentsOf: elements)
-        }
-        add("Missing files", missingFiles) { "\($0.key) (required by \($0.value))" }
-        add("Unreadable files", unreadableFiles) { "\($0.key) (required by \($0.value.source)): \($0.value.message)" }
-        add("Unreadable files", unreadableFiles) { "\($0.key) (required by \($0.value.source)): \($0.value.message)" }
-        add("Unwritable files", unwritableFiles) { "\($0.key) (required by \($0.value.source)): \($0.value.message)" }
-        add("External files", files.external) { "\($0.key) (from \($0.value))" }
-
-        let data = lines.joined(separator: "\n").data(using: .utf8)!
-        try data.createFolderAndWrite(to: file)
-    }
-
     private func didCopyFile() {
         numberOfCopiedFiles += 1
         print("          Copied files: \(numberOfCopiedFiles)/\(numberOfFilesToCopy)   \r", terminator: "")
@@ -259,6 +239,16 @@ final class FileGenerator {
     }
 
     func writeResults(to file: URL) {
+        guard !unreadableFiles.isEmpty || !unwritableFiles.isEmpty || !failedMinifications.isEmpty || !missingFiles.isEmpty || !copiedFiles.isEmpty || !minifiedFiles.isEmpty || !files.expected.isEmpty || !files.external.isEmpty else {
+            do {
+                if FileManager.default.fileExists(atPath: file.path) {
+                    try FileManager.default.removeItem(at: file)
+                }
+            } catch {
+                print("    Failed to delete file log: \(error)")
+            }
+            return
+        }
         var lines: [String] = []
         func add<S>(_ name: String, _ property: S, convert: (S.Element) -> String) where S: Sequence {
             let elements = property.map { "  " + convert($0) }.sorted()
@@ -275,12 +265,13 @@ final class FileGenerator {
         add("Copied files", copiedFiles) { $0 }
         add("Minified files", minifiedFiles) { $0 }
         add("Expected files", files.expected) { "\($0.key) (required by \($0.value))" }
+        add("External files", files.external) { "\($0.key) (required by \($0.value))" }
 
         let data = lines.joined(separator: "\n").data(using: .utf8)!
         do {
             try data.createFolderAndWrite(to: file)
         } catch {
-            print("    Failed to save log: \(error)")
+            print("    Failed to save file log: \(error)")
         }
     }
 }

Sources/Generator/Processing/GenerationResultsHandler.swift

@@ -155,11 +155,11 @@ final class GenerationResultsHandler {
 
     private func markForCopyOrMinification(file: String, source: String) {
         let ext = file.lastComponentAfter(".")
-        if configuration.minifyCSSandJS, ext == "js" {
+        if configuration.minifyJavaScript, ext == "js" {
             files.toMinify[file] = (source, .js)
             return
         }
-        if configuration.minifyCSSandJS, ext == "css" {
+        if configuration.minifyCSS, ext == "css" {
             files.toMinify[file] = (source, .css)
             return
         }
@@ -314,7 +314,18 @@ final class GenerationResultsHandler {
         requireMultiVersionImage(source: source, destination: destination, requiredBy: path, width: configuration.pageImageWidth, desiredHeight: nil)
     }
 
-    @discardableResult
+    func requireOriginalSizeImages(
+        source: String,
+        destination: String,
+        requiredBy path: String) {
+            _ = requireScaledMultiImage(
+                source: source,
+                destination: destination.insert("@full", beforeLast: "."),
+                requiredBy: path,
+                width: configuration.fullScreenImageWidth,
+                desiredHeight: nil)
+        }
+
     private func requireScaledMultiImage(source: String, destination: String, requiredBy path: String, width: Int, desiredHeight: Int?) -> NSSize {
         let rawDestinationPath = destination.dropAfterLast(".")
         let avifPath = rawDestinationPath + ".avif"
@@ -327,7 +338,7 @@ final class GenerationResultsHandler {
     }
 
     private func markImageAsMissing(path: String, source: String) {
-        images.missing[source] = path
+        images.missing[path] = source
     }
 
     private func requireImage(at destination: String, generatedFrom source: String, requiredBy path: String, quality: Float, width: Int, height: Int?, alwaysGenerate: Bool) -> NSSize {
@@ -357,7 +368,7 @@ final class GenerationResultsHandler {
         return scaledSize
     }
 
-    private func getImageSize(atPath path: String, source: String) -> NSSize? {
+    func getImageSize(atPath path: String, source: String) -> NSSize? {
         if let size = imageSizeCache[path] {
             return size
         }
@@ -405,8 +416,7 @@ final class GenerationResultsHandler {
         guard existingJob.width != job.width else {
             return
         }
-        warning("Different width \(existingJob.width) as \(job.path) (width \(job.width))",
-                destination: job.destination, path: existingJob.path)
+        warning("Existing job with width \(existingJob.width) (from \(existingJob.path)), but width \(job.width)", destination: job.destination, path: existingJob.path)
     }
 
     // MARK: Visual output
@@ -444,6 +454,16 @@ final class GenerationResultsHandler {
     }
 
     func writeResults(to file: URL) {
+        guard !missingFiles.isEmpty || !unreadableFiles.isEmpty || !unwritableFiles.isEmpty || !missingLinkedPages.isEmpty || !pageWarnings.isEmpty || !generatedFiles.isEmpty || !draftPages.isEmpty || !emptyPages.isEmpty else {
+            do {
+                if FileManager.default.fileExists(atPath: file.path) {
+                    try FileManager.default.removeItem(at: file)
+                }
+            } catch {
+                print("    Failed to delete generation log: \(error)")
+            }
+            return
+        }
         var lines: [String] = []
         func add<S>(_ name: String, _ property: S, convert: (S.Element) -> String) where S: Sequence {
             let elements = property.map { "  " + convert($0) }.sorted()
@@ -458,14 +478,14 @@ final class GenerationResultsHandler {
         add("Unwritable files", unwritableFiles) { "\($0.key) (required by \($0.value.source)): \($0.value.message)" }
         add("Missing linked pages", missingLinkedPages) { "\($0.key) (linked by \($0.value))" }
         add("Warnings", pageWarnings) { "\($0.source): \($0.message)" }
+        add("Generated files", generatedFiles) { $0 }
         add("Drafts", draftPages) { $0 }
         add("Empty pages", emptyPages) { "\($0.key) (from \($0.value))" }
-        add("Generated files", generatedFiles) { $0 }
         let data = lines.joined(separator: "\n").data(using: .utf8)!
         do {
             try data.createFolderAndWrite(to: file)
         } catch {
-            print("    Failed to save log: \(error)")
+            print("    Failed to save generation log: \(error)")
         }
     }
 }

Sources/Generator/Processing/ImageGenerator.swift

@@ -312,6 +312,16 @@ final class ImageGenerator {
     }
 
     func writeResults(to file: URL) {
+        guard !missingImages.isEmpty || !unreadableImages.isEmpty || !failedImages.isEmpty || !unhandledImages.isEmpty || !imageWarnings.isEmpty || !generatedImages.isEmpty || !optimizedImages.isEmpty else {
+            do {
+                if FileManager.default.fileExists(atPath: file.path) {
+                    try FileManager.default.removeItem(at: file)
+                }
+            } catch {
+                print("    Failed to delete image log: \(error)")
+            }
+            return
+        }
         var lines: [String] = []
         func add<S>(_ name: String, _ property: S, convert: (S.Element) -> String) where S: Sequence {
             let elements = property.map { "  " + convert($0) }.sorted()
@@ -332,7 +342,7 @@ final class ImageGenerator {
         do {
             try data.createFolderAndWrite(to: file)
         } catch {
-            print("    Failed to save log: \(error)")
+            print("    Failed to save image log: \(error)")
         }
     }
 }

Sources/Generator/Processing/MetadataInfoLogger.swift

@@ -151,6 +151,16 @@ final class MetadataInfoLogger {
     }
 
     func writeResults(to file: URL) {
+        guard !errors.isEmpty || !warnings.isEmpty || !unreadableMetadata.isEmpty || !unusedProperties.isEmpty || !invalidProperties.isEmpty || !unknownProperties.isEmpty || !missingProperties.isEmpty else {
+            do {
+                if FileManager.default.fileExists(atPath: file.path) {
+                    try FileManager.default.removeItem(at: file)
+                }
+            } catch {
+                print("    Failed to delete metadata log: \(error)")
+            }
+            return
+        }
         var lines: [String] = []
         func add<S>(_ name: String, _ property: S, convert: (S.Element) -> String) where S: Sequence {
             let elements = property.map { "  " + convert($0) }.sorted()
@@ -172,7 +182,7 @@ final class MetadataInfoLogger {
         do {
             try data.createFolderAndWrite(to: file)
         } catch {
-            print("    Failed to save log: \(error)")
+            print("    Failed to save metadata log: \(error)")
         }
     }
 }

Sources/Generator/Processing/RequiredHeaders.swift

@@ -0,0 +1,15 @@
+import Foundation
+
+enum HeaderFile: String {
+    case codeHightlighting = "highlight.js"
+    case modelViewer = "model-viewer.js"
+
+    var asModule: Bool {
+        switch self {
+        case .codeHightlighting: return false
+        case .modelViewer: return true
+        }
+    }
+}
+
+typealias RequiredHeaders = Set<HeaderFile>

Sources/Generator/Templates/Elements/PageImageTemplate.swift

@@ -1,15 +1,31 @@
 import Foundation
 
+enum PageImageTemplateKey: String, CaseIterable {
+    case altText = "ALT_TEXT"
+    case image = "IMAGE"
+    case imageExtension = "IMAGE_EXT"
+    case width = "WIDTH"
+    case height = "HEIGHT"
+    case leftText = "LEFT_TEXT"
+    case rightText = "RIGHT_TEXT"
+    case number = "NUMBER"
+}
+
+struct EnlargeableImageTemplate: Template {
+
+    typealias Key = PageImageTemplateKey
+
+    static let templateName = "image-enlargeable.html"
+
+    let raw: String
+
+    let results: GenerationResultsHandler
+
+}
+
 struct PageImageTemplate: Template {
 
-    enum Key: String, CaseIterable {
-        case image = "IMAGE"
-        case imageExtension = "IMAGE_EXT"
-        case width = "WIDTH"
-        case height = "HEIGHT"
-        case leftText = "LEFT_TEXT"
-        case rightText = "RIGHT_TEXT"
-    }
+    typealias Key = PageImageTemplateKey
 
     static let templateName = "image.html"
 

Sources/Generator/Templates/Elements/PageLinkTemplate.swift

@@ -3,6 +3,7 @@ import Foundation
 struct PageLinkTemplate: Template {
 
     enum Key: String, CaseIterable {
+        case altText = "ALT_TEXT"
         case url = "URL"
         case image = "IMAGE"
         case title = "TITLE"

Sources/Generator/Templates/Elements/SlideshowImageTemplate.swift

@@ -0,0 +1,23 @@
+import Foundation
+
+struct SlideshowImageTemplate: Template {
+
+    enum Key: String, CaseIterable {
+        case altText = "ALT_TEXT"
+        case url = "URL"
+        case image = "IMAGE"
+        case title = "TITLE"
+        case subtitle = "SUBTITLE"
+        case number = "NUMBER"
+    }
+
+    static let templateName = "slideshow-image.html"
+
+    let raw: String
+
+    let results: GenerationResultsHandler
+
+    func makePath(components: [String]) -> String {
+        components.joined(separator: " » ") //  » ")
+    }
+}

Sources/Generator/Templates/Elements/SlideshowTemplate.swift

@@ -0,0 +1,15 @@
+import Foundation
+
+struct SlideshowTemplate: Template {
+
+    enum Key: String, CaseIterable {
+        case title = "TITLE"
+        case content = "CONTENT"
+    }
+
+    static let templateName = "slideshow.html"
+
+    let raw: String
+
+    let results: GenerationResultsHandler
+}

Sources/Generator/Templates/Elements/SlideshowsTemplate.swift

@@ -0,0 +1,14 @@
+import Foundation
+
+struct SlideshowsTemplate: Template {
+
+    enum Key: String, CaseIterable {
+        case content = "CONTENT"
+    }
+
+    static let templateName = "slideshows.html"
+
+    let raw: String
+
+    let results: GenerationResultsHandler
+}

Sources/Generator/Templates/Elements/ThumbnailTemplate.swift

@@ -6,6 +6,7 @@ protocol ThumbnailTemplate {
 }
 
 enum ThumbnailKey: String, CaseIterable {
+    case altText = "ALT_TEXT"
     case url = "URL"
     case image = "IMAGE"
     case title = "TITLE"

Sources/Generator/Templates/Filled/LocalizedSiteTemplate.swift

@@ -51,7 +51,7 @@ struct LocalizedSiteTemplate {
         self.month = df2
 
         let df3 = DateFormatter()
-        df3.dateFormat = "dd"
+        df3.dateFormat = "d"
         df3.locale = Locale(identifier: language)
         self.day = df3
 
@@ -67,7 +67,7 @@ struct LocalizedSiteTemplate {
             sections: sections,
             topBarWebsiteTitle: site.topBarTitle)
         self.pageHead = PageHeadGenerator(factory: factory, results: results)
-        self.overviewSection = OverviewSectionGenerator(factory: factory, results: results)
+        self.overviewSection = OverviewSectionGenerator(factory: factory, siteRoot: site, results: results)
     }
 
     // MARK: Content

Sources/Generator/Templates/Pages/PageTemplate.swift

@@ -3,6 +3,7 @@ import Foundation
 struct PageTemplate: Template {
 
     enum Key: String, CaseIterable {
+        case language = "LANG"
         case head = "HEAD"
         case topBar = "TOP_BAR"
         case contentClass = "CONTENT_CLASS"

Sources/Generator/Templates/TemplateFactory.swift

@@ -51,8 +51,18 @@ final class TemplateFactory {
 
     let image: PageImageTemplate
 
+    let largeImage: EnlargeableImageTemplate
+
     let video: PageVideoTemplate
 
+    // MARK: Slideshow
+
+    let slideshows: SlideshowsTemplate
+
+    let slideshow: SlideshowTemplate
+
+    let slideshowImage: SlideshowImageTemplate
+
     // MARK: HTML
 
     let html: HTMLElementsGenerator
@@ -61,21 +71,28 @@ final class TemplateFactory {
 
     init(templateFolder: URL, results: GenerationResultsHandler) throws {
         self.templateFolder = templateFolder
-        self.backNavigation = try .init(in: templateFolder, results: results)
-        self.pageHead = try .init(in: templateFolder, results: results)
-        self.topBar = try .init(in: templateFolder, results: results)
-        self.overviewSection = try .init(in: templateFolder, results: results)
-        self.overviewSectionClean = try .init(in: templateFolder, results: results)
-        self.box = try .init(in: templateFolder, results: results)
-        self.pageLink = try .init(in: templateFolder, results: results)
-        self.largeThumbnail = try .init(in: templateFolder, results: results)
-        self.squareThumbnail = try .init(in: templateFolder, results: results)
-        self.smallThumbnail = try .init(in: templateFolder, results: results)
-        self.leftHeader = try .init(in: templateFolder, results: results)
-        self.centeredHeader = try .init(in: templateFolder, results: results)
-        self.page = try .init(in: templateFolder, results: results)
-        self.image = try .init(in: templateFolder, results: results)
-        self.video = try .init(in: templateFolder, results: results)
+        func create<T>() throws -> T where T: Template {
+            try .init(in: templateFolder, results: results)
+        }
+        self.backNavigation = try create()
+        self.pageHead = try create()
+        self.topBar = try create()
+        self.overviewSection = try create()
+        self.overviewSectionClean = try create()
+        self.box = try create()
+        self.pageLink = try create()
+        self.largeThumbnail = try create()
+        self.squareThumbnail = try create()
+        self.smallThumbnail = try create()
+        self.leftHeader = try create()
+        self.centeredHeader = try create()
+        self.page = try create()
+        self.image = try create()
+        self.largeImage = try create()
+        self.video = try create()
+        self.slideshow = try create()
+        self.slideshows = try create()
+        self.slideshowImage = try create()
         self.html = .init()
     }
 

Sources/Generator/run.swift

@@ -18,10 +18,15 @@ private func loadConfiguration(at configPath: String) -> Configuration? {
     print("                                                    ")
     print("    Configuration file: \(configPath)")
     let configUrl = URL(fileURLWithPath: configPath)
-    let config: Configuration
+    guard configUrl.exists else {
+        print("                 Error: Configuration file not found")
+        return nil
+    }
+    var config: Configuration
     do {
         let data = try Data(contentsOf: configUrl)
         config = try JSONDecoder().decode(from: data)
+        config.adjustPathsRelative(to: configUrl.deletingLastPathComponent())
     } catch {
         print("   Configuration error: \(error)")
         return nil
@@ -48,7 +53,10 @@ private func loadSiteData(in folder: URL, runFolder: URL) throws -> (root: Eleme
         print("                Error: No site root loaded, aborting generation")
         return nil
     }
-    let pageMap = root.languages.map { (language: $0.language, pages: root.getExternalPageMap(language: $0.language)) }
+    let pageMap = root.languages.map { language in
+        (language: language.language,
+         pages: root.getExternalPageMap(language: language.language, log: log))
+    }
     log.printMetadataScanOverview(languages: root.languages.count)
     return (root, pageMap)
 }
@@ -108,15 +116,15 @@ private func copyFiles(files: FileData, configuration: Configuration, runFolder:
         runFolder: runFolder,
         files: files)
     generator.generate()
+    let file = runFolder.appendingPathComponent("files.txt")
+    generator.writeResults(to: file)
 }
 
 private func finish(start: Date, complete: Bool) {
     print("--- SUMMARY ----------------------------------------")
     print("                                                    ")
     let duration = Int(-start.timeIntervalSinceNow.rounded())
-    if duration < 60 {
-        print("              Duration: \(duration) s")
-    } else if duration < 3600 {
+    if duration < 3600 {
         print(String(format: "              Duration: %d:%02d", duration / 60, duration % 60))
     } else {
         print(String(format: "              Duration: %d:%02d:%02d", duration / 3600, (duration / 60) % 60, duration % 60))

config_example.json

@@ -1,6 +1,8 @@
 {
     "pageImageWidth" : 748,
-    "minifyCSSandJS" : true,
+    "fullScreenImageWidth" : 4000,
+    "minifyJavaScript" : false,
+    "minifyCSS" : false,
     "createMdFilesIfMissing" : false,
     "contentPath" : "/path/to/content/folder",
     "outputPath" : "/path/to/output/folder")

install.sh

@@ -1,14 +1,17 @@
 #!/bin/bash
 # Install the required dependencies for CHGenerator
 
-# Note: The following is only required if `minifyCSSandJS=True`
-# is set in the generator configuration
+# Install magick to resize images
+brew install imagemagick
 
-# Install the Javascript minifier
+# Install avif to create AVIF versions of images
+npm install avif -g
+
+# Install the Javascript minifier (required if `minifyJavaScript = True`)
 # https://github.com/mishoo/UglifyJS
 npm install uglify-js -g
 
-# Install the clean-css minifier
+# Install the clean-css minifier (required if `minifyCSS = True`)
 # https://github.com/clean-css/clean-css-cli
 npm install clean-css-cli -g