zakkhoyt / swiftynotes

---

SwiftyNotes is a website, built using the Swift programming language, to provide quick idiomatic tips on the Swift language—aka writing Swifty code (yes, Swifty is a real term used). This repo contains the code that generates the website using the swift-website-dsl library. There are some pretty nerdy things in here to check out such as the fact that the code snippets are 100% valid Swift that are compiled before the site is generated.

I've learned so much from the Swift community. My hope is to give a little back with this project.

Contributions of any kind are most welcome. Even feel free to contribute a new tip 🤓.

Contribute a Swift Tip

If interested, create a pull request (PR) with a tip of your own! The below sections will help you get started with the code base, but here are the high level steps to contribute a new tip.

1. Create a new folder in the Notes folder named with the date to publish your tip (format: yyyy-mm-dd).
2. Add the tip's metadata json file. This is the content for the tip (e.g., title and body). Here is an example.
3. Add the tip's code snippet. This needs to be valid Swift code and should compliment the metadata above. Here is an example.
4. Make sure your tip is generated as expected by following the below getting started guide.
5. Make a PR with your new tip!

Getting Started

To test out the SwiftyNotes website locally

• Open terminal
• Clone this repo
  • git clone https://github.com/jasonzurita/swiftynotes
• Change directories to the cloned project
  • cd <path>/swiftynotes
• Generate the website
  • swift run
• Open the generated website in your browser
  • open _site/index.html

That's it 🥳. Make changes to the site, do a swift run, and refresh your browser!

Tech Stack

As mentioned, this website is generated using the swift-website-dsl library. This library is a reflection of the HTML spec codified and created to feel like SwiftUI in syntax.

Example from the SwiftyNotes site:

Html {
    Head(title: "SwiftyNotes", cssStyleFileName: "CodeColors.css")
    Body {
        SiteHeader()
        SiteNotes()
        Footer {
            P("Jason Zurita © 2024 | Built in Swift and ") {
                A(copy: "open source.", url: "https://github.com/jasonzurita/swiftynotes")
            }
        }
        .textAlign(.center)
        .color(.mediumGray)
    }
    .font(.apple)
    .textAlign(.center)
    .background(.color(.lightGray))
    .margin(0)
    .padding(0)
}

The website module consumes the above HTML eDSL. The result is a fully Swift defined site along with styling. When swift run is invoked, this module runs as an executable and generates HTML that is ready to be statically hosted and consumed by browsers.

Deployment

The SwiftyNotes site is hosted using CloudFlare pages as a static website. When a new commit is pushed to the main branch, GitHub Actions runs the tests, builds the website, and then uploads the generated site (in the _site directory) to CloudFlare to host it. Pretty much that simple.