Started on May 18, 2022. Published on May 5, 2022. Modified on May 24, 2022.
This contains my thoughts and design notes about the version 3 rebuild of basus.me. This is version 3, with the first version being the hand-rolled HTML and the second being generated from Pollen (with some HTML as well). I’m calling this a rebuild, rather than a redesign, because I’m not just changing the appearance of the site, but also how it is built, and the functions it serves.
Serve as (a basis for) a long-term repository for all my public writing online.
I want to eventually collect all the writing and posts I’ve made on other websites and platforms here. That would include (at the least) everything from The ByteBaker, my old Tumblr, my experiments with Write.as, and whatever other platforms I can remember and recover.
Allow for easy customization and styling.
I should be able to easily play around with colors, layouts, and types of pages without too much trouble. There should be some amount of separation of content and styling so that when I do migrate to a version 4, it can be done without having to touch all the content.
Encourage regular writing.
One of the big reasons for this rebuild is that I really miss writing online. I stopped for a myriad of reasons, including that the platforms I was using (WordPress and Write.as) had just enough mismatch with my own thinking, writing and publishing process to make writing unappealing. The site should be built in such a way that adding or editing material is easy and low-friction. Additionally, (and tying into point 1 above), it should be easy to repost things I post to say, Twitter or Instagram here.
Provide thoughts, inspiration and maybe an experimental playground for writing/publishing/thinking systems.
I don’t expect this version to be the final (or even close to final) version of the site. In fact, it’s explicitly a stopgap so that I can separate out actually writing and publishing from building the system that supports those activities. I expect that I will run into friction and dissatisfaction with the current systems I’m using and those will feed into building new tools. At the same time, I will try to work within in the limits of the current system to get as close to my ideal as possible.
Design and Implementation Decisions
- The site is built from Markdown files using Hugo. The
generated files are served by a basic webserver, Nginx, running on an Arch
Linux VPS. Hugo comes with a convenient server with live reload which makes
seeing design changes and drafts very easy. The publication function also
conveniently generates a separate output for easy deployment and backup. There
are some aspects of Hugo’s design which are awkward (like the use of magic
_index.mdfiles), and mixing Markdown and HTML is harder than it should be. It’s definitely not the end-all but it’s a good solution for now, a local maxima.
- Hugo mostly does a pretty good job of separating styling from content. The site’s design is implemented as a Hugo theme, while the content lives as Markdown files. The general design has been cobbled together from a number of places (see Influences below), and I expect to continue experimenting with it.
- The site is versioned and backed up in 3 different Git repos: one for the
content, one for the styling, and one for the final generated site. Having a
repo for the generated site allows for easy archiving. Putting all the content
into a single repo might not be the best idea since I might want to separate
out the different sections, but Git’s
filter-reposhould let me separate them out later. This leaves out the static files that Hugo insists on keeping separate from the site content. Right now there isn’t much in there, but I might turn that into an additional repo if it grows.
- Writing in Markdown is less than ideal, but again, is a local maxima for now. The upshot is that I can write in Emacs, (or Obsidian, for a mostly WYSIWYG experience) and not in some awkward online interface. On the other hand, I have to manage metadata like timestamps and tags manually, which is already annoying.
- The site is divided into a number of sections. For now the landing page has basic biographical information and “headlines” about what I’m up to. For now, this is the closest I want to get to a “now page”. The journal is a basic blog. Eventually content from The ByteBaker and my other experimental blogs should be migrated here. I have a notes section for, well, notes on various things that I want to be publicly available, but not maybe aren’t a coherent journal entry. I suspect that some journal entries will starts as notes. Eventually there will be a “stream” (based on Simon Collison’s stream), mainly as a mirror for my Twitter and Instagram accounts. It’s very likely that writing that as Markdown files may get awkward quickly.
- Being driven by Markdown files is a double-edged sword. On the one hand, it means I can write in Emacs and use all my keybindings and muscle memory. On the other, there is a lot of manual management of metadata etc. Even things like inserting links to other notes or posts is a bit of chore. Authoring in something like Obsidian does not fix this. (See Obsidian Impressions.)
- Another Markdown limitation: there isn’t an easy way to specify things that generate the same HTML tag, but are semantically different. For example, there is no way to generate separate markup (like adding HTML classes) for internal and external links.
- Relatedly, using Hugo means that working on the site requires bits and pieces of a variety of languages: HTML and CSS of course, Markdown, YAML for front-matter, and Hugo’s templating language (which I think is vaguely a stripped down version of Go?). I still hold on to hopes of one day tearing down the whole tower of Babel and writing everything in a single, conceptually unified language.
- Since Hugo’s taxonomies (like categories or tags) are site-wide, building the notes index page by iterating over tags also includes journal entries, which I don’t want.
- I’m not sure how to handle tags and/or categories, especially between the different parts of the site. I’m tempted to have a two-tier system like Simon Collison does. I would have to decide what the (small number of) categories should be.
- I’m a little concerned about the separation between stream, journal and essay. In particular, I’m not sure how often I will have something that could fit into multiple sections.
- Eventually I would like to be able to post from my phone, so that I can use the stream as a mirror of my Twitter and Instagram accounts.
- Think more about categories and tags
- Experiment with more color schemes
- Figure out the RSS setup. Right now it’s just whatever Hugo’s default is, and I probably won’t like it.
- Standardize names for components in the HTML (for example, the bit that shows the tags on various pages). This will make it easier to pull them out into as partials templates.
- Rob Weychert is probably the biggest single influence on the design and structure for v3. I’ve lifted his structure for color themes as well some of his rationale for having a site check-pointed by versions (especially by having each version have its own subdomain).
- Simon Collison has influenced the header design, and the idea of having different sections for different kinds of content, especially a “stream” section for short posts.
- Butterick’s Practical Typography inspired the sidebar layout that most individual pages use.
- Andre Garzia inspired me to finally embrace the chaos and publish this version once I got to a “good enough” state, rather than working out every detail.