feat: Initial commit

.editorconfig

@@ -0,0 +1,7 @@
+root = true
+
+[*.swift]
+indent_style = space
+indent_size = 2
+tab_width = 2
+trim_trailing_whitespace = true

.gitignore

@@ -0,0 +1,16 @@
+.DS_Store
+/build
+/.build
+/.swiftpm
+/*.xcodeproj
+.publish
+Output
+public/*
+.hugo_build.lock
+deploy
+node_modules
+env
+Package.resolved
+
+# Local Netlify folder
+.netlify

.swiftformat

@@ -0,0 +1,11 @@
+--self init-only
+--indent 2
+--ifdef indent
+--trimwhitespace always
+--wraparguments before-first
+--wrapparameters before-first
+--wrapcollections preserve
+--wrapconditions after-first
+--typeblanklines preserve
+--commas inline
+--stripunusedargs closure-only

Package.swift

@@ -0,0 +1,22 @@
+// swift-tools-version: 5.10
+import PackageDescription
+
+let package = Package(
+  name: "Docs",
+  platforms: [.macOS(.v12)],
+  dependencies: [
+    .package(url: "https://github.com/loopwerk/Saga", from: "2.0.0"),
+    .package(url: "https://github.com/loopwerk/SagaParsleyMarkdownReader", from: "1.0.0"),
+    .package(url: "https://github.com/loopwerk/SagaSwimRenderer", from: "1.0.0")
+  ],
+  targets: [
+    .executableTarget(
+      name: "Docs",
+      dependencies: [
+        .product(name: "Saga", package: "Saga"),
+        .product(name: "SagaParsleyMarkdownReader", package: "SagaParsleyMarkdownReader"),
+        .product(name: "SagaSwimRenderer", package: "SagaSwimRenderer")
+      ]
+    )
+  ]
+)

Sources/Docs/Extensions.swift

@@ -0,0 +1,90 @@
+import Foundation
+import Saga
+
+extension Date {
+  func formatted(_ format: String) -> String {
+    let formatter = DateFormatter()
+    formatter.dateFormat = format
+    return formatter.string(from: self)
+  }
+}
+
+extension Item where M == ArticleMetadata {
+
+  /// The article summary, which is used when displaying a list of articles.
+  var summary: String {
+    // Use the summary if supplied in the articles front-matter.
+    if let summary = metadata.summary {
+      return summary
+    }
+    // Generate the summary from the first 255 words of the article.
+    return String(body.withoutHtmlTags.truncate())
+  }
+
+  /// The articles banner image path.
+  var imagePath: String {
+    let image = metadata.image ?? "\(filenameWithoutExtension).png"
+    return "/articles/images/\(image)"
+  }
+
+  /// An easy way to only get public articles, since ArticleMetadata.public is optional
+  var `public`: Bool {
+    #if DEBUG
+      return true
+    #else
+      return metadata.public ?? true
+    #endif
+  }
+
+  func getPrimaryTag() -> String? {
+    guard let primaryTag = metadata.primaryTag else {
+      guard metadata.tags.count == 1 else { return nil }
+      return metadata.tags[0]
+    }
+    return primaryTag
+  }
+}
+
+// NOTE: Most of these are taken from https://github.com/loopwerk/loopwerk.io
+
+extension String {
+
+  /// Used to generate the word count of an article, to be displayed as metadata about
+  /// the article.
+  var numberOfWords: Int {
+    let characterSet = CharacterSet.whitespacesAndNewlines.union(.punctuationCharacters)
+    let components = self.components(separatedBy: characterSet)
+    return components.filter { !$0.isEmpty }.count
+  }
+
+  // This is a sloppy implementation but sadly `NSAttributedString(data:options:documentAttributes:)`
+  // is not available in CoreFoundation, and as such can't run on Linux (blocking CI builds).
+  var withoutHtmlTags: String {
+    return replacingOccurrences(of: "(?m)<pre><span></span><code>[\\s\\S]+?</code></pre>", with: "", options: .regularExpression, range: nil)
+      .replacingOccurrences(of: "<[^>]+>", with: "", options: .regularExpression, range: nil)
+      .trimmingCharacters(in: .whitespacesAndNewlines)
+  }
+
+  /// See https://jinja2docs.readthedocs.io/en/stable/templates.html#truncate
+  func truncate(length: Int = 255, killWords: Bool = false, end: String = "...", leeway: Int = 5) -> String {
+    if count <= length + leeway {
+      return self
+    }
+
+    if killWords {
+      return prefix(length - end.count) + end
+    }
+
+    return prefix(length - end.count).split(separator: " ").dropLast().joined(separator: " ") + end
+  }
+
+  /// Removes unwanted breaks that are caused by the way markdown files are formatted by
+  /// prettier in my neovim setup.  When not applied then paragraphs get split up improperly
+  /// causing them to display funny on the site.
+  var removeBreaks: String {
+    replacingOccurrences(of: "<br>", with: "")
+      .replacingOccurrences(of: "<br />", with: "")
+      .trimmingCharacters(in: .whitespacesAndNewlines)
+  }
+
+}

Sources/Docs/Metadata.swift

@@ -0,0 +1,51 @@
+import Foundation
+import Saga
+
+/// Represents constants about the site.
+enum SiteMetadata {
+  #if DEBUG
+    static let url = URL(string: "http://localhost:3000")!
+  #else
+    static let url = URL(string: "https://mhoush.com")!
+  #endif
+  static let name = "mhoush"
+  static let author = "Michael Housh"
+  /// Summary used for metadata / twitter card for home page,
+  /// also displayed at bottom of articles.
+  static let summary = """
+  HVAC business owner with over 27 years of experience. Writes articles about HVAC,
+  Programming, Home-Performance, and Building Science
+  """
+  /// The default twitter image when linking to home page.
+  static let twitterImage = "/static/images/home-twitter-image.png"
+}
+
+/// Represents the valid file metadata for an article.
+struct ArticleMetadata: Metadata {
+  /// The articles associated tags.
+  let tags: [String]
+
+  /// A custom summary for the article, if not supplied then it is generated
+  /// using the `String.truncate` method in the String+Extensions.swift file.
+  var summary: String?
+
+  /// Whether the articles is public, defaults to `true` if not supplied.
+  /// This is useful if working on an article.
+  let `public`: Bool?
+
+  /// Specify a custom banner image path, if not supplied it uses the articles
+  /// filename with a `png` extension and searches in the content/articles/images
+  /// directory.  So it's often not required to be supplied.
+  let image: String?
+
+  /// Specify the primary tag for suggesting related articles, if not supplied,
+  /// then most recent articles are suggested.
+  let primaryTag: String?
+}
+
+/// Represents valid metadata for the files that are not an `article`.
+struct PageMetadata: Metadata {
+
+  /// The section of the website for the file.
+  let section: String?
+}

Sources/Docs/Run.swift

@@ -0,0 +1,62 @@
+import Foundation
+import HTML
+import PathKit
+@preconcurrency import Saga
+import SagaParsleyMarkdownReader
+import SagaSwimRenderer
+
+@main
+struct Run {
+  static func main() async throws {
+    //   try await Saga(input: "content", output: "deploy")
+    //     // All markdown files within the "articles" subfolder will be parsed to html,
+    //     // using ArticleMetadata as the Item's metadata type.
+    //     // Furthermore we are only interested in public articles.
+    //     .register(
+    //       folder: "articles",
+    //       metadata: ArticleMetadata.self,
+    //       readers: [.parsleyMarkdownReader],
+    //       itemProcessor: sequence(removingBreaks, publicationDateInFilename, permalink),
+    //       filter: \.public,
+    //       writers: [
+    //         .itemWriter(swim(renderArticle)),
+    //         .listWriter(swim(renderArticles)),
+    //         .tagWriter(swim(renderTag), tags: \.metadata.tags),
+    //         .yearWriter(swim(renderYear)),
+    //         // Atom feed for all articles, and a feed per tag
+    //         .listWriter(
+    //           atomFeed(
+    //             title: SiteMetadata.name,
+    //             author: SiteMetadata.author,
+    //             baseURL: SiteMetadata.url,
+    //             summary: \.metadata.summary
+    //           ),
+    //           output: "feed.xml"
+    //         ),
+    //         .tagWriter(
+    //           atomFeed(
+    //             title: SiteMetadata.name,
+    //             author: SiteMetadata.author, baseURL: SiteMetadata.url, summary: \.metadata.summary
+    //           ),
+    //           output: "tag/[key]/feed.xml",
+    //           tags: \.metadata.tags
+    //         )
+    //       ]
+    //     )
+    //     // All the remaining markdown files will be parsed to html,
+    //     // using the default EmptyMetadata as the Item's metadata type.
+    //     .register(
+    //       metadata: PageMetadata.self,
+    //       readers: [.parsleyMarkdownReader],
+    //       itemProcessor: removingBreaks,
+    //       itemWriteMode: .keepAsFile, // need to keep 404.md as 404.html, not 404/index.html
+    //       writers: [.itemWriter(swim(renderPage))]
+    //     )
+    //
+    //     // Run the steps we registered above
+    //     .run()
+    //     // All the remaining files that were not parsed to markdown, so for example images, raw html files and css,
+    //     // are copied as-is to the output folder.
+    //     .staticFiles()
+  }
+}

Sources/Docs/Section.swift

@@ -0,0 +1,9 @@
+/// Represents different sections of the website.
+///
+/// This is used to render base layouts appropriately for the given section.
+enum Section: String {
+  case home
+  case about
+  case articles
+  case notFound
+}

Sources/Docs/Templates/BaseLayout.swift

@@ -0,0 +1,127 @@
+import Foundation
+import HTML
+
+/// The base page layout used to render the different sections of the website.
+///
+/// - Parameters:
+///   - conocicalURL: The url for the page.
+///   - section: The section of the page.
+///   - title: The page title.
+///   - rssLink: A prefix for generating an rss feed for the page (generally only used for articles).
+///   - extraHeader: Any extra items to be placed in the `head` of the html.
+func baseLayout(
+  canocicalURL: String,
+  section: Section,
+  title pageTitle: String,
+  rssLink: String = "",
+  extraHeader: NodeConvertible = Node.fragment([]),
+  @NodeBuilder children: () -> NodeConvertible
+) -> Node {
+  return [
+    .documentType("html"),
+    html(lang: "en-US") {
+      generateHeader(pageTitle, extraHeader)
+      body(class: "bg-page text-white pb-5 font-avenir \(section.rawValue)") {
+        siteHeader(section)
+
+        div(class: "container pt-12 lg:pt-28") {
+          children()
+        }
+
+        footer(rssLink)
+      }
+    }
+  ]
+}
+
+private func siteHeader(_ section: Section) -> Node {
+  header(class: "header") {
+    div(class: "header__inner") {
+      div(class: "header__logo") {
+        a(href: "/") {
+          div(class: "logo") {
+            "mhoush.com"
+          }
+        }
+      }
+    }
+    nav(class: "menu") {
+      ul(class: "flex flex-wrap gap-x-2 lg:gap-x-5") {
+        li {
+          a(class: section == .articles ? "active" : "", href: "/articles/") { "Articles" }
+        }
+        li {
+          a(class: section == .about ? "active" : "", href: "/about.html") { "About" }
+        }
+      }
+    }
+  }
+}
+
+private func footer(_ rssLink: String) -> Node {
+  div(class: "site-footer text-gray gray-links border-t border-light text-center pt-6 mt-8 text-sm") {
+    p {
+      "Copyright © Michael Housh 2023-\(Date().description.prefix(4))."
+    }
+    p {
+      "Built in Swift using"
+      a(href: "https://github.com/loopwerk/Saga", rel: "nofollow", target: "_blank") { "Saga" }
+      "("
+      %a(href: "https://github.com/m-housh/mhoush.com", rel: "nofollow", target: "_blank") { "source" }
+      %")."
+    }
+    p {
+      a(
+        href: "\(SiteMetadata.url.absoluteString)/articles/\(rssLink)feed.xml",
+        rel: "nofollow",
+        target: "_blank"
+      ) { "RSS" }
+      " | "
+      a(href: "https://github.com/m-housh", rel: "nofollow", target: "_blank") { "Github" }
+      " | "
+      a(
+        href: "https://www.youtube.com/channel/UCb58SeURd5bObfTiL0KoliA",
+        rel: "nofollow",
+        target: "_blank"
+      ) { "Youtube" }
+      " | "
+      a(href: "https://www.facebook.com/michael.housh", rel: "nofollow", target: "_blank") { "Facebook" }
+      " | "
+      a(href: "mailto:michael@mhoush.com", rel: "nofollow") { "Email" }
+    }
+    p {
+      span {
+        "All articles are licensed under Creative-Commons (CC BY-NC) 4.0"
+      }
+      a(href: "https://creativecommons.org/licenses/by-nc/4.0/") {
+        img(class: "justify-center", src: "/static/images/by-nc.png", width: "100")
+      }
+    }
+    script(src: "https://cdnjs.cloudflare.com/ajax/libs/prism/1.29.0/components/prism-core.min.js")
+    script(src: "https://cdnjs.cloudflare.com/ajax/libs/prism/1.29.0/plugins/keep-markup/prism-keep-markup.min.js")
+    script(src: "https://cdnjs.cloudflare.com/ajax/libs/prism/1.29.0/plugins/autoloader/prism-autoloader.min.js")
+  }
+}
+
+private func generateHeader(_ pageTitle: String, _ extraHeader: NodeConvertible) -> Node {
+  head {
+    meta(charset: "utf-8")
+    meta(content: "#0e1112", name: "theme-color", customAttributes: ["media": "(prefers-color-scheme: dark)"])
+    meta(content: "#566B78", name: "theme-color", customAttributes: ["media": "(prefers-color-scheme: light)"])
+    meta(content: "Michael Housh", name: "author")
+    meta(content: "Mhoush", name: "apple-mobile-web-app-title")
+    meta(content: "initial-scale=1.0, width=device-width", name: "viewport")
+    meta(content: "telephone=no", name: "format-detection")
+    meta(content: "True", name: "HandheldFriendly")
+    meta(content: "320", name: "MobileOptimized")
+    meta(content: "Mhoush", name: "og:site_name")
+    meta(content: "hvac, developer, swift, home-performance, design", name: "keywords")
+    title { SiteMetadata.name + ": \(pageTitle)" }
+    link(href: "/static/favicon.ico", rel: "shortcut icon")
+    link(href: "/static/output.css", rel: "stylesheet")
+    link(href: "/static/style.css", rel: "stylesheet")
+    link(href: "/articles/feed.xml", rel: "alternate", title: SiteMetadata.name, type: "application/rss+xml")
+    extraHeader
+    script(src: "https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js")
+  }
+}

Sources/Docs/Templates/Header.swift

@@ -0,0 +1,58 @@
+import Foundation
+import HTML
+import Saga
+
+enum HeaderType {
+  case article(Item<ArticleMetadata>)
+  case home
+}
+
+func generateHeader(
+  _ headerType: HeaderType
+) -> NodeConvertible {
+  switch headerType {
+  case .home:
+    return Node.fragment([
+      link(href: "/static/prism.css", rel: "stylesheet"),
+      meta(content: SiteMetadata.summary, name: "description"),
+      meta(content: "summary_large_image", name: "twitter:card"),
+      meta(content: SiteMetadata.twitterImage, name: "twitter:image"),
+      meta(content: SiteMetadata.name, name: "twitter:image:alt"),
+      meta(content: SiteMetadata.twitterImage, name: "og:url"),
+      meta(content: SiteMetadata.author, name: "og:title"),
+      meta(content: SiteMetadata.summary, name: "og:description"),
+      meta(content: SiteMetadata.twitterImage, name: "og:image"),
+      meta(content: "1014", name: "og:image:width"),
+      meta(content: "530", name: "og:image:height")
+    ])
+  case let .article(article):
+    return Node.fragment([
+      link(href: "/static/prism.css", rel: "stylesheet"),
+      link(href: "https://cdnjs.cloudflare.com/ajax/libs/font-awesome/4.7.0/css/font-awesome.min.css", rel: "stylesheet"),
+      meta(content: article.summary, name: "description"),
+      meta(content: "summary_large_image", name: "twitter:card"),
+      meta(content: article.imagePath, name: "twitter:image"),
+      meta(content: article.title, name: "twitter:image:alt"),
+      meta(content: ogURL(article), name: "og:url"),
+      meta(content: article.title, name: "og:title"),
+      meta(content: article.summary, name: "og:description"),
+      meta(content: article.imagePath, name: "og:image"),
+      meta(content: "1014", name: "og:image:width"),
+      meta(content: "530", name: "og:image:height"),
+      script(crossorigin: "anonymous", src: "https://kit.fontawesome.com/f209982030.js"),
+      Node.raw("""
+      <script>
+      MathJax = {
+        tex: {
+          inlineMath: [['$', '$']]
+        },
+        svg: {
+          fontCache: 'global'
+        }
+      };
+      </script>
+      """),
+      script(defer: true, src: "https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-svg.js")
+    ])
+  }
+}

Sources/Docs/Templates/RenderArticle.swift

@@ -0,0 +1,196 @@
+import Foundation
+import HTML
+import Saga
+
+func tagPrefix(index: Int, totalTags: Int) -> Node {
+  if index > 0 {
+    if index == totalTags - 1 {
+      return " and "
+    } else {
+      return ", "
+    }
+  }
+  return ""
+}
+
+func renderArticleInfo(_ article: Item<ArticleMetadata>) -> Node {
+  div(class: "text-gray gray-links text-sm") {
+    span(class: "border-r border-gray pr-2 mr-2") {
+      article.date.formatted("MMMM dd, yyyy")
+    }
+
+    %.text("\(article.body.withoutHtmlTags.numberOfWords) words, posted in ")
+
+    article.metadata.tags.sorted().enumerated().map { index, tag in
+      Node.fragment([
+        %tagPrefix(index: index, totalTags: article.metadata.tags.count),
+        Node.raw("""
+        <i class="fa fa-home"></i>
+        """),
+        %a(class: "text-orange [&:hover]:border-b border-green", href: "/articles/tag/\(tag.slugified)/") {
+          tag
+        }
+      ])
+    }
+  }
+}
+
+func ogURL(_ article: Item<ArticleMetadata>) -> String {
+  SiteMetadata.url
+    .appendingPathComponent("/articles/images/\(article.url)")
+    .absoluteString
+}
+
+private func parseOtherArticles(_ context: ItemRenderingContext<ArticleMetadata>) -> OtherArticles {
+  let allArticles = context.allItems.compactMap { $0 as? Item<ArticleMetadata> }
+  let otherArticles = allArticles
+    .filter { $0.url != context.item.url }
+
+  guard let primaryTag = context.item.getPrimaryTag() else {
+    return .all(otherArticles)
+  }
+
+  return .related(
+    tag: primaryTag,
+    items: otherArticles.sorted { lhs, rhs in
+      switch (lhs.metadata.tags.contains(primaryTag), rhs.metadata.tags.contains(primaryTag)) {
+      case (true, false): return true
+      default: return false
+      }
+    }
+  )
+}
+
+private enum OtherArticles {
+  case all([Item<ArticleMetadata>])
+  case related(tag: String, items: [Item<ArticleMetadata>])
+
+  var items: [Item<ArticleMetadata>] {
+    switch self {
+    case let .all(items): return items
+    case let .related(_, items): return items
+    }
+  }
+
+  var title: String {
+    switch self {
+    case .all: return "Recent Articles"
+    case .related: return "Related Articles"
+    }
+  }
+
+  var tag: String? {
+    guard case let .related(tag, _) = self else { return nil }
+    return tag
+  }
+}
+
+var tagSVG: Node {
+  Node.raw("""
+  <svg viewBox="0 0 33 33" version="1.1" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:sketch="http://www.bohemiancoding.com/sketch/ns" fill="#5a5a5a" stroke="#5a5a5a"><g id="SVGRepo_bgCarrier" stroke-width="0"></g><g id="SVGRepo_tracerCarrier" stroke-linecap="round" stroke-linejoin="round"></g><g id="SVGRepo_iconCarrier"> <title>tag-2</title> <desc>Created with Sketch Beta.</desc> <defs> </defs> <g id="Page-1" stroke="none" stroke-width="1" fill="none" fill-rule="evenodd" sketch:type="MSPage"> <g id="Icon-Set" sketch:type="MSLayerGroup" transform="translate(-360.000000, -774.000000)" fill="#5b5b5b"> <path d="M390.097,789.321 C390.097,789.849 389.611,790.623 389.095,791.139 L378.823,801.378 L365.634,788.197 L375.89,777.974 C376.36,777.504 377.111,776.903 377.641,776.903 L389.139,776.903 C389.668,776.903 390.097,777.331 390.097,777.858 L390.097,789.321 L390.097,789.321 Z M375.89,804.304 C375.079,805.111 373.765,805.111 372.955,804.304 L362.684,794.063 C361.873,793.256 361.873,791.946 362.684,791.139 L364.166,789.66 L377.341,802.856 L375.89,804.304 L375.89,804.304 Z M390.097,774.993 L376.683,774.993 C375.624,774.993 375.431,775.455 374.422,776.511 L361.217,789.676 C359.596,791.291 359.596,793.911 361.217,795.526 L371.487,805.767 C373.108,807.382 375.735,807.382 377.356,805.767 L390.563,792.602 C391.412,791.754 392.014,791.332 392.014,790.276 L392.014,776.903 C392.014,775.849 391.155,774.993 390.097,774.993 L390.097,774.993 Z M383.959,786.019 C383.148,786.826 381.835,786.826 381.024,786.019 C380.214,785.211 380.214,783.901 381.024,783.093 C381.835,782.285 383.148,782.285 383.959,783.093 C384.77,783.901 384.77,785.211 383.959,786.019 L383.959,786.019 Z M379.558,781.63 C377.937,783.246 377.937,785.865 379.558,787.481 C381.178,789.097 383.806,789.097 385.427,787.481 C387.047,785.865 387.047,783.246 385.427,781.63 C383.806,780.015 381.178,780.015 379.558,781.63 L379.558,781.63 Z" id="tag-2" sketch:type="MSShapeGroup"> </path> </g> </g> </g></svg>
+  """)
+}
+
+func renderArticle(context: ItemRenderingContext<ArticleMetadata>) -> Node {
+  let otherArticles = parseOtherArticles(context)
+
+  return baseLayout(
+    canocicalURL: context.item.url,
+    section: .articles,
+    title: context.item.title,
+    extraHeader: generateHeader(.article(context.item))
+  ) {
+    article(class: "prose") {
+      h1 { context.item.title }
+      div(class: "-mt-6") {
+        renderArticleInfo(context.item)
+      }
+      img(alt: "banner", src: context.item.imagePath)
+      Node.raw(context.item.body)
+    }
+
+    div(class: "border-t border-light pt-8 mt-16") {
+      div(class: "grid lg:grid-cols-2") {
+        h2(class: "text-4xl font-extrabold mb-8") { otherArticles.title }
+        if let tag = otherArticles.tag {
+          a(href: "/articles/tag/\(tag)") {
+            div(class: " [&:hover]:border-b border-orange px-5 flex flex-row gap-5") {
+              img(src: "/static/images/tag.svg", width: "40")
+              span(class: "text-4xl font-extrabold text-orange") { tag }
+            }
+          }
+        }
+      }
+
+      div(class: "grid lg:grid-cols-2 gap-10") {
+        otherArticles.items.prefix(2).map { renderArticleForGrid(article: $0) }
+      }
+
+      div(class: "prose mt-10") {
+        a(href: "/articles/") {
+          div(class: "flex flex-row gap-2") {
+            span(class: "mt-8") { "All Articles" }
+            img(src: "/static/images/document.svg", width: "40")
+          }
+        }
+      }
+    }
+
+    // Giscus comment section.
+    commentSection
+
+    div(class: "border-t border-light mt-8 pt-8") {
+      h2(class: "text-4xl font-extrabold mb-8") { "Author" }
+      div(class: "flex flex-col lg:flex-row gap-8") {
+        div(class: "flex-[0_0_120px]") {
+          img(class: "w-[120px] h-[120px] rounded-full", src: "/static/images/avatar.png")
+        }
+
+        div(class: "prose") {
+          h3(class: "!m-0") { SiteMetadata.author }
+          p(class: "text-gray") { SiteMetadata.summary }
+        }
+      }
+    }
+  }
+}
+
+func renderArticleForGrid(article: Item<ArticleMetadata>) -> Node {
+  section {
+    h2(class: "post-title text-2xl font-bold mb-2") {
+      a(class: "[&:hover]:border-b border-orange", href: article.url) { article.title }
+    }
+    renderArticleInfo(article)
+    p {
+      a(href: article.url) {
+        div {
+          // img(alt: "banner", src: article.imagePath)
+          article.summary
+        }
+      }
+    }
+  }
+}
+
+private var commentSection: Node {
+  div(class: "border-t border-light pt-8") {
+    Node.raw("""
+          <script src="https://giscus.app/client.js"
+            data-repo="m-housh/mhoush.com"
+            data-repo-id="R_kgDOJagAXA"
+            data-category="Article Discussions"
+            data-category-id="DIC_kwDOJagAXM4CnLfv"
+            data-mapping="pathname"
+            data-strict="0"
+            data-reactions-enabled="1"
+            data-emit-metadata="0"
+            data-input-position="bottom"
+            data-theme="preferred_color_scheme"
+            data-lang="en"
+            data-loading="lazy"
+            crossorigin="anonymous"
+            async>
+         </script>
+    """)
+  }
+}

Sources/Docs/Templates/RenderArticles.swift

@@ -0,0 +1,94 @@
+import Foundation
+import HTML
+import Saga
+
+func uniqueTagsWithCount(_ articles: [Item<ArticleMetadata>]) -> [(String, Int)] {
+  let tags = articles.flatMap { $0.metadata.tags }
+  let tagsWithCounts = tags.reduce(into: [:]) { $0[$1, default: 0] += 1 }
+  return tagsWithCounts.sorted { $0.1 > $1.1 }
+}
+
+func renderArticles(context: ItemsRenderingContext<ArticleMetadata>) -> Node {
+  let dateFormatter = DateFormatter()
+  dateFormatter.dateFormat = "yyyy"
+
+  let articlesPerYear = Dictionary(grouping: context.items, by: { dateFormatter.string(from: $0.date) })
+  let sortedByYearDescending = articlesPerYear.sorted { $0.key > $1.key }
+
+  return baseLayout(canocicalURL: "/articles/", section: .articles, title: "Articles", rssLink: "", extraHeader: "") {
+    // TODO: Add list of tags here that can be navigated to.
+    sortedByYearDescending.map { year, articles in
+      div {
+        div(class: "border-b border-light flex flex-row gap-4 mb-12") {
+          img(src: "/static/images/calendar.svg", width: "40")
+          h1(class: "text-4xl font-extrabold") { year }
+        }
+
+        div(class: "grid gap-10 mb-16") {
+          articles.map { renderArticleForGrid(article: $0) }
+        }
+      }
+    }
+  }
+}
+
+func renderTag<T>(context: PartitionedRenderingContext<T, ArticleMetadata>) -> Node {
+  let extraHeader = link(
+    href: "/articles/tag/\(context.key.slugified)/feed.xml",
+    rel: "alternate",
+    title: "\(SiteMetadata.name): articles with tag \(context.key)",
+    type: "application/rss+xml"
+  )
+
+  return baseRenderArticles(
+    context.items,
+    canocicalURL: "/articles/tag/\(context.key.slugified)/",
+    title: "Articles in \(context.key)",
+    rssLink: "tag/\(context.key.slugified)/",
+    extraHeader: extraHeader
+  ) {
+    div(class: "border-b border-light grid lg:grid-cols-2 mb-12") {
+      a(href: "/articles") {
+        div(class: "flex flex-row gap-2") {
+          img(src: "/static/images/tag.svg", width: "40")
+          h1(class: "text-4xl font-extrabold") { "\(context.key)" }
+          h1(class: "[&:hover]:border-b border-green text-2xl font-extrabold text-orange px-4") { "«" }
+        }
+      }
+    }
+  }
+}
+
+func renderYear<T>(context: PartitionedRenderingContext<T, ArticleMetadata>) -> Node {
+  baseRenderArticles(context.items, canocicalURL: "/articles/\(context.key)/", title: "Articles in \(context.key)")
+}
+
+private func baseRenderArticles(
+  _ articles: [Item<ArticleMetadata>],
+  canocicalURL: String,
+  title pageTitle: String,
+  rssLink: String = "",
+  extraHeader: NodeConvertible = Node.fragment([]),
+  @NodeBuilder label: () -> Node = { Node.fragment([]) }
+) -> Node {
+  return baseLayout(
+    canocicalURL: canocicalURL,
+    section: .articles,
+    title: pageTitle,
+    rssLink: rssLink,
+    extraHeader: extraHeader
+  ) {
+    label()
+    articles.map { article in
+      section(class: "mb-10") {
+        h1(class: "post-title text-2xl font-bold mb-2") {
+          a(class: "[&:hover]:border-b border-orange", href: article.url) { article.title }
+        }
+        renderArticleInfo(article)
+        p(class: "mt-4") {
+          a(href: article.url) { article.summary }
+        }
+      }
+    }
+  }
+}

Sources/Docs/Templates/RenderPage.swift

@@ -0,0 +1,62 @@
+import HTML
+import Saga
+
+func renderPage(context: ItemRenderingContext<PageMetadata>) -> Node {
+  let section = Section(rawValue: context.item.metadata.section ?? "")
+  assert(section != nil)
+
+  return baseLayout(
+    canocicalURL: context.item.url,
+    section: section!,
+    title: context.item.title,
+    extraHeader: section == .home ? generateHeader(.home) : Node.fragment([])
+  ) {
+    switch section {
+    case .home:
+      renderHome(body: context.item.body)
+    case .notFound:
+      let articles = context.allItems
+        .compactMap { $0 as? Item<ArticleMetadata> }
+        .prefix(10)
+      render404(body: context.item.body, articles: Array(articles))
+    default:
+      renderNonHome(body: context.item.body)
+    }
+  }
+}
+
+func renderHome(body: String) -> Node {
+  div {
+    img(alt: "Avatar", class: "my-24 w-[315px] h-200px mx-auto", src: "/static/images/avatar.png")
+
+    div(class: "my-24 uppercase font-avenir text-[40px] leading-[1.25] font-thin text-center [&>h1>strong]:font-bold") {
+      Node.raw(body)
+    }
+  }
+}
+
+func renderNonHome(body: String) -> Node {
+  article {
+    div(class: "prose") {
+      Node.raw(body)
+    }
+  }
+}
+
+func render404(body: String, articles: [Item<ArticleMetadata>]) -> Node {
+  article(class: "prose") {
+    Node.raw(body)
+
+    ul {
+      articles.map { article in
+        li {
+          a(href: article.url) { article.title }
+        }
+      }
+    }
+
+    div {
+      a(href: "/articles/") { "› See all articles" }
+    }
+  }
+}

content/404.md

@@ -0,0 +1,11 @@
+---
+section: notFound
+---
+
+# 404
+
+## Oops
+
+Your page was not found.
+
+Looking for one of the articles?

package.json

@@ -0,0 +1,24 @@
+{
+  "name": "docs.housh.dev",
+  "version": "1.0.0",
+  "description": "",
+  "main": "index.js",
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1",
+    "css-watch": "pnpm tailwindcss -i ./content/static/input.css -o ./content/static/output.css --minify --watch",
+    "css-build": "pnpm tailwindcss -i ./content/static/input.css -o ./content/static/output.css --minify"
+  },
+  "keywords": [],
+  "author": "",
+  "license": "ISC",
+  "devDependencies": {
+    "@tailwindcss/typography": "^0.5.16",
+    "tailwindcss": "^3.4.17"
+  },
+  "dependencies": {
+    "autoprefixer": "^10.4.20",
+    "postcss": "^8.5.3",
+    "sass": "^1.85.0",
+    "tailwind": "^4.0.0"
+  }
+}

tailwind.config.js

@@ -0,0 +1,105 @@
+import typography from "@tailwindcss/typography";
+import defaultTheme from "tailwindcss/defaultTheme";
+const colors = require("tailwindcss/colors");
+
+/** @type {import('tailwindcss').Config} */
+module.exports = {
+  content: ["./Sources/Mhoush/templates/*.swift", "./content/articles/*.md"],
+  theme: {
+    container: {
+      center: true,
+      padding: {
+        DEFAULT: "0",
+      },
+    },
+    screens: {
+      sm: "315px",
+      lg: "800px",
+    },
+    colors: {
+      inherit: "inherit",
+      transparent: "transparent",
+      white: "#f1f5f9",
+      orange: "#F5A87F",
+      red: colors.red,
+      blue: "#B4BEFE",
+      green: "#A6E3A1",
+      page: "#1E1E2E",
+      nav: "#0e1112",
+      sub: "#252f3f",
+      light: "#64748b",
+      gray: "#93a3b8",
+      pink: "#EE72F1",
+    },
+    extend: {
+      colors: {
+        sky: colors.sky,
+        blue: colors.blue,
+      },
+      fontFamily: {
+        avenir: ["Avenir", ...defaultTheme.fontFamily.sans],
+        anonymous: ["Anonymous Pro", ...defaultTheme.fontFamily.mono],
+      },
+      typography: (theme) => ({
+        DEFAULT: {
+          css: {
+            maxWidth: "100%",
+            "--tw-prose-body": theme("colors.white"),
+            "--tw-prose-headings": theme("colors.white"),
+            "--tw-prose-code": theme("colors.white"),
+            "--tw-prose-pre-bg": theme("colors.sub"),
+            "--tw-prose-hr": theme("colors.light"),
+            "--tw-prose-bullets": theme("colors.gray"),
+            "--tw-prose-counters": theme("colors.gray"),
+            "--tw-prose-quotes": theme("colors.gray"),
+            "--tw-prose-quote-borders": theme("colors.gray"),
+            a: {
+              color: theme("colors.green"),
+              textDecoration: "none",
+              fontWeight: "400",
+            },
+            strong: {
+              color: theme("colors.white"),
+              fontWeight: "800",
+            },
+            pre: {
+              fontSize: "1rem",
+              lineHeight: "1.5rem",
+            },
+          },
+        },
+      }),
+    },
+  },
+  corePlugins: {
+    contain: false,
+    ringWidth: false,
+    backdropFilter: false,
+    transform: false,
+    filter: false,
+    backgroundOpacity: false,
+    textOpacity: false,
+  },
+  plugins: [
+    typography({ target: "legacy" }),
+
+    function ({ addBase, theme }) {
+      function extractColorVars(colorObj, colorGroup = "") {
+        return Object.keys(colorObj).reduce((vars, colorKey) => {
+          const value = colorObj[colorKey];
+
+          const newVars =
+            typeof value === "string"
+              ? { [`--color${colorGroup}-${colorKey}`]: value }
+              : extractColorVars(value, `-${colorKey}`);
+
+          return { ...vars, ...newVars };
+        }, {});
+      }
+
+      addBase({
+        ":root": extractColorVars(theme("colors")),
+      });
+    },
+  ],
+};