How this website was made...

So it’s been checks notes 9 months since the last post from this website.

A lot has happened in the world of development since the last post (Swift 6.4 is out, Godot is now at 4.7 with 4.8 right around the corner and Unity 6.6 has released) and, while I’m very detached to the life of constant posting (aka I post when I actually have something to say and share that’s meaningful, fun or insightful that isn’t a repeat of what’s out there online), I did not expect to have such a long break between posts.

It wasn’t a lack of things to talk about, but other projects and IRL took over in terms of priority where I was only able to work on this site occasionally on my free time…

What I didn’t plan for is that, after one year of existence, this site has passed through 3 versions in order to reach a state that I’m comfortable with that allows for the maintenance requirements I need to post.

Prelude: What I wanted from this Website

The idea for this site originally began after I decided to start using RSS readers as my main daily feed for news and updates: while others like Social Media as their way to keep up to date with stuff, build a brand, become influencers and all that stuff, I never really liked it: a public space where everyone’s talking as loud as they can to get others attention to buy into their ideas is not really great for discussion and articulation of ideas.

While filling my RSS with blogs about development, I stumbled upon multiple of them posting about leaving Social Media and making a website for themselves as a way to not only have a better platform for discussing their thoughts, they wanted to make something for themselves.

That inspired me about something I never done before, even though I’ve first learned programming more than 10 years ago and worked on apps and games with other developers for many target audiences:

“Make an app for myself”

At this point, the challenge was set and I was excited to try my hand in it, all I needed was to set the parameters to make it more interesting (and more like me):

• For starters, I wanted to use Swift as the main driver for the site, due to being such a comfortable and ergonomic language to use: it’s safe, flexible, expressive, concise and can be expanded to be used in a variety of environments. I wanted to make it easier to scale it up in the future (e.g. adding a server, building it as an iOS/macOS/Linux/Windows app, WebAssembly support, etc.) and making Web development with a Swift twist:
  • HTML templates using Swift’s Result Builders, with support for CSS.
  • Compile-time type safety for the web.
  • Creating a Swift “App as a Package”.
  • Make the website easier to test, with both exhaustive and non-exhaustive testing.
  • Support for JavaScript frameworks and resources as plugins
  • Taking advance of the Swift package ecosystem in the development process.
  • Demonstrating the frameworks I made directly into the site itself (either as interactive demos or as part of building the pages themselves).
  • Using new features of Swift as they’re released (since the app was for myself, I didn’t risk any issues of it being unusable to people on older versions of the OS).
• I also wanted the website to support RSS, as it was the reason the website is being made.
• Another important feature was to make the site’s content all be an Obsidian Folder, that is then processed and served as webpages
  • The goal was to start with Static Site Generation (SSG), but leave the door open in the future for server-side rendering and building the website as a Desktop/Mobile app.
  • While it’s source code should be available to view, the content should stay private until it’s actually published.
  • As a long time PKM user, I also wanted my website pages to not be just generic pages, but contextual ones based on schemas (projects, posts, products, etc.)
• Last, but not least, it should be a digital window into my works, my recommendations and anything else I want to highlight that can be useful to others.
  • The idea is to bring my Github Portfolio into here, with more detailed developer notes, as well as making dev logs.

The requirements seemed simple at first, but little did I know that it’d take 4 iterations for me to get the website in a place that fulfilled most of the goals above.

Iteration #1: Publish

When first making the app, I searched for many different Static Site Generators for Swift to decide which one I wanted to use. Given the criteria, I already knew that whichever one I chose, it’d have to convert Markdown into usable Swift code and then publish it via Github pages.

So, I decided to base my work on John Sundell’s workflow for Swift by Sundell and use Publish to make my website: this seemed like a good idea at first, as the workflow was already battle-tested. The website at this point was split into two repositories: one for the source code, one for the deployed pages.

The initial version was organized as a Swift package as follows:

• Resources: Contains the CSS files used by the website
• Sources
  • AreasFeature containing the sections of the website
  • CSS to define CSS tags to apply to HTML
  • HTML to define common reusable HTML snippets
  • HomeFeature to define the landing page of the Website
  • PageFeature to define the HTML document itself
  • PostsFeature to handle the schema and views for posts
  • PublishIntegration to make the actual integration with Publish
  • Settings to define some website metadata
  • TagsFeature to provide tags for the posts
  • Website as the executable that actually generates the website when publish deploy is called

