Contents
Making 404Wolf.com
Inspiration
I initially was planning on working on various other ongoing projects, such as an English flashcard generating service, but decided that I wanted to have a good place to document my progress on everything else. I started by making a simple homepage, and then when determining how to integrate a post/blog system fell down the rabbithole of learning my first stack and javascript for the first time. I could’ve used Wordpress, but I thought it would be a good chance to learn how to do it from scratch.
I began working on this website during my second week of my batch at Recurse Center, an amazing open-ended programming retreat based in Brooklyn, NY.
Choosing frameworks
One of the main goals of this website was to get started with webdev. It was my
first proper “full stack project.” Previously I’d experimented with some
templated HTML, but I hadn’t done javascript before. I really enjoyed
Harvard’s CS50 React Native course’s video, where they speed-teach the language
(which is public and can be found
here). I also read over the
learnxinyminutes.com website to get a brief
overview of the syntax. I’ve found that javascript (and, later, typescript), is
weird, and not quite like other languages I’ve used. In some ways it’s
functional, especially with such flexible lambdas and promises. Yet, in others,
it’s object-orianted. Everything is a descendent of a primitive object, much
like Python, and you can have “classes,” but using it functionally is often a
lot more straightforward than in Python in my opinion.
For the frontend I went with React; I liked the idea of a composable component based system, it is quite popular, and I didn’t really know what I was getting into. At the time I didn’t know about React component libraries like MUI, so I ended up building everything from the ground up, which I think was good for learning, but bad for longer term maintenance.
Since I knew I was going to want a backend for things like managing the posts on
my website, I did a bit of research on how to set up a webserver for the
project. I considered using express or django to serve the site and
corresponding API, but a Recurse batch-mate introduced me to
NextJS, which was very easy to scaffold and fun to work
with. It was also very easy (and free!) to get it hosted with
Vercel. NextJS is an interesting framework that blends
React for the frontend with Express for the backend, so that you can write your
backend would-be API code in the same file directory, and even files, as your
frontend code.
Originally, I made my website pages pull from a folder of markdown files which I
edited and directly commited to Github. Eventually, though, it became unwieldy,
and I met someone who introduced me to Prisma and
Postgresql. Postgres is a relational database system, an extension of SQL, and
Prisma is a popular Javascript ORM (object-relational-mapping framework, used
for querying the database with JS-object-style calls instead of literal SQL
queries). I stored the posts and some resources in AWS S3 blob storage (flat ID
to file storage), which at first was a pain to set up but got easier as I
tinkered with the settings and began to understand how it (and auth) worked,
referencing the images of my posts with keys that I stored in the database. It
was a rabbit hole into my first full stack web app.
I originally was planning on just using basic CSS, but after stumbling upon
tailwind in a react guide I was reading, I decided that it was worth giving it a
shot. It was simple to get set up, and made styling the website much easier and
faster. Tailwind is a “utility-first” styling framework that provides a ton of
useful classes that pre-pack styles so that you can do the styling directly in
HTML instead of ever needing any CSS, sort of like bootstrap. For example, to
add a bit of padding to the left of a div, you can simply add the class
“pl-3”. It has classes for pretty much every possible CSS style, and has
predetermined discrete choices for sizes and colors (which can be customized,
but in general help development more than hurt).
One fun thing I came across when designing the homepage UX is Typewriter.js, a library for simulating typing. I thought it’d be a cool affect to apply to headers on my site, and then later experimented with other animations and animation frameworks a bit. It lets you do typewriter animations in a very nice modonic style.
typewriter
.typeString('Hello World!')
.pauseFor(2500)
.deleteAll()
.typeString('Strings can be removed')
.pauseFor(2500)
.deleteChars(7)
.start()Post Management
One of the key features of my website is its integrated post management system.
Though originally my purpose was to just have a collection of my projects on the
site, as a portfolio of sorts, I decided to also add the ability to post blogs
too. All posts on the site are of a specific type, either project or blog.
By going to the pattern matched URL https://404wolf.com/posts/<type>s, you can
view all posts of a specific type. Each post has a specific schema, which is
used to generate a grid of tiles that present post previews.
interface PostData {
coverUrl: string | null
coverAlt: string | null
id: string
title: string
description: string
date: string
tags: string[]
}
The posts themselves store this metadata in the database, and have corresponding
markdown files in S3. When the page is loaded to view a post, the S3 markdown is
prefetched, and is rendered client side. I use
react-markdown to render the
markdown, with some custom overrides to handle images and codeblocks. I talk
about this more in this blog I wrote, but I’ve also
added image blocks to markdown, to allow for groups of many images to show up
inline in the rendered markdown, by actually toying with the markdown to html
AST process.
Post editor
To edit my posts, I decided to add an integrated editor into my website. This is
because I want the website to automatically handle storage of associated post
resources (images, files, markdown versions, etc.), rather than having to
manually deal with uploading things to S3 and directly using the hard S3 links.
My goal was to be able to reference the resources by keys (unique IDs I assign
to them) directly in the markdown, and by integrating the editor into the
website I’ve made it possible to have a what-you-see-is-what-you-get markdown
editing system where the markdown automatically replaces aliases live. The
actual post-editing page is quite complex since it includes many different
fields to enter metadata for the project post, a split screen viewing panel, and
a resource panel. The most notable part, seen in the Editable S3 text area
image above, is I’ve made a component to directly edit an AWS S3 file with
simple text area entry that is capable of displaying images and other artifacts
as rendered markdown.
This system of using IDs was done with keys that are required to be unique by
the user, which is probably not the ideal way of doing it — I was manually
naming files uniquely. I decided to solve this problem by making all posts
upload with a unique ID automatically based on their filename, by appending
000n to the end, like filename_0004.png. It’s a bit clunky and requires
iteration to find an unused file name, but it works for now.
Exporting/importing
In general, I don’t like locking myself into ecosystems, so from the beginning I
knew I wanted a system to export the contents of the site. This website
obviously relies on the hosting of various different cloud providers, which,
though reliable, are fail points. When I created the post editing system, I also
wrote two basic scripts to upload and download the all the posts and their
respective metadata. All files associated with a specific post get stored in a
folder alongside the post’s markdown, and the metadata is saved as a simple
json. Writing these scripts was rather simple, since I’m iteratively doing a
database call for each post to download all the resources using the public S3
URL, and my ORM can give me a metadata json automatically. This script was made
obsolete by my new Obsidian plugin for the website, though.
Obsidian Plugin
Coming soon!
Teasers
