SpaceGirl | Making a Naive Blog from Scratch

Not quite sure what I have planned here, but I saw a post on X today that made me think:

For years, I've always had made plans for projects to build cooped up inside my head. Sometimes I would try them out (usually by making some prototype), learn a little something then move onto the next thing, having never written down my experience building said project (a lot of the times not even committing the source anywhere). This approach to learning stuff for me has worked out pretty well. But, there have been times were I've wanted to recall something from a project I've built or some tool I had fiddled with in the past. GPU Passthrough with Linux virtual machines comes to mind. So much ethereal knowledge gained to get the task I was aiming for complete, but lost to time whenever I want to go back and modify it.

That's where this "blog" (what does this word even mean anymore?) comes in. I think I want it to be a rambling place to store esoteric knowledge gained from hours of research on a topic so I can reference it whenever. And maybe it'll also be a research short-cut for other people (kudos to you if you're reading some guy's blog on a website thats header is "SpaceGirl").

How you're reading this

I know there are a billion tools made over the decades that make it quick and easy to build a blog. But that wouldn't be any fun would it? The whole reason why I make anything software related is because I enjoy the process of making it. If I just used some off-the-shelf tool like WordPress (no offense to them), it would feel like I'm back in college writing for the sake of putting words on a screen. Which is why I decided to just roll it from scratch (which really isn't that much work btw, you'd be surprised how simple it is to build bespoke ¹ software).

I literally wrote this little web-server in an evening (helps when your day job is building B2B SaaS) in Rust (I swear I don't have blue hair) with Axum. It's about as simple as a web-server can get, it serves files in a directory, but since I wanted to write stuff in Markdown, it has to compile the Markdown to HTML first. Luckily there is a little(?) crate called...markdown that actually handles the compiling.

"But wait? I thought you wanted to build it from scratch? What's with these dependencies? You practically just glued things together!"

And you wouldn't be wrong in saying that. The answer I have is:

Been there. Done that.

I've written from scratch an HTTP/1.1 server before, I already scratched that itch, so I don't feel bad about not making this part myself. I can also (sorta) say the same for the Markdown compiler. I've written a toy (read crappy) compiler before and (for the sake of not immediately killing my motivation to build this blog) don't feel the need to do that either ².

So with that out of the way, there are actually some interesting choices to think about when writing an HTML templating engine (that's basically what this site is).

• Do you want to cache, in-memory, all the pages at startup so you aren't doing disk reads with every request?
  • If you cache them what do you need to do when you want to add/update a post? (do you restart the web-server manually? a sketchy endpoint? mark posts as stale after a while and re-fetch them from disk?)
• How far do you want to go with flexibility of the templating?
  • Do you want variables? Or just straight copy-paste?
  • Do you write a compiler for it ³?

(Hmm. I thought I had more and cooler choices to list there, but whatever)

As I said, I want to write (almost) everything myself with my personal projects. So to prove that, I'll show you some code that you definitely have never seen anywhere (because its awful):

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

impl Post {
    fn to_html(&self, templates: &HashMap<String, Cached<Template>>) -> String {
        let mut s = String::with_capacity(self.content.len());
        if let Some(template) = self
            .embed_template_name
            .as_ref()
            .and_then(|name| templates.get(name))
        {
            if template.data.index > 0 {
                s += &template.data.content[0..template.data.index];
            }

            s += &markdown::to_html(&self.content);

            if template.data.index > 0 {
                s += &template.data.content[template.data.index + 3..]
            }
        } else {
            s += &markdown::to_html(&self.content);
        }

        s
    }
}

This wouldn't be a blog from a software dev without showing some jank code now would it? What you see there is how the markdown text gets translated into html (if you couldn't read the markdown::to_html() fn call). But this is also how you can embed HTML around the markdown. If you get past the ugliness of that, basically a Post can reference an embed_template_name, which is just the name of some template file (parsed at start up and stripped). Within that file you can define where the markdown will get inserted (which the web-server stores as a byte index into the contents of that file). For example:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

<html>
    <head>
        <title>SpaceGirl - Home</title>
    </head>
    <body>
        %%%

        <br/>
        (C) 2024 - Patrick Cleavelin
    </body>
</html>

The %%% denotes where to insert the markdown. In the markdown itself, you can define an (optional) template to use at the top of the file. Like so:

1

%{<name of template here>}

And it will then use that template when rendering the HTML.

Obviously there is a lot more to be done (and some boring stuff I left out). I mean, it's only 204 lines (minus deps), so it can only do so much, but at least it allows me to create this initial blog post. It honestly may even never get updated, that depends on if I want more fancier features or not.

Anyway, this was a lot more words than I originally thought I would write in this post (which is maybe the reason I need to make more of these?). I don't promise more of these, idk if I'll even deploy this thing. If you're reading this...thanks I guess? If I post again it'll probably be about game dev or something idk (I think I failed at "ignoring my non-existant audience")

EDIT 2024-09-30: Here is the repo for the web-server btw if you want to follow along.