I'm by no means a frontend engineer. I have a fundamental understanding of HTML, CSS, JavaScript, TypeScript, React, Vue, but I'm not interested in frontend development. With that in mind, let me tell you a story of the multiple iterations it took to get this website up and running.
So, as any good software engineer would do, I googled "best frontend framework" and found a bunch of articles. I read through a few of them and decided to go with Next.js + React. I had used React before and it seemed like a good choice. So I found a tutorial on how to set up Next.js + React.
So far so good. I initialize my project, install the dependencies, and start coding. It took way too long and since I wasn't up-to-date with the latest technologies, it was clearly more effort than I wanted to expend.
Round 2 starts, time to start researching. I'm on YouTube and I see a video about SvelteKit. The marketing worked on me, so I decided to try it out. Honestly, not as bad as Next.js + React. I was able to get a basic site up and running. I actually got it hosted and deployed using AWS. Nice!
However, my solution of CloudFront -> S3 with static output from SvelteKit didn't work. SvelteKit does not output the files in the expected directory structure, so the page doesn't load properly. There were issues with just refreshing the page. I attempted to see if there were settings I was missing, but to no avail.
There were solutions that involved me building a Lambda Function with API Gateway to serve the files. Hello? Like what in the world is going on? I just want to put static HTML files into a bucket and forget about it. From what I could tell, this is not possible with SvelteKit.
This time, I decided to go with the most basic solution. I'm just going to write HTML, CSS, and JavaScript. I'm going to return to the era of simplicity. Because really, what do I need them for? I'm not doing anything special. I'm just writing a blog. I don't need a frontend framework for that.
So, I write some plain old HTML files, copy and paste the Svelte HTML into them. And it pretty much works. However, there's some things I gave up when not using a framework. One of the simplest things is the ability to use a component. I have to copy and paste the header and footer into every single page. I'm not a fan of that.
At this point, I google how to return HTML. The only real solution I found was to use a <code>template</code> element. I write a bit of JavaScript and then add it to the page as a custom element. Pretty simple. However, the JavaScript tedious and the HTML would be enclosed in a string, so I lose all of the syntax highlighting and formatting.
Because this is a side project of mine, its time to write a custom solution for fun! I wrote a script to preprocess HTML files and automatically generate the JavaScript to create the custom HTML element. So I would just write HTML and it becomes an element that I can use in other HTML files. Simple!
My build script just preprocesses some HTML files, then copies everything to the build directory in the correct structure. I use npm http-server to serve it locally. Iterations are quick, just run the server, edit code, save changes, run build, reload page, done! Each step is less than 10ms, so its pretty much instant.
When using raw HTML, I thought styling would be an issue. From my previous experience, you needed to use one of those gargantuan frameworks to import other libraries that required preprocessing, compiling, and all of that extra stuff. To my surprise and delight, I found two simple solutions that just require you to import a CSS files. This site uses Pico.css for the overall styling and Highlight.js to highlight code blocks. Both of these libraries were basically plug and play with minimal configuration. That's exactly how these frontend frameworks should be.
In short, this site is hosted completely by AWS using Route53, CloudFront, and S3. I wrote a simple script that builds the entire project and deploys it to AWS. I didn't really have too many issues with this part. It was pretty straight forward using the AWS CDK.
Most articles online include a timestamp for when it was published and when it was last modified. I thought this would be a neat feature to include in my website. However, I needed to come up with another solution to implement this feature. I wanted to keep my simple build process but somehow inject the timestamps into the resulting HTML.
To keep track of the article's timestamps, I decided to implement a simple database; a json file. It keeps tracks of the articles based on their relative path in the repository. Then during the build process, it checks whether or not its seen that HTML file at that relative path. If not, initialize a value for that article with the published and modified time of now. Or if a article timestamp was found, compare a hash of the HTML file with the hash stored in the database. If they are different, then the article has been updated. So we set the last modified timestamp to now. To actually get the HTML injected, I do a simple search and replace for text in the HTML file.
Overall, this is a relatively simple mechanism to keep track of files. It's a bit fragile for detecting changes. For example, formatting changes to the HTML would trigger a new last modified timestamp. However, I don't mind it for now. I'm willing to tradeoff the simplicity for the fragility. Using a formatter as the first step in the build process helps to avoid this situation.
So as I keep writing articles, I noticed that I didn't like writing in HTML. It was verbose and writing code sometimes required escaping some HTML specific characters. I've used Markdown a ton and knew that Markdown has a one-to-one mapping with HTML. Also, Markdown is simpler to write and apply grammer tools to (not implemented yet so there's probably spelling and grammer mistakes all over the place).
So I when back to my preprocessor and added a bit of code that:
index.md fileindex.htmlThis was relatively simple because there's already libraries to convert Markdown to HTML. Additionally, these libraries already had integrations with Highlight.js, so I wouldn't lose syntax highlighting. All in all, the biggest effort was manually rewriting the HTML to Markdown, which was pretty simple with some clevery search and replace or search and delete.
So now, I only need to write a small HTML file named index.html then start writing the content in a index.md file. It's much easier for me to write this way but I retain all of features I need for writing articles.