As I was already using a SwiftUI approach to create the HTML templates, I also decided to apply similar SwiftUI nomenclature and suffix types with “Screen” or “View” based on their function.

As is, the website was already good to go and the first version was already usable. It’s when I started to add more that the caveats started to pile up:
- A pretty opinionated approach that clashed with the schema-based approach I intended in the long-term meant that I would need a lot of boilerplate
- Publish was made on Swift 5.5, while we were already on 6.1, amidst the headaches of the Strict Concurrency model and before the approachable concurrency that’d come soon after: at that point, the package failed to work with Swift 6

However, these caveats only become a problem when considering the fact that the package stopped receiving updates and I had no free time, meaning a fork to fix these issues would take too much time, so I had to find another SSG.

Iteration #2: swift-html + Saga

This is when the website actually got interesting as a project, as I decided to go with Saga and used Coenttb’s fork of PointFree’s swift-html, which provided an API that’s very close to the actual HTML specification (and a cost that would bite me in the back later).

With this, I also decided it was finally time to unify both repositories into one, with Github Actions deploying only a specific subset of the website on push to it’s folder, changing to a Continuous Delivery workflow when the code is pushed to the main branch.

I also reworked the architecture to better fit some things to the development process:

• Sources
  • Assets now encapsulates all resources used by the website, with them now living in the package as a module, allowing access through the artsBlueprintsCodeBundle.
  • CSS was adjusted to import the theme, with class tags being now handled by swift-html
  • FileClient as a reexport of John Sundell’s Files package with extra utilities relevant only to the website. I chose to do a Reexport as means to keep the API surface, even if I end up changing the backend powering the module in the future
  • HTML now provides a solution to embed JS frameworks into a page for more functionality
  • Models now has all the schemas for the Website, instead of separating them per-feature: this allows better business rules integration without making too many workarounds or importing multiple packages for just one type
  • NavigationFeature replaces AreasFeature, providing the views for the sections of the website
  • PostViewerFeature is the new name of PostsFeature, which still handles the views of a post
  • RSS reexports FeedKit and provides a solution for RSS manipulation: while Saga provides a writer for creating RSS feeds automatically and is what is being used right now, a more domain-specific model will make it easier to work with RSS in the long-term. For now, it’s a placeholder of what’s to come…
  • SagaIntegration now replaces PublishIntegration, defining all the pipeline for the website’s deployment
  • Settings continues to exist, but now is a placeholder module. In the future, this will be where settings for the website will live.
  • TagViewerFeature is the new name of TagsFeature, containing all views for tags

Iteration #3: Saga + Elementary (we’re here)

In the meantime since then, Saga also got a new major version that made it easier to develop and iterate over the website to the point many of the original bottlenecks in earlier iterations are basically almost gone, opening the door for quicker improvements and feature additions:

• Actual support for programmatic items to be included in the pipeline (allows me to remove some workarounds to add missing entries)
• Build hooks (replaces a certain instability that existed of trying to hook into Saga’s pipeline to add and remove files that should be local, development-only or are irrelevant to the website’s content)
• CLI for development with hot reloading (while I was serving it before using npx prior to this, the setup I was using always had a caveat regarding refreshing the page or tracking the pages, which is now all addressed)

As the codebase itself also grew more mature in the time since, the integration into Saga’s pipeline also became easier, making it easier to maintain and update the site while still time-constrained by other projects.

What the Future Holds

The website is still far from done, but here’s some of what I’m planning for it right now (subject to change, of course):

• Dedicated Markdown Parser: currently I have an initial implementation in MarkdownHTML based on swift-markdown that I could turn into a Saga Reader, but it still requires lots of work. Currently, the website uses Parsley to provide conversion from Github-flavored Markdown, but, in the long-term, I want control over how the Markdown is parsed to HTML to make it easier to add features to webpages, as well as transform the content based on feature requests.
• Making interactive demos of my projects using WebAssembly, which would fulfill one of the goals of using Swift to make the website and being able to use my frameworks directly in posts to explain subjects.
• Showcase of projects, arts and crafts and fun articles/videos I find online worth a read/watch: most of the skeleton is already prepared, it just needs a style and for me to aggregate more development materiais to display.
• Growing from a Static Site: this is more into the future, but a dynamic site would allow me to offer more independence and control over my content